Create Cashback Rule

curl --request POST \
  --url https://api.whop.com/api/v1/cashback_rule \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rate_bps": 500,
  "starts_at": "2026-01-01T12:00:00.000Z",
  "description": "Software cashback",
  "expires_at": "2026-01-01T12:00:00.000Z",
  "merchant_category_code": "5734",
  "merchant_name": "ACME SOFTWARE",
  "scoped_account_id": "<string>"
}
'

import requests

url = "https://api.whop.com/api/v1/cashback_rule"

payload = {
    "rate_bps": 500,
    "starts_at": "2026-01-01T12:00:00.000Z",
    "description": "Software cashback",
    "expires_at": "2026-01-01T12:00:00.000Z",
    "merchant_category_code": "5734",
    "merchant_name": "ACME SOFTWARE",
    "scoped_account_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    rate_bps: 500,
    starts_at: '2026-01-01T12:00:00.000Z',
    description: 'Software cashback',
    expires_at: '2026-01-01T12:00:00.000Z',
    merchant_category_code: '5734',
    merchant_name: 'ACME SOFTWARE',
    scoped_account_id: '<string>'
  })
};

fetch('https://api.whop.com/api/v1/cashback_rule', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.whop.com/api/v1/cashback_rule",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'rate_bps' => 500,
    'starts_at' => '2026-01-01T12:00:00.000Z',
    'description' => 'Software cashback',
    'expires_at' => '2026-01-01T12:00:00.000Z',
    'merchant_category_code' => '5734',
    'merchant_name' => 'ACME SOFTWARE',
    'scoped_account_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.whop.com/api/v1/cashback_rule"

	payload := strings.NewReader("{\n  \"rate_bps\": 500,\n  \"starts_at\": \"2026-01-01T12:00:00.000Z\",\n  \"description\": \"Software cashback\",\n  \"expires_at\": \"2026-01-01T12:00:00.000Z\",\n  \"merchant_category_code\": \"5734\",\n  \"merchant_name\": \"ACME SOFTWARE\",\n  \"scoped_account_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.whop.com/api/v1/cashback_rule")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"rate_bps\": 500,\n  \"starts_at\": \"2026-01-01T12:00:00.000Z\",\n  \"description\": \"Software cashback\",\n  \"expires_at\": \"2026-01-01T12:00:00.000Z\",\n  \"merchant_category_code\": \"5734\",\n  \"merchant_name\": \"ACME SOFTWARE\",\n  \"scoped_account_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.whop.com/api/v1/cashback_rule")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"rate_bps\": 500,\n  \"starts_at\": \"2026-01-01T12:00:00.000Z\",\n  \"description\": \"Software cashback\",\n  \"expires_at\": \"2026-01-01T12:00:00.000Z\",\n  \"merchant_category_code\": \"5734\",\n  \"merchant_name\": \"ACME SOFTWARE\",\n  \"scoped_account_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2026-01-01T12:00:00.000Z",
  "description": "Cloud cashback",
  "discarded_at": null,
  "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"
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

Cashback Rules

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

POST

cashback_rule

curl --request POST \
  --url https://api.whop.com/api/v1/cashback_rule \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rate_bps": 500,
  "starts_at": "2026-01-01T12:00:00.000Z",
  "description": "Software cashback",
  "expires_at": "2026-01-01T12:00:00.000Z",
  "merchant_category_code": "5734",
  "merchant_name": "ACME SOFTWARE",
  "scoped_account_id": "<string>"
}
'

import requests

url = "https://api.whop.com/api/v1/cashback_rule"

payload = {
    "rate_bps": 500,
    "starts_at": "2026-01-01T12:00:00.000Z",
    "description": "Software cashback",
    "expires_at": "2026-01-01T12:00:00.000Z",
    "merchant_category_code": "5734",
    "merchant_name": "ACME SOFTWARE",
    "scoped_account_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    rate_bps: 500,
    starts_at: '2026-01-01T12:00:00.000Z',
    description: 'Software cashback',
    expires_at: '2026-01-01T12:00:00.000Z',
    merchant_category_code: '5734',
    merchant_name: 'ACME SOFTWARE',
    scoped_account_id: '<string>'
  })
};

fetch('https://api.whop.com/api/v1/cashback_rule', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.whop.com/api/v1/cashback_rule",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'rate_bps' => 500,
    'starts_at' => '2026-01-01T12:00:00.000Z',
    'description' => 'Software cashback',
    'expires_at' => '2026-01-01T12:00:00.000Z',
    'merchant_category_code' => '5734',
    'merchant_name' => 'ACME SOFTWARE',
    'scoped_account_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.whop.com/api/v1/cashback_rule"

	payload := strings.NewReader("{\n  \"rate_bps\": 500,\n  \"starts_at\": \"2026-01-01T12:00:00.000Z\",\n  \"description\": \"Software cashback\",\n  \"expires_at\": \"2026-01-01T12:00:00.000Z\",\n  \"merchant_category_code\": \"5734\",\n  \"merchant_name\": \"ACME SOFTWARE\",\n  \"scoped_account_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.whop.com/api/v1/cashback_rule")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"rate_bps\": 500,\n  \"starts_at\": \"2026-01-01T12:00:00.000Z\",\n  \"description\": \"Software cashback\",\n  \"expires_at\": \"2026-01-01T12:00:00.000Z\",\n  \"merchant_category_code\": \"5734\",\n  \"merchant_name\": \"ACME SOFTWARE\",\n  \"scoped_account_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.whop.com/api/v1/cashback_rule")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"rate_bps\": 500,\n  \"starts_at\": \"2026-01-01T12:00:00.000Z\",\n  \"description\": \"Software cashback\",\n  \"expires_at\": \"2026-01-01T12:00:00.000Z\",\n  \"merchant_category_code\": \"5734\",\n  \"merchant_name\": \"ACME SOFTWARE\",\n  \"scoped_account_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "created_at": "2026-01-01T12:00:00.000Z",
  "description": "Cloud cashback",
  "discarded_at": null,
  "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"
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

{
  "error": {
    "message": "account_id is required",
    "type": "bad_request",
    "code": "<string>"
  }
}

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

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

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"

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"