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"
    },
    {
      "id": "org_def456",
      "name": "Acme Payments EU",
      "mode": "LIVE",
      "created_at": "2026-01-11T09:12:00Z",
      "updated_at": "2026-01-11T09:12:00Z"
    }
  ],
  "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

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.

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"
}

---

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"
}

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

Important behavior:

• Only name is updatable via this endpoint.

• mode is not updatable here.

• Attempting to update an inaccessible organisation returns 404.

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"
}

---

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

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."
    }
  ]
}

Other business validation codes you may receive:

Code	Meaning
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).