Cascade

    Referrals

    These endpoints are called from a shopper's browser, so they take your publishable key rather than a secret one. Anything specific to one customer also takes a signed email and timestamp: see Identifying the customer for how to produce the signature.

    GET /widgets/referrals

    Get the customer's referral code and stats for each loyalty program they belong to

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Request
    curl \
  "https://api.cascade.dev/widgets/referrals?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..."
    Response
    {
  "programs": [
    {
      "loyaltyProgramId": "550e8400-e29b-41d4-a716-446655440000",
      "programName": "string",
      "referralCode": "string",
      "pendingCount": 0,
      "completedCount": 0,
      "rules": ["..."]
    }
  ]
}

    POST /widgets/referrals/capture

    Record that the customer was referred by another member, through their code or through a shared wishlist's product link. Call it once the visitor has identified, for example after they sign up or join the program.

    Query Parameters

    apiPublishableKeystringrequired

    Your organization's publishable key, from Settings, API keys.

    customerEmailstring (email)required

    Email address of the customer the storefront signed in.

    timestampstringrequired

    Unix time in seconds when the signature was generated. It is accepted for 24 hours.

    signaturestringrequired

    Hex HMAC-SHA256 of customerEmail followed by timestamp, keyed with your widget signing secret. See the widgets guide for the recipe.

    Body Parameters

    codestring

    The referral code the visitor arrived with, from the share URL or typed in.

    wishlistShareTokenstring

    The cascadeWishlist token from a shared wishlist's product link, when the visitor arrived from one. Attributes the visitor to the list's owner without exposing their code. Ignored when code is also sent.

    Request
    curl \
  -X POST \
  "https://api.cascade.dev/widgets/referrals/capture?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY&customerEmail=shopper%40example.com&timestamp=1735689600&signature=9f86d081..." \
  -H "Content-Type: application/json" \
  -d '{
  "code": "string",
  "wishlistShareToken": "string"
}'
    Response
    {
  "outcome": "attributed"
}