# 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

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

### Example response

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

{% hint style="info" %}
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.
  {% endhint %}

### Example request

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

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

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

### Example response

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

<details>

<summary>Error responses</summary>

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

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

</details>

***

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

{% hint style="info" %}
Important behavior:

* Only `name` is updatable via this endpoint.
* `mode` is not updatable here.
* Attempting to update an inaccessible organisation returns `404`.
  {% endhint %}

### Example request

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

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

{% hint style="warning" %}
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
  {% endhint %}

### Example request

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

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

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

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

### 404 Not found

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

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

### 422 Unprocessable Entity

Used for business-rule and schema validation errors.

Example: business validation (delete blocked):

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


---

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