# POST memberships

Provision an app's partner membership. Account verification/claim and term acceptance still affect eligibility.

## Purpose

Provision an app's partner membership. Account verification/claim and term acceptance still affect eligibility.

## Authentication and scope

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

- `programId`: required; string; format: uuid
- `email`: required; string
- `name`: optional; string; minLength: 1; maxLength: 120
- `groupId`: optional; string; format: uuid

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/memberships" \
  --header "Authorization: Bearer $HEYCRUST_AFFILIATE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: example-post-memberships-001" \
  --data '{"programId":"11111111-1111-4111-8111-111111111111","email":"partner@example.com","name":"Example partner"}'
```

## 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",
  "programId": "11111111-1111-4111-8111-111111111111",
  "appId": "11111111-1111-4111-8111-111111111111",
  "status": "provisioned",
  "eligible": false,
  "termsAccepted": false,
  "currentTermsAccepted": false
}
```