Organisations

Manage organisations 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/organisations/
Authentication: Bearer token via API key.

Required abilities:

• organisations:read for GET endpoints
• organisations:write for POST, PATCH, and DELETE endpoints

Access scope model:

• Admin partner-group keys can access all organisations belonging to their partner.
• Non-admin partner-group keys can access only organisations explicitly assigned to their group.
• Organisation-level keys receive 401 Unauthorised on all endpoints in this API.

---

GET /v1/organisations - List organisations

Returns organisations accessible to the authenticated partner-group API key.

Because organisation mode must match partner mode on create, results for a given partner key are expected to be single-mode (LIVE or TEST).

API level: Partner-level only
Authentication: organisations:read

Query parameters

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

Example request

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

Example response

{
  "items": [
    {
      "id": "org_abc123",
      "name": "Acme Payments",
      "mode": "LIVE",
      "created_at": "2026-01-10T10:45:12Z",
      "updated_at": "2026-01-10T10:45:12Z",
      "links": [
        {
          "rel": "self",
          "uri": "/v1/organisations/org_abc123"
        }
      ]
    },
    {
      "id": "org_def456",
      "name": "Acme Payments EU",
      "mode": "LIVE",
      "created_at": "2026-01-11T09:12:00Z",
      "updated_at": "2026-01-11T09:12:00Z",
      "links": [
        {
          "rel": "self",
          "uri": "/v1/organisations/org_def456"
        }
      ]
    }
  ],
  "count": 2
}

---

POST /v1/organisations - Create organisation

Create a new organisation for the authenticated partner.

API level: Partner-level only
Authentication: organisations:write

Request body

Field	Type	Required	Validation	Description
name	string	Yes	Min length 1	Public organisation name

Note

Important behavior:

• Organisation mode always follows the partner's mode.
• If resulting mode is TEST and name does not already start with [TEST], the API prefixes the name with [TEST] automatically.
• If name already starts with [TEST], no duplicate prefix is added.
• The API removes spaces from the start and end of name.
• name must be unique within the partner, and the comparison ignores case. The check includes organisations that your key cannot access. If the name is already in use, the API returns 422 with the code DUPLICATE_ORGANISATION_NAME.

Example request

curl -X POST "https://api.chargebackstop.com/v1/organisations/" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Organisation"
  }'

Example response

{
  "id": "org_new123",
  "name": "New Organisation",
  "mode": "LIVE",
  "created_at": "2026-02-16T12:00:00Z",
  "updated_at": "2026-02-16T12:00:00Z",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/organisations/org_new123"
    }
  ]
}

---

GET /v1/organisations/{organisation_id} - Get organisation by ID

Retrieve one accessible organisation by ID.

API level: Partner-level only
Authentication: organisations:read

URL parameters

Parameter	Type	Description
organisation_id	string	Organisation ID

Example request

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

Example response

{
  "id": "org_abc123",
  "name": "Acme Payments",
  "mode": "LIVE",
  "created_at": "2026-01-10T10:45:12Z",
  "updated_at": "2026-01-15T08:00:00Z",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/organisations/org_abc123"
    }
  ]
}

Error responses

404 Not Found - Organisation does not exist or is not accessible to this key:

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

---

PATCH /v1/organisations/{organisation_id} - Update organisation

Update organisation details.

API level: Partner-level only
Authentication: organisations:write

URL parameters

Parameter	Type	Description
organisation_id	string	Organisation ID to update

Request body

Field	Type	Required	Validation	Description
name	string	Yes	Min length 1	Updated public organisation name

Note

Important behavior:

• Only name is updatable via this endpoint.
• mode is not updatable here.
• Attempting to update an inaccessible organisation returns 404.
• The API removes spaces from the start and end of name.
• name must be unique within the partner, and the comparison ignores case. The check includes organisations that your key cannot access. If the name is already in use, the API returns 422 with the code DUPLICATE_ORGANISATION_NAME.

Example request

curl -X PATCH "https://api.chargebackstop.com/v1/organisations/org_abc123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Payments UK"
  }'

Example response

{
  "id": "org_abc123",
  "name": "Acme Payments UK",
  "mode": "LIVE",
  "created_at": "2026-01-10T10:45:12Z",
  "updated_at": "2026-02-16T12:10:00Z",
  "links": [
    {
      "rel": "self",
      "uri": "/v1/organisations/org_abc123"
    }
  ]
}

---

DELETE /v1/organisations/{organisation_id} - Delete organisation

Delete an organisation if it has no related dependent records.

API level: Partner-level only
Authentication: organisations:write

URL parameters

Parameter	Type	Description
organisation_id	string	Organisation ID to delete

Caution

Important behavior:

• Deletion is blocked if the organisation still has related data. In those cases, API returns 422.

Blocking checks include:

• Merchants
• Network alert enrolments
• Integrations
• Data providers
• Alerts

Example request

curl -X DELETE "https://api.chargebackstop.com/v1/organisations/org_abc123" \
  -H "Authorization: Bearer <api_key>"

Example response

204 No Content

---

Common error responses

400 Invalid request

{
  "errors": [
    {
      "code": "INVALID_REQUEST",
      "message": "Invalid request"
    }
  ]
}

401 Unauthorised

Returned for invalid/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 (organisations:read or organisations:write).

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

404 Not found

Returned when the organisation does not exist or is outside the key's accessible scope.

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

422 Unprocessable Entity

Used for business-rule and schema validation errors.

Example: business validation (delete blocked):

{
  "errors": [
    {
      "code": "HAS_MERCHANTS",
      "message": "The organisation has merchants. Please contact customer support to delete this organisation."
    }
  ]
}

Example: business validation (duplicate name):

{
  "errors": [
    {
      "code": "DUPLICATE_ORGANISATION_NAME",
      "message": "An organisation named 'Acme Payments' already exists for this partner."
    }
  ]
}

Other business validation codes you may receive:

Code	Meaning
DUPLICATE_ORGANISATION_NAME	The partner already has an organisation with this name
HAS_MERCHANTS	Organisation has merchants and cannot be deleted
HAS_ENROLMENTS	Organisation has active enrolments and cannot be deleted
HAS_INTEGRATIONS	Organisation has integrations and cannot be deleted
HAS_DATA_PROVIDERS	Organisation has data providers and cannot be deleted
HAS_ALERTS	Organisation has alerts and cannot be deleted

Schema validation errors are also returned as 422 with VALIDATION_* codes (for example, invalid field values or empty name).