Skip to main content
POST
Create Cashback Rule

Authorizations

Authorization
string
header
required

An Account API key, an App API key, an account access token, an account-scoped user token, or a user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************. See Auth & API keys for how to get each one.

Headers

Idempotency-Key
string

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

Required string length: 1 - 255
Api-Version-Date
string

Pins the request to a dated API version.

Example:

"2026-10-15-1"

Body

application/json
rate_bps
integer
required

Cashback rate in basis points: 500 means 5%.

Required range: 1 <= x <= 10000
Example:

500

starts_at
string<date-time>
required

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

Example:

"2026-01-01T12:00:00.000Z"

description
string | null

Optional description of the rule.

Maximum string length: 255
Example:

"Software cashback"

expires_at
string<date-time> | null

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

Example:

"2026-01-01T12:00:00.000Z"

merchant_category_code
string | null

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

Pattern: ^[0-9]{4}$
Example:

"5734"

merchant_name
string | null

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.

Required string length: 1 - 128
Example:

"ACME SOFTWARE"

scoped_account_id
string | null

Account ID, prefixed biz_, of one direct connected account to limit the rule to. Required when both merchant filters are omitted or null, in which case the rule matches all eligible transactions for that account. Otherwise, omit or set null to designate all direct connected accounts.

Pattern: ^biz_

Response

cashback rule created

created_at
string
required

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

Example:

"2026-01-01T12:00:00.000Z"

description
string | null
required

Optional description of the cashback rule.

Example:

"Cloud cashback"

discarded_at
string | null
required

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

Example:

null

expires_at
string | null
required

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

Example:

"2026-01-01T12:00:00.000Z"

funding_account_id
string
required

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

Example:

"biz_xxxxxxxxxxxxxx"

id
string
required

Cashback rule ID, prefixed cicbr_.

Example:

"cicbr_xxxxxxxxxxxxxx"

merchant_category_code
string | null
required

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

Example:

"7372"

merchant_name
string | null
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.

Example:

"ACME CLOUD"

rate_bps
integer
required

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

Example:

500

scoped_account_id
string | null
required

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

Example:

"biz_xxxxxxxxxxxxxx"

starts_at
string
required

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

Example:

"2026-01-01T12:00:00.000Z"

updated_at
string
required

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

Example:

"2026-01-01T12:00:00.000Z"