Rulesets - developer preview

Create and manage resolution rulesets and their child rules.

Base URL: https://api.chargebackstop.com/v1/rulesets/

Authentication: Bearer token via API key.

Required abilities:

• rulesets:read for GET endpoints

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

Access scope model:

• Organisation-level keys can access rulesets for their own organisation only.

• Admin partner-group keys can access rulesets across all organisations for their partner.

• Non-admin partner-group keys can access rulesets only for organisations assigned to their group.

---

POST /v1/rulesets - create ruleset

Creates one ruleset and optionally creates child rules within the same request.

API level: Organisation-level and partner-level Authentication: rulesets:write

Request body

Field	Type	Description
organisation_id	string	Organisation ID
enrolment_ids	array[string]	One or more enrolment IDs
outcome	string	REFUND, CANCEL, REFUND_AND_CANCEL, or ACCEPT_DISPUTE
join_operator	string	AND or OR
is_enabled	boolean	Optional, defaults to true
rules	array[object]	Optional initial rules

All selected enrolments must be accessible and must share the same supported enrolment type.

Only one rule of each type is allowed per ruleset.

Amount rules must use USD.

If any embedded rule fails validation, the entire ruleset creation is rolled back.

Example 1 request

curl -X POST "https://api.chargebackstop.com/v1/rulesets/" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "organisation_id": "org_xyz456",
    "enrolment_ids": ["enrl_abc123", "enrl_def456"],
    "outcome": "REFUND",
    "join_operator": "AND",
    "is_enabled": true,
    "rules": [
      {
        "type": "DESCRIPTOR",
        "parameters": {
          "descriptors": [
            {"value": "NETFLIX", "match_type": "STARTS_WITH"},
            {"value": "SPOTIFY", "match_type": "STARTS_WITH"}
          ]
        }
      },
      {
        "type": "AMOUNT",
        "parameters": {
          "operator": "GREATER_THAN",
          "currency_code": "USD",
          "amount_in_cents": 5000
        }
      }
    ]
  }'

Example 1 response

{
  "id": "rset_abc123",
  "organisation_id": "org_xyz456",
  "enrolment_ids": ["enrl_abc123", "enrl_def456"],
  "outcome": "REFUND",
  "join_operator": "AND",
  "is_enabled": true,
  "rules": [
    {
      "id": "resrule_desc123",
      "type": "DESCRIPTOR",
      "parameters": {
        "descriptors": [
          {"value": "NETFLIX", "match_type": "STARTS_WITH"},
          {"value": "SPOTIFY", "match_type": "STARTS_WITH"}
        ]
      },
      "created_at": "2026-05-05T10:00:00Z",
      "updated_at": "2026-05-05T10:00:00Z"
    },
    {
      "id": "resrule_amt123",
      "type": "AMOUNT",
      "parameters": {
        "operator": "GREATER_THAN",
        "currency_code": "USD",
        "amount_in_cents": 5000
      },
      "created_at": "2026-05-05T10:00:00Z",
      "updated_at": "2026-05-05T10:00:00Z"
    }
  ],
  "created_at": "2026-05-05T10:00:00Z",
  "updated_at": "2026-05-05T10:00:00Z"
}

---

GET /v1/rulesets - list rulesets

Returns a paginated list of accessible rulesets.

API level: Organisation-level and partner-level Authentication: rulesets:read

Query parameters

Parameter	Type	Description
organisation_id	string	Filter by organisation ID
sort	string	-created_at (default), created_at, -updated_at, or updated_at
limit	integer	Number of results per page
offset	integer	Number of results to skip

Example 2 request

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

Example 2 response

{
  "items": [
    {
      "id": "rset_def456",
      "organisation_id": "org_xyz456",
      "enrolment_ids": ["enrl_abc123", "enrl_def456"],
      "outcome": "REFUND",
      "join_operator": "AND",
      "is_enabled": true,
      "rules": [],
      "created_at": "2026-05-05T10:00:00Z",
      "updated_at": "2026-05-05T10:00:00Z"
    }
  ],
  "count": 1
}

---

GET /v1/rulesets/{ruleset_id} - get ruleset by ID

Returns one accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:read

Example 3 request

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

Example 3 response

{
  "id": "rset_abc123",
  "organisation_id": "org_xyz456",
  "enrolment_ids": ["enrl_abc123"],
  "outcome": "ACCEPT_DISPUTE",
  "join_operator": "AND",
  "is_enabled": true,
  "rules": [
    {
      "id": "resrule_amt123",
      "type": "AMOUNT",
      "parameters": {
        "operator": "GREATER_THAN",
        "currency_code": "USD",
        "amount_in_cents": 5000
      },
      "created_at": "2026-05-05T10:00:00Z",
      "updated_at": "2026-05-05T10:00:00Z"
    }
  ],
  "created_at": "2026-05-05T10:00:00Z",
  "updated_at": "2026-05-05T10:00:00Z"
}

---

PATCH /v1/rulesets/{ruleset_id} - update ruleset

Updates one accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:write

Request body

Field	Type	Description
enrolment_ids	array[string]	Optional. One or more enrolment IDs
outcome	string	Optional. REFUND, CANCEL, REFUND_AND_CANCEL, or ACCEPT_DISPUTE
join_operator	string	Optional. AND or OR
is_enabled	boolean	Optional. Whether the ruleset is enabled

Send only the mutable fields you want to change. Omitted fields keep their existing values.

rules is not accepted on this endpoint. Update child rules through the nested rule endpoints instead.

All selected enrolments must be accessible and must share the same supported enrolment type.

Example 4 request

curl -X PATCH "https://api.chargebackstop.com/v1/rulesets/rset_abc123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "enrolment_ids": ["enrl_abc123", "enrl_def456"],
    "outcome": "CANCEL",
    "join_operator": "OR",
    "is_enabled": false
  }'

Example 4 response

{
  "id": "rset_abc123",
  "organisation_id": "org_xyz456",
  "enrolment_ids": ["enrl_abc123", "enrl_def456"],
  "outcome": "CANCEL",
  "join_operator": "OR",
  "is_enabled": false,
  "rules": [],
  "created_at": "2026-05-05T10:00:00Z",
  "updated_at": "2026-05-05T10:00:00Z"
}

---

DELETE /v1/rulesets/{ruleset_id} - delete ruleset

Deletes one accessible ruleset and its child rules.

API level: Organisation-level and partner-level Authentication: rulesets:write

The response body is empty on success.

Example 5 request

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

Example 5 response

204 No Content

---

POST /v1/rulesets/{ruleset_id}/rules - add rule

Adds one rule to an existing accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:write

Example 6 request

curl -X POST "https://api.chargebackstop.com/v1/rulesets/rset_abc123/rules" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "AMOUNT",
    "parameters": {
      "operator": "GREATER_THAN",
      "currency_code": "USD",
      "amount_in_cents": 5000
    }
  }'

Example 6 response

{
  "id": "resrule_amt123",
  "type": "AMOUNT",
  "parameters": {
    "operator": "GREATER_THAN",
    "currency_code": "USD",
    "amount_in_cents": 5000
  },
  "created_at": "2026-05-05T10:00:00Z",
  "updated_at": "2026-05-05T10:00:00Z"
}

---

GET /v1/rulesets/{ruleset_id}/rules/{rule_id} - get rule by ID

Returns one accessible rule from an accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:read

Example 7 request

curl -X GET "https://api.chargebackstop.com/v1/rulesets/rset_abc123/rules/resrule_amt123" \
  -H "Authorization: Bearer <api_key>"

Example 7 response

{
  "id": "resrule_amt123",
  "type": "AMOUNT",
  "parameters": {
    "operator": "GREATER_THAN",
    "currency_code": "USD",
    "amount_in_cents": 5000
  },
  "created_at": "2026-05-05T10:00:00Z",
  "updated_at": "2026-05-05T10:00:00Z"
}

---

PATCH /v1/rulesets/{ruleset_id}/rules/{rule_id} - update rule

Updates one accessible rule within an accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:write

Request body

Field	Type	Description
type	string	Must match the existing rule type
parameters	object	Rule parameters for the selected type

Rule type cannot be changed.

Amount rules must use USD.

Example 8 request

curl -X PATCH "https://api.chargebackstop.com/v1/rulesets/rset_abc123/rules/resrule_amt123" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "AMOUNT",
    "parameters": {
      "operator": "GREATER_THAN",
      "currency_code": "USD",
      "amount_in_cents": 7500
    }
  }'

Example 8 response

{
  "id": "resrule_amt123",
  "type": "AMOUNT",
  "parameters": {
    "operator": "GREATER_THAN",
    "currency_code": "USD",
    "amount_in_cents": 7500
  },
  "created_at": "2026-05-05T10:00:00Z",
  "updated_at": "2026-05-05T10:00:00Z"
}

---

DELETE /v1/rulesets/{ruleset_id}/rules/{rule_id} - delete rule

Deletes one accessible rule from an accessible ruleset.

API level: Organisation-level and partner-level Authentication: rulesets:write

The response body is empty on success.

Example 9 request

curl -X DELETE "https://api.chargebackstop.com/v1/rulesets/rset_abc123/rules/resrule_amt123" \
  -H "Authorization: Bearer <api_key>"

Example 9 response

204 No Content

---

Error examples

Example 10: forbidden

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

Example 11: not found

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

Example 12: invalid currency

{
  "errors": [
    {
      "code": "INVALID_CURRENCY_CODE",
      "message": "Only USD is allowed.",
      "field": "currency_code"
    }
  ]
}

Example 13: rules not allowed on ruleset update

{
  "errors": [
    {
      "code": "RULES_NOT_ALLOWED_ON_RULESET_UPDATE",
      "message": "Rules cannot be updated via this endpoint. Use PATCH /v1/rulesets/{ruleset_id}/rules/{rule_id} instead.",
      "field": "rules"
    }
  ]
}