# POST bonuses

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

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

## Example

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](/docs/api) and [Developer integration](/docs/developers).

## 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
}
```