Memberships

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

Required abilities:

• memberships:read for GET endpoints

• memberships:write for POST, PATCH, and DELETE endpoints

Access scope model:

• Admin partner-group keys can access memberships across all organisations belonging to their partner.

• Non-admin partner-group keys can access memberships only in organisations explicitly assigned to their group.

• Organisation-level keys receive 401 Unauthorised on all endpoints in this API.

---

GET /v1/memberships - List memberships

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

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

Query parameters

Parameter	Type	Description
organisation_id	string	Filter by exact organisation ID
limit	integer	Number of results per page
offset	integer	Number of results to skip

Results are ordered by created_at descending.

Example request

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

Example response

{
  "items": [
    {
      "id": "mem_abc123",
      "organisation_id": "org_xyz456",
      "user_id": "usr_aaa111",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "role": "ADMIN",
      "is_alert_action_required_email_enabled": true,
      "is_alert_resolved_email_enabled": true,
      "is_alert_dismissed_email_enabled": true,
      "is_evidence_requested_email_enabled": true,
      "created_at": "2026-02-10T09:30:00Z",
      "updated_at": "2026-02-10T09:30:00Z"
    },
    {
      "id": "mem_def456",
      "organisation_id": "org_xyz456",
      "user_id": "usr_bbb222",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "[email protected]",
      "role": "STANDARD",
      "is_alert_action_required_email_enabled": true,
      "is_alert_resolved_email_enabled": false,
      "is_alert_dismissed_email_enabled": false,
      "is_evidence_requested_email_enabled": true,
      "created_at": "2026-02-08T15:12:44Z",
      "updated_at": "2026-02-08T15:12:44Z"
    }
  ],
  "count": 2
}

---

POST /v1/memberships - Create membership

Create a new membership for an accessible organisation.

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

Request body

Field	Type	Required	Validation	Description
organisation_id	string	Yes	Must be accessible by API key	Organisation that owns the membership
first_name	string	Yes	Min length 1	User first name
last_name	string	Yes	Min length 1	User last name
email	string	Yes	Valid email format	User email
role	string	Yes	ADMIN or STANDARD	Membership role
is_alert_action_required_email_enabled	boolean	No	Defaults to true	Alert action-required email setting
is_alert_resolved_email_enabled	boolean	No	Defaults to true	Alert resolved email setting
is_alert_dismissed_email_enabled	boolean	No	Defaults to true	Alert dismissed email setting
is_evidence_requested_email_enabled	boolean	No	Defaults to true	Evidence requested email setting

• If the user is already a member of the organisation, the API returns 422 with MEMBERSHIP_ALREADY_EXISTS.

• Notification setting values provided in the request are applied as sent.

Example request

curl -X POST "https://api.chargebackstop.com/v1/memberships/" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_xyz456",
    "first_name": "Alice",
    "last_name": "Johnson",
    "email": "[email protected]",
    "role": "ADMIN",
    "is_alert_action_required_email_enabled": true,
    "is_alert_resolved_email_enabled": false,
    "is_alert_dismissed_email_enabled": true,
    "is_evidence_requested_email_enabled": true
  }'

Example response

{
  "id": "mem_new123",
  "organisation_id": "org_xyz456",
  "user_id": "usr_new123",
  "first_name": "Alice",
  "last_name": "Johnson",
  "email": "[email protected]",
  "role": "ADMIN",
  "is_alert_action_required_email_enabled": true,
  "is_alert_resolved_email_enabled": false,
  "is_alert_dismissed_email_enabled": true,
  "is_evidence_requested_email_enabled": true,
  "created_at": "2026-02-16T12:00:00Z",
  "updated_at": "2026-02-16T12:00:00Z"
}

---

GET /v1/memberships/{membership_id} - Get membership by ID

Retrieve one accessible membership by ID.

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

URL parameters

Parameter	Type	Description
membership_id	string	Membership ID

Example request

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

Example response

{
  "id": "mem_abc123",
  "organisation_id": "org_xyz456",
  "user_id": "usr_aaa111",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "role": "ADMIN",
  "is_alert_action_required_email_enabled": true,
  "is_alert_resolved_email_enabled": true,
  "is_alert_dismissed_email_enabled": true,
  "is_evidence_requested_email_enabled": true,
  "created_at": "2026-02-10T09:30:00Z",
  "updated_at": "2026-02-16T09:05:00Z"
}

---

PATCH /v1/memberships/{membership_id} - Update membership

Update one accessible membership.

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

URL parameters

Parameter	Type	Description
membership_id	string	Membership ID to update

Request body

All fields are optional.

Field	Type	Required	Validation	Description
role	string	No	ADMIN or STANDARD	Updated membership role
is_alert_action_required_email_enabled	boolean	No	Optional	Updated alert action-required email setting
is_alert_resolved_email_enabled	boolean	No	Optional	Updated alert resolved email setting
is_alert_dismissed_email_enabled	boolean	No	Optional	Updated alert dismissed email setting
is_evidence_requested_email_enabled	boolean	No	Optional	Updated evidence requested email setting

• Only fields included in the request are updated.

• If no fields are provided, the API returns the existing membership unchanged.

Example request

curl -X PATCH "https://api.chargebackstop.com/v1/memberships/mem_abc123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "STANDARD",
    "is_alert_resolved_email_enabled": false,
    "is_alert_dismissed_email_enabled": false
  }'

Example response

{
  "id": "mem_abc123",
  "organisation_id": "org_xyz456",
  "user_id": "usr_aaa111",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "role": "STANDARD",
  "is_alert_action_required_email_enabled": true,
  "is_alert_resolved_email_enabled": false,
  "is_alert_dismissed_email_enabled": false,
  "is_evidence_requested_email_enabled": true,
  "created_at": "2026-02-10T09:30:00Z",
  "updated_at": "2026-02-16T12:10:00Z"
}

---

DELETE /v1/memberships/{membership_id} - Delete membership

Delete one accessible membership.

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

URL parameters

Parameter	Type	Description
membership_id	string	Membership ID to delete

Example request

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

Example response

204 No Content

---

Common error responses

400 Invalid request

Returned when a membership cannot be created for the target user (for example, a staff user).

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

401 Unauthorised

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

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

404 Not found

Returned when the membership is not found or outside the key's accessible scope.

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

422 Unprocessable Entity (membership already exists)

{
  "errors": [
    {
      "code": "MEMBERSHIP_ALREADY_EXISTS",
      "message": "A user with this email is already a member of this organisation"
    }
  ]
}

422 Unprocessable Entity (membership deletion forbidden)

{
  "errors": [
    {
      "code": "MEMBERSHIP_DELETION_FORBIDDEN",
      "message": "This membership cannot be deleted"
    }
  ]
}

Other business validation codes you may receive:

Code	Meaning
MEMBERSHIP_ALREADY_EXISTS	A membership for this user and organisation already exists
MEMBERSHIP_DELETION_FORBIDDEN	Membership cannot be deleted due to business rules

Schema validation errors are also returned as 422 with VALIDATION_* codes.