WHwhop
Cashback Rules

Create Cashback Rule

Changed on

Creates a future-dated card cashback rule for your direct connected accounts, funded by the authenticated platform account. Creating a rule does not transfer funds; pay cashback out with POST /cashback_rules/payout. Requires payout:transfer_funds. Supports Idempotency-Key for safe retries.

post/cashback_rule

Request

  • Base URL
    https://api.whop.com/api/v1
  • URL
    https://api.whop.com/api/v1/cashback_rule
  • Auth
    HTTP bearer

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_, 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.

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

  • 140d015b9966Revision changes
    • breaking

      the response property became nullable for the status

    • breaking

      the response property became nullable for the status

    • info

      the request property became nullable

    • info

      the request property became nullable

    • info

      the request property became optional

    • info

      the request property became optional