# 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.

{% hint style="info" %}
API-level summary:

* Organisation-level and Partner-level keys are supported.
* Use `integrations:read` for GET endpoints and `integrations:write` for POST/PATCH endpoints.
  {% endhint %}

***

## 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)

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

### Example 1 response (partner-level key)

```json
{
  "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)

```bash
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)

```json
{
  "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

```bash
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

```json
{
  "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

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

### Example 4 response

```json
{
  "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"
    }
  ]
}
```

<details>

<summary>404 Not Found — Integration does not exist (example)</summary>

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

</details>

***

## 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

```bash
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

```json
{
  "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

<details>

<summary>401 Unauthorised (example)</summary>

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

</details>

<details>

<summary>403 Forbidden (missing ability) (example)</summary>

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

</details>

<details>

<summary>404 Not found (example)</summary>

Returned when the target organisation or integration is not found.

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

</details>

<details>

<summary>422 Unprocessable Entity (business validation) (example)</summary>

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

</details>

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`                                             |


---

# 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/integrations.md?ask=<question>
```

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.