# 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 | {% hint style="info" %} When `sort` is omitted, results are ordered by `created_at` descending. {% endhint %} ### Example request ```bash curl -X GET "https://api.chargebackstop.com/v1/merchants/?limit=20&offset=0&sort=-created_at" \ -H "Authorization: Bearer " ``` ### Example response ```json { "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. | {% hint style="info" %} If you do not use ChargebackStop representment/disputes workflows, skip `default_representment_service_type`. {% endhint %} ### Example request ```bash curl -X POST "https://api.chargebackstop.com/v1/merchants/" \ -H "Authorization: Bearer " \ -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 ```json { "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 ```bash curl -X GET "https://api.chargebackstop.com/v1/merchants/mrch_abc123" \ -H "Authorization: Bearer " ``` ### Example response ```json { "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. | {% hint style="info" %} * 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`. {% endhint %} ### Example request ```bash curl -X PATCH "https://api.chargebackstop.com/v1/merchants/mrch_abc123" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Stripe Europe", "external_id": "acct_eu_010", "default_representment_service_type": "ONLINE_SERVICES" }' ``` ### Example response ```json { "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 | {% hint style="info" %} Deletion is blocked when the merchant has related enrolments or alerts. {% endhint %} ### Example request ```bash curl -X DELETE "https://api.chargebackstop.com/v1/merchants/mrch_abc123" \ -H "Authorization: Bearer " ``` ### 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. ```json { "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`). ```json { "errors": [ { "code": "FORBIDDEN", "message": "Forbidden" } ] } ``` ### 404 Not found Returned when the merchant is not found. ```json { "errors": [ { "code": "NOT_FOUND", "message": "Not found" } ] } ``` ### 422 Unprocessable Entity (merchant type change restricted) ```json { "errors": [ { "code": "MERCHANT_TYPE_CHANGE_RESTRICTED", "message": "Cannot change merchant type when integrations are associated with this merchant." } ] } ``` ### 422 Unprocessable Entity (merchant deletion restricted) ```json { "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 | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.chargebackstop.com/developer/api-documentation/merchants.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.