Integrations

Manage integrations used by ChargebackStop APIs.

This endpoint set currently supports creating and managing CUSTOM_ORDERS integrations, and listing all integrations your API key can access.

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

This endpoint set supports both organisation-level and partner-level keys.

integrations:read and integrations:write are enabled automatically for every API key.

• integrations:read for GET endpoints

• integrations:write for POST and PATCH endpoints

Access scope model:

• Organisation-level keys can access integrations for their own organisation only.

• Admin partner-group keys can access integrations across all organisations for their partner.

• Non-admin partner-group keys can access integrations only for organisations assigned to their group.

API-level summary:

• Organisation-level and Partner-level keys are supported.

• Use integrations:read for GET endpoints and integrations:write for POST/PATCH endpoints.

---

GET /v1/integrations - List integrations

Returns integrations from organisations accessible to the API key.

API level: Organisation-level and Partner-level Authentication: integrations:read

Query parameters

No custom filters are currently supported.

Pagination parameters are supported:

Parameter	Type	Description
limit	integer	Number of results per page
offset	integer	Number of results to skip

Example 1 request (partner-level key)

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

Example 1 response (partner-level key)

{
  "items": [
    {
      "id": "int_abc123",
      "organisation_id": "org_xyz456",
      "name": "Orders API Integration",
      "type": "CUSTOM_ORDERS",
      "status": "ENABLED",
      "merchant_ids": ["mrch_111", "mrch_222"],
      "links": [
        {
          "rel": "self",
          "uri": "/v1/integrations/int_abc123"
        }
      ]
    },
    {
      "id": "int_def789",
      "organisation_id": "org_xyz456",
      "name": "Stripe Main",
      "type": "STRIPE",
      "status": "ENABLED",
      "merchant_ids": ["mrch_111"],
      "links": [
        {
          "rel": "self",
          "uri": "/v1/integrations/int_def789"
        }
      ]
    }
  ],
  "count": 2
}

Example 2 request (organisation-level key)

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

Example 2 response (organisation-level key)

{
  "items": [
    {
      "id": "int_abc123",
      "organisation_id": "org_xyz456",
      "name": "Orders API Integration",
      "type": "CUSTOM_ORDERS",
      "status": "ENABLED",
      "merchant_ids": ["mrch_111", "mrch_222"],
      "links": [
        {
          "rel": "self",
          "uri": "/v1/integrations/int_abc123"
        }
      ]
    }
  ],
  "count": 1
}

---

POST /v1/integrations - Create integration

Create a new integration.

API level: Organisation-level and Partner-level Authentication: integrations:write

Request body

Field	Type	Required	Validation	Description
organisation_id	string	Yes	Must be accessible by API key	Organisation that owns the integration
name	string	Yes	1-255 chars	Integration display name
type	string	Yes	Must be CUSTOM_ORDERS	Integration type
status	string	No	ENABLED or DISABLED	Initial integration status
merchant_ids	array[string]	Yes	Non-empty, unique, all merchants must belong to organisation_id and be accessible	Merchants linked to this integration

Status behavior on create:

• If status is omitted, integrations are created with status: ENABLED.

Example 3 request

curl -X POST "https://api.chargebackstop.com/v1/integrations/" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_xyz456",
    "name": "Orders API Integration",
    "type": "CUSTOM_ORDERS",
    "status": "DISABLED",
    "merchant_ids": ["mrch_111", "mrch_222"]
  }'

Example 3 response

{
  "id": "int_abc123",
  "organisation_id": "org_xyz456",
  "name": "Orders API Integration",
  "type": "CUSTOM_ORDERS",
  "status": "DISABLED",
  "merchant_ids": ["mrch_111", "mrch_222"],
  "links": [
    {
      "rel": "self",
      "uri": "/v1/integrations/int_abc123"
    }
  ]
}

---

GET /v1/integrations/{integration_id} - Get integration by ID

Retrieve a single integration by ID.

API level: Organisation-level and Partner-level Authentication: integrations:read

URL parameters

Parameter	Type	Description
integration_id	string	Integration ID

Example 4 request

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

Example 4 response

{
  "id": "int_abc123",
  "organisation_id": "org_xyz456",
  "name": "Orders API Integration",
  "type": "CUSTOM_ORDERS",
  "status": "ENABLED",
  "merchant_ids": ["mrch_111", "mrch_222"],
  "links": [
    {
      "rel": "self",
      "uri": "/v1/integrations/int_abc123"
    }
  ]
}

404 Not Found — Integration does not exist (example)

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

---

PATCH /v1/integrations/{integration_id} - Update integration

Update an existing integration.

API level: Organisation-level and Partner-level Authentication: integrations:write

Important behavior

• status updates are only allowed for CUSTOM_ORDERS integrations.

• The only allowed status value in PATCH is DISABLED.

• name can be updated.

• You must provide at least one of status or name.

URL parameters

Parameter	Type	Description
integration_id	string	Integration ID to update

Request body

Field	Type	Required	Validation	Description
status	string	No	DISABLED only; only for CUSTOM_ORDERS integrations	New integration status
name	string	No	1-255 chars	New integration name

Example 5 request

curl -X PATCH "https://api.chargebackstop.com/v1/integrations/int_abc123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Orders API Integration - EU"
  }'

Example 5 response

{
  "id": "int_abc123",
  "organisation_id": "org_xyz456",
  "name": "Orders API Integration - EU",
  "type": "CUSTOM_ORDERS",
  "status": "DISABLED",
  "merchant_ids": ["mrch_111", "mrch_222"],
  "links": [
    {
      "rel": "self",
      "uri": "/v1/integrations/int_abc123"
    }
  ]
}

---

Common error responses

401 Unauthorised (example)

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

403 Forbidden (missing ability) (example)

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

404 Not found (example)

Returned when the target organisation or integration is not found.

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

422 Unprocessable Entity (business validation) (example)

{
  "errors": [
    {
      "code": "INVALID_MERCHANT_IDS",
      "message": "One or more merchant_ids are invalid or inaccessible for this organisation"
    }
  ]
}

Other business validation codes you may receive:

Code	Meaning
DUPLICATE_MERCHANT_IDS	merchant_ids contains duplicate values
INVALID_MERCHANT_IDS	One or more merchants do not exist, are inaccessible, or do not belong to the provided organisation
INVALID_INTEGRATION_TYPE	PATCH attempted on a non-CUSTOM_ORDERS integration
MISSING_UPDATE_FIELDS	PATCH request did not include either status or name