Affiliate REST

POST bonuses

Grant a positive one-time bonus under the eligible membership's current contract and hold rules.

Verified 2026-10-07·Read Markdown

On this page

Purpose

Grant a positive one-time bonus under the eligible membership's current contract and hold rules.

Authentication and scope

Use an app-scoped affiliate API key with rewards:write. Record IDs must belong to the credential's app and workspace. A workspace MCP key or install-bridge key is not interchangeable with this key.

Request

POST /api/affiliate-platform/v1/bonuses

membershipId: required; string; format: uuid
amount: required; object
reason: required; string; minLength: 1; maxLength: 2000

Use the exact record identifier returned for your own app.

Set the environment credential from your authenticated Developers screen. Replace the fictional record IDs and shop/contact values. This request changes data; review the effect before running it. Use a new idempotency key for a new action, and reuse the same key/body only when retrying the same action.

bash

curl --request POST "https://heycrust.com/api/affiliate-platform/v1/bonuses" \
  --header "Authorization: Bearer $HEYCRUST_AFFILIATE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: example-post-bonuses-001" \
  --data '{"membershipId":"11111111-1111-4111-8111-111111111111","amount":{"amountMinor":"1000","currency":"USD"},"reason":"Example agreed achievement"}'

Response and verification

The response is the operation's program, membership, terms, referral, commission or payout-history representation. Verify its app/record identity and state; acceptance of a request is not proof of an external transfer or attributed Shopify install.

Successful responses use Cache-Control: no-store and X-Affiliate-Schema-Version: 1. Money uses currency plus minor-unit integer strings; currencies stay separate.

Errors and recovery

401 means missing/invalid/revoked credentials; 403 means denied app/scope/resource access. Invalid fields produce 400, unsupported operation/path 404, conflict/source/review conditions 409, and the DB-backed credential quota produces 429 with Retry-After. The public affiliate quota is 120 requests per credential per minute. Validate the response body as well as the status. JSON mutation bodies must fit the 65,536-byte request bound.

Read API overview and Developer integration.

Response example

Successful response excerpt exercised through the actual handler with isolated fixtures. Other fields are omitted. IDs, dates and merchant values are fictional; this is an example state, not a universal outcome.

json

{
  "id": "11111111-1111-4111-8111-111111111111",
  "membershipId": "11111111-1111-4111-8111-111111111111",
  "kind": "bonus",
  "amount": {
    "amountMinor": "1000",
    "currency": "USD"
  },
  "basis": null,
  "rateBps": null
}