---
title: "Create Cashback Rule"
method: POST
path: "/cashback_rule"
tags: ["Cashback Rules"]
---

# Create Cashback Rule

`POST /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.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `description` string, nullable — Optional description of the rule.
  - `expires_at` string, date-time, nullable — Exclusive end, strictly later than starts_at. Omit or set null for no expiration.
  - `merchant_category_code` string, nullable — Four-digit MCC, including leading zeros. Null matches any MCC. When both merchant filters are absent, scoped_account_id is required.
  - `merchant_name` string, 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_bps` integer, required — Cashback rate in basis points: 500 means 5%.
  - `scoped_account_id` string, 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_at` string, date-time, required — Inclusive start, strictly later than the current time, as an ISO 8601 timestamp.

## Response `201`

cashback rule created

- CashbackRule
  - `created_at` string, required — When the rule was created, as an ISO 8601 timestamp.
  - `description` string, nullable, required — Optional description of the cashback rule.
  - `discarded_at` string, nullable, required — When the rule was discarded, as an ISO 8601 timestamp. Null means it has not been discarded.
  - `expires_at` string, nullable, required — Exclusive end of the eligibility window, as an ISO 8601 timestamp. Null means no expiration.
  - `funding_account_id` string, required — Platform account designated to fund cashback, prefixed `biz_`. Derived from the authenticated credential.
  - `id` string, required — Cashback rule ID, prefixed `cicbr_`.
  - `merchant_category_code` string, nullable, required — Four-digit merchant category code. Null matches any MCC. When both merchant filters are null, scoped_account_id is required.
  - `merchant_name` string, 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_bps` integer, required — Cashback rate in basis points. 100 means 1%, and 10000 means 100%.
  - `scoped_account_id` string, nullable, 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.
  - `updated_at` string, required — When the rule was last updated, as an ISO 8601 timestamp.

## Other responses

- `400` — Invalid Parameters
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Resource not found
- `409` — Conflict

## Changes

> 74 revisions in range; 1 not diffed.

- **2026-09-23** `140d015b9966` — 2 breaking, 4 info
  - the response property `merchant_category_code` became nullable for the status `201`
  - the response property `merchant_name` became nullable for the status `201`
  - the request property `merchant_category_code` became nullable
  - the request property `merchant_name` became nullable
  - …2 more

[Change history](https://skmtc.dev/whop/apis/whop-api/changes/cashback_rule/post.md)

---

[API](https://skmtc.dev/whop/apis/whop-api.md) · [All operations](https://skmtc.dev/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc.dev/whop/apis/whop-api/revisions/78e1ed7366cd?raw)