# POST referrals

Submit a manual client claim for verification. This is not a verified installation or automatic commission.

## Purpose

Submit a manual client claim for verification. This is not a verified installation or automatic commission.

## Authentication and scope

Use an app-scoped affiliate API key with `referrals: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/referrals`

- `membershipId`: required; string; format: uuid
- `shopDomain`: required; string; minLength: 1; maxLength: 255
- `referredAt`: required; value
- `evidence`: required; string; minLength: 5; maxLength: 4000

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/referrals" \
  --header "Authorization: Bearer $HEYCRUST_AFFILIATE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: example-post-referrals-001" \
  --data '{"membershipId":"11111111-1111-4111-8111-111111111111","shopDomain":"example.myshopify.com","referredAt":"2026-10-07T00:00:00Z","evidence":"Example client referral agreement"}'
```

## 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",
  "programId": "11111111-1111-4111-8111-111111111111",
  "appId": "11111111-1111-4111-8111-111111111111",
  "shopDomain": "example.myshopify.com",
  "status": "requested",
  "source": "manual",
  "termsVersionId": null
}
```