# GET referrals

List observed/submitted referral summaries for the app.

## Purpose

List observed/submitted referral summaries for the app.

## Authentication and scope

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

`GET /api/affiliate-platform/v1/referrals`

- `appId`: optional; string or null
- `programId`: optional; string; format: uuid
- `groupId`: optional; string; format: uuid
- `membershipId`: optional; string; format: uuid
- `from`: optional; value
- `to`: optional; value
- `currency`: optional; string; minLength: 3; maxLength: 3
- `status`: optional; string; maxLength: 40
- `search`: optional; string; maxLength: 120
- `cursor`: optional; string; maxLength: 1500
- `limit`: optional; integer; minimum: 1; maximum: 50

List filters are section-specific. Currency applies to commission/payout lists; a group filter does not apply to programs. Default page limit is 50 and maximum is 50. A returned cursor is bound to the same credential, section and filters.

## Example

Set the environment credential from your authenticated Developers screen. Replace the fictional record IDs and shop/contact values. This request reads existing records.

```bash
curl --request GET "https://heycrust.com/api/affiliate-platform/v1/referrals?limit=25" \
  --header "Authorization: Bearer $HEYCRUST_AFFILIATE_API_KEY"
```

## Response and verification

Lists return `items` and `nextCursor`. Rows are summaries rather than the complete detail representation. Continue with the same filters when using a cursor.

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
{
  "items": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "kind": "referrals",
      "appId": "11111111-1111-4111-8111-111111111111",
      "programId": "11111111-1111-4111-8111-111111111111",
      "membershipId": "11111111-1111-4111-8111-111111111111",
      "name": "example.myshopify.com",
      "status": "accepted",
      "amount": null
    }
  ],
  "nextCursor": null
}
```