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
`organisation_id`	string	Filter by organisation ID
`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

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",
      "links": [
        {
          "rel": "self",
          "uri": "/v1/merchants/mrch_abc123"
        }
      ]
    },
    {
      "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",
      "links": [
        {
          "rel": "self",
          "uri": "/v1/merchants/mrch_def789"
        }
      ]
    }
  ],
  "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.

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",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/merchants/mrch_new123"
    }
  ]
}

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",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/merchants/mrch_abc123"
    }
  ]
}

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.

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",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/merchants/mrch_abc123"
    }
  ]
}

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

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