Sign in
Cashback Rules

Create Cashback Rule

Creates a future-dated card cashback rule funded by the authenticated platform account. Requires payout:transfer_funds. Merchant name and MCC are optional. Every supplied merchant filter must match. When both are omitted or null, scoped_account_id is required and all eligible transactions for that account match. Optionally limit the rule to one direct connected account. The funding account is derived from the credential and cannot be supplied. Creation does not transfer funds. Supports Idempotency-Key for safe retries.

post/cashback_rule

Headers

Idempotency-Keystring

Client-generated key for replaying the same request safely for 24 hours.

Request body

descriptionstring nullable

Optional description of the rule.

expires_atstring date-time nullable

Exclusive end, strictly later than starts_at. Omit or set null for no expiration.

merchant_category_codestring nullable

Four-digit MCC, including leading zeros. Null matches any MCC. When both merchant filters are absent, scoped_account_id is required.

merchant_namestring nullable

Raw merchant name reported by the card provider, not the enriched display name. Omit or set null to match any merchant name. Supplied names must contain a non-whitespace character and match together with any MCC filter.

rate_bpsinteger required

Cashback rate in basis points: 500 means 5%.

scoped_account_idstring nullable

Account ID prefixed biz_ belonging to a direct connected account. Required when both merchant filters are omitted or null. Otherwise, omit or set null to designate all direct connected accounts.

starts_atstring date-time required

Inclusive start, strictly later than the current time, as an ISO 8601 timestamp.

Example request

{
  "description": "Software cashback",
  "expires_at": "2026-01-01T12:00:00.000Z",
  "merchant_category_code": "5734",
  "merchant_name": "ACME SOFTWARE",
  "rate_bps": 500,
  "starts_at": "2026-01-01T12:00:00.000Z"
}

Response

cashback rule created

created_atstring required

When the rule was created, as an ISO 8601 timestamp.

descriptionstring nullable required

Optional description of the cashback rule.

discarded_atstring nullable required

When the rule was discarded, as an ISO 8601 timestamp. Null means it has not been discarded.

expires_atstring nullable required

Exclusive end of the eligibility window, as an ISO 8601 timestamp. Null means no expiration.

funding_account_idstring required

Platform account designated to fund cashback, prefixed biz_. Derived from the authenticated credential.

idstring required

Cashback rule ID, prefixed cicbr_.

merchant_category_codestring nullable required

Four-digit merchant category code. Null matches any MCC. When both merchant filters are null, scoped_account_id is required.

merchant_namestring nullable required

Raw merchant name reported by the card provider. Null matches any merchant name. When set, matches together with any MCC filter; not a substring or enriched display-name match.

rate_bpsinteger required

Cashback rate in basis points. 100 means 1%, and 10000 means 100%.

scoped_account_idstring nullable required

Connected account ID, prefixed biz_. Null designates all direct connected accounts of the funding platform.

starts_atstring required

Inclusive start of the rule's eligibility window, as an ISO 8601 timestamp.

updated_atstring required

When the rule was last updated, as an ISO 8601 timestamp.

Example response

{
  "created_at": "2026-01-01T12:00:00.000Z",
  "description": "Cloud cashback",
  "expires_at": "2026-01-01T12:00:00.000Z",
  "funding_account_id": "biz_xxxxxxxxxxxxxx",
  "id": "cicbr_xxxxxxxxxxxxxx",
  "merchant_category_code": "7372",
  "merchant_name": "ACME CLOUD",
  "rate_bps": 500,
  "scoped_account_id": "biz_xxxxxxxxxxxxxx",
  "starts_at": "2026-01-01T12:00:00.000Z",
  "updated_at": "2026-01-01T12:00:00.000Z"
}

Changes