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 for GET endpoints
integrations:write for POST and PATCH endpoints

integrations:read is enabled automatically for every API key. integrations:write is enabled automatically for organisation-level keys and admin partner-group keys. Non-admin partner-group keys get integrations:write only if their group has permission to manage organisation integrations.

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.

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`