Skip to content
HeyCrustDocs

Search documentation

Search by topic or tool name
Partner portalOpen app ↗
Browse documentation
Affiliate REST

GET referrals

List observed/submitted referral summaries for the app.

Verified ·Read Markdown
On this page

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 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
{
  "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
}

Continue reading