Merchants

Manage merchants under your partner account.

This endpoint set is partner-level only. Organisation API keys cannot access these endpoints.

Base URL: https://api.chargebackstop.com/v1/merchants/ Authentication: Bearer token via API key.

Required abilities:

• merchants:read for GET endpoints

• merchants:write for POST, PATCH, and DELETE endpoints

Access scope model:

• Admin partner-group keys can access merchants across all organisations belonging to their partner.

• Non-admin partner-group keys can access merchants only in organisations explicitly assigned to their group.

• Organisation-level keys receive 401 Unauthorised on all endpoints in this API.

---

GET /v1/merchants - List merchants

Returns merchants accessible to the authenticated partner-group API key.

API level: Partner-level only Authentication: merchants:read

Query parameters

Parameter	Type	Description
type	string	Filter by merchant type
name	string	Case-insensitive partial match on merchant name
external_id	string	Filter by exact external merchant ID
sort	string	Sort field: name, type, created_at, updated_at; prefix with - for descending
limit	integer	Number of results per page
offset	integer	Number of results to skip

When sort is omitted, results are ordered by created_at descending.

Example request

curl -X GET "https://api.chargebackstop.com/v1/merchants/?limit=20&offset=0&sort=-created_at" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "items": [
    {
      "id": "mrch_abc123",
      "organisation_id": "org_xyz456",
      "name": "Acme Stripe EU",
      "type": "STRIPE",
      "external_id": "acct_eu_001",
      "default_representment_service_type": "PHYSICAL_GOODS",
      "created_at": "2026-02-10T09:30:00Z",
      "updated_at": "2026-02-10T09:30:00Z"
    },
    {
      "id": "mrch_def789",
      "organisation_id": "org_xyz456",
      "name": "Acme Adyen UK",
      "type": "ADYEN",
      "external_id": null,
      "default_representment_service_type": null,
      "created_at": "2026-02-08T15:12:44Z",
      "updated_at": "2026-02-08T15:12:44Z"
    }
  ],
  "count": 2
}

---

POST /v1/merchants - Create merchant

Create a new merchant for an accessible organisation.

API level: Partner-level only Authentication: merchants:write

Request body

Field	Type	Required	Validation	Description
organisation_id	string	Yes	Must be accessible by API key	Organisation that owns the merchant
name	string	Yes	Min length 1	Merchant display name
type	string	Yes	Must be a supported merchant type	Merchant type
external_id	string	No	Max length 250	Optional external merchant ID
default_representment_service_type	string	No	PHYSICAL_GOODS, ONLINE_SERVICES, or OFFLINE_SERVICES	Default representment service type. If you do not use ChargebackStop representment/disputes workflows, omit this field.

If you do not use ChargebackStop representment/disputes workflows, skip default_representment_service_type.

Example request

curl -X POST "https://api.chargebackstop.com/v1/merchants/" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_xyz456",
    "name": "Acme Stripe US",
    "type": "STRIPE",
    "external_id": "acct_us_002",
    "default_representment_service_type": "PHYSICAL_GOODS"
  }'

Example response

{
  "id": "mrch_new123",
  "organisation_id": "org_xyz456",
  "name": "Acme Stripe US",
  "type": "STRIPE",
  "external_id": "acct_us_002",
  "default_representment_service_type": "PHYSICAL_GOODS",
  "created_at": "2026-02-16T12:00:00Z",
  "updated_at": "2026-02-16T12:00:00Z"
}

---

GET /v1/merchants/{merchant_id} - Get merchant by ID

Retrieve one accessible merchant by ID.

API level: Partner-level only Authentication: merchants:read

URL parameters

Parameter	Type	Description
merchant_id	string	Merchant ID

Example request

curl -X GET "https://api.chargebackstop.com/v1/merchants/mrch_abc123" \
  -H "Authorization: Bearer <api_key>"

Example response

{
  "id": "mrch_abc123",
  "organisation_id": "org_xyz456",
  "name": "Acme Stripe EU",
  "type": "STRIPE",
  "external_id": "acct_eu_001",
  "default_representment_service_type": "PHYSICAL_GOODS",
  "created_at": "2026-02-10T09:30:00Z",
  "updated_at": "2026-02-16T09:05:00Z"
}

---

PATCH /v1/merchants/{merchant_id} - Update merchant

Update one accessible merchant.

API level: Partner-level only Authentication: merchants:write

URL parameters

Parameter	Type	Description
merchant_id	string	Merchant ID to update

Request body

At least one field should be provided.

Field	Type	Required	Validation	Description
name	string	No	Min length 1	Updated merchant name
type	string	No	Must be a supported merchant type	Updated merchant type
external_id	string or null	No	Optional	Updated external ID (null clears value)
default_representment_service_type	string or null	No	PHYSICAL_GOODS, ONLINE_SERVICES, OFFLINE_SERVICES, or null	Updated default representment service type. If you do not use ChargebackStop representment/disputes workflows, omit this field.

• Merchant type changes are blocked when related integrations, enrolments, or data providers exist.

• Other fields can still be updated when type changes are blocked.

• If you do not use ChargebackStop representment/disputes workflows, skip default_representment_service_type.

Example request

curl -X PATCH "https://api.chargebackstop.com/v1/merchants/mrch_abc123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Stripe Europe",
    "external_id": "acct_eu_010",
    "default_representment_service_type": "ONLINE_SERVICES"
  }'

Example response

{
  "id": "mrch_abc123",
  "organisation_id": "org_xyz456",
  "name": "Acme Stripe Europe",
  "type": "STRIPE",
  "external_id": "acct_eu_010",
  "default_representment_service_type": "ONLINE_SERVICES",
  "created_at": "2026-02-10T09:30:00Z",
  "updated_at": "2026-02-16T12:10:00Z"
}

---

DELETE /v1/merchants/{merchant_id} - Delete merchant

Delete one accessible merchant.

API level: Partner-level only Authentication: merchants:write

URL parameters

Parameter	Type	Description
merchant_id	string	Merchant ID to delete

Deletion is blocked when the merchant has related enrolments or alerts.

Example request

curl -X DELETE "https://api.chargebackstop.com/v1/merchants/mrch_abc123" \
  -H "Authorization: Bearer <api_key>"

Example response

204 No Content

---

Common error responses

401 Unauthorised

Returned for invalid or expired API keys, and for organisation-level keys calling this partner-only API.

{
  "errors": [
    {
      "code": "UNAUTHORISED",
      "message": "Unauthorised"
    }
  ]
}

403 Forbidden (missing ability)

Returned when the API key is valid but missing required ability (merchants:read or merchants:write).

{
  "errors": [
    {
      "code": "FORBIDDEN",
      "message": "Forbidden"
    }
  ]
}

404 Not found

Returned when the merchant is not found.

{
  "errors": [
    {
      "code": "NOT_FOUND",
      "message": "Not found"
    }
  ]
}

422 Unprocessable Entity (merchant type change restricted)

{
  "errors": [
    {
      "code": "MERCHANT_TYPE_CHANGE_RESTRICTED",
      "message": "Cannot change merchant type when integrations are associated with this merchant."
    }
  ]
}

422 Unprocessable Entity (merchant deletion restricted)

{
  "errors": [
    {
      "code": "MERCHANT_DELETION_RESTRICTED",
      "message": "Merchant cannot be deleted because it has active enrollments. Please contact support if you need to delete this merchant."
    }
  ]
}

Other business validation codes you may receive:

Code	Meaning
INVALID_MERCHANT_TYPE	type is not a valid merchant type
INVALID_REPRESENTMENT_SERVICE_TYPE	default_representment_service_type is not valid
MERCHANT_TYPE_CHANGE_RESTRICTED	Requested type change is blocked by related records
MERCHANT_DELETION_RESTRICTED	Merchant cannot be deleted due to related records