Sign in
Cashback Rules

Create Cashback Rule

Creates a future-dated card cashback rule funded by the authenticated platform account. Requires payout:transfer_funds. Both the raw merchant name and four-digit MCC are required. 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 required

Four-digit MCC, including leading zeros. Must match together with merchant_name.

merchant_namestring required

Raw merchant name reported by the card provider, not the enriched display name. Matched with the MCC; not a substring or wildcard.

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. 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 required

Four-digit merchant category code. Both merchant filters must match.

merchant_namestring required

Raw merchant name reported by the card provider. Matched together with the merchant category code; 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