Skip to main content
POST
Create Cashback Rule

Authorizations

Authorization
string
header
required

An Account API key, account-scoped JWT, App API key, or user OAuth token. Prepend the key or token with Bearer, for example Bearer ***************************.

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-09-09"

Body

application/json
merchant_category_code
string
required

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

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

"5734"

merchant_name
string
required

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

Required string length: 1 - 128
Example:

"ACME SOFTWARE"

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"

scoped_account_id
string | null

Account ID prefixed biz_ belonging to a direct connected account. 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:

"Software cashback"

discarded_at
string | null
required

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

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
required

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

Example:

"5734"

merchant_name
string
required

Raw merchant name reported by the card provider. Matched together with the merchant category code; not a substring or enriched display-name match.

Example:

"ACME SOFTWARE"

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.

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"