HTTP endpoints

redeemInstallClaim

POST /api/tracking/{publishableKey}/install-claims/redeem

Uses the publishable tracking key in the path. Website requests need an allowed Origin. Native capture must be enabled on the key. No server key is sent.

HTTP

Use your backend's HTTP client. The cURL request shows the wire format. Replace path parameters and example values.

curl --fail-with-body --request POST \
  'https://app.grizzlee.ca/api/tracking/{publishableKey}/install-claims/redeem' \
  -H 'Origin: https://shop.example.com' \
  -H 'Content-Type: application/json' \
  --data '{"code":"code-example"}'

Request body

Field	Type	Required	Details
`code`	string	Yes

Request schema

json

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false
}

Response

HTTP responses wrap this value in data. The SDK returns the value directly unless the note above describes a wrapper.

Field	Type	Required	Details
`receipt`	string	Yes
`checkoutReference`	string	Yes	A short signed reference to the same capture, 112 characters, that expires with the receipt. Put it in a Stripe Checkout Session's client_reference_id, or in grizzlee_receipt metadata, and a Stripe connection that records invoices claims the referral for the paying customer.
`programId`	string	Yes
`placements`	array	Yes
`expiresAt`	string	Yes
`duration`	union	Yes
`incentive`	union	Yes	The program's current friend incentive, or null when it has none. Says nothing about eligibility.
`display`	object	Yes	The program's public name, headline and milestone label.
`installClaim`	object	No	Present when the capture asked for an install claim.

duration

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

Variant 5

Type: string.

Variant 6

Type: string.

incentive

Variant 1

Type: null.

Variant 2

Field	Type	Required	Details
`incentive.type`	"percent"	Yes
`incentive.rateBps`	number	Yes
`incentive.orders`	number	Yes	How many of the friend's orders get the incentive.
`incentive.newCustomersOnly`	boolean	Yes	true: use the merchant's newCustomer answer, or recorded purchases when omitted. false: returning customers qualify too. A supplied answer uses the order limit after the referral.
`incentive.expiresAfterDays`	union	Yes	Days after the referral was captured, claimed or entered. null means it never expires.
`incentive.returnOnFullRefund`	boolean	Yes	true: a full refund gives the use back, so the customer can get the offer again.
`incentive.maxDiscountCents`	number	No	Largest discount for one order.
`incentive.minOrderCents`	number	No	The friend's order total before the discount must reach this amount. Checked by the merchant's checkout.
`incentive.orderCategories`	object	No	Order categories that get the discount. Checked apart from the program's own orderCategories, which decide rewards. Absent means every order qualifies.
`incentive.currency`	union	Yes

incentive.expiresAfterDays

Variant 1

Type: null.

Variant 2

Type: number.

incentive.orderCategories

Field	Type	Required	Details
`incentive.orderCategories.include`	array	No
`incentive.orderCategories.exclude`	array	No

incentive.currency

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

Variant 3

Field	Type	Required	Details
`incentive.type`	"fixed"	Yes
`incentive.orders`	number	Yes	How many of the friend's orders get the incentive.
`incentive.newCustomersOnly`	boolean	Yes	true: use the merchant's newCustomer answer, or recorded purchases when omitted. false: returning customers qualify too. A supplied answer uses the order limit after the referral.
`incentive.expiresAfterDays`	union	Yes	Days after the referral was captured, claimed or entered. null means it never expires.
`incentive.returnOnFullRefund`	boolean	Yes	true: a full refund gives the use back, so the customer can get the offer again.
`incentive.amountCents`	number	Yes
`incentive.minOrderCents`	number	No	The friend's order total before the discount must reach this amount. Checked by the merchant's checkout.
`incentive.orderCategories`	object	No	Order categories that get the discount. Checked apart from the program's own orderCategories, which decide rewards. Absent means every order qualifies.
`incentive.currency`	union	Yes

incentive.expiresAfterDays

Variant 1

Type: null.

Variant 2

Type: number.

incentive.orderCategories

Field	Type	Required	Details
`incentive.orderCategories.include`	array	No
`incentive.orderCategories.exclude`	array	No

incentive.currency

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

display

Field	Type	Required	Details
`display.publicName`	object	Yes
`display.headline`	object	Yes
`display.milestoneLabel`	union	Yes	Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and many matter in Russian. A merchant's label sets one and other, and few and many reuse other.

display.publicName

Field	Type	Required
`display.publicName.en`	string	Yes
`display.publicName.fr-CA`	string	Yes
`display.publicName.hy`	string	Yes
`display.publicName.ru`	string	Yes

display.headline

Field	Type	Required
`display.headline.en`	string	Yes
`display.headline.fr-CA`	string	Yes
`display.headline.hy`	string	Yes
`display.headline.ru`	string	Yes

display.milestoneLabel

Variant 1

Type: null.

Variant 2

Field	Type	Required
`display.milestoneLabel.one`	object	Yes
`display.milestoneLabel.few`	object	Yes
`display.milestoneLabel.many`	object	Yes
`display.milestoneLabel.other`	object	Yes

display.milestoneLabel.one

Field	Type	Required
`display.milestoneLabel.one.en`	string	Yes
`display.milestoneLabel.one.fr-CA`	string	Yes
`display.milestoneLabel.one.hy`	string	Yes
`display.milestoneLabel.one.ru`	string	Yes

display.milestoneLabel.few

Field	Type	Required
`display.milestoneLabel.few.en`	string	Yes
`display.milestoneLabel.few.fr-CA`	string	Yes
`display.milestoneLabel.few.hy`	string	Yes
`display.milestoneLabel.few.ru`	string	Yes

display.milestoneLabel.many

Field	Type	Required
`display.milestoneLabel.many.en`	string	Yes
`display.milestoneLabel.many.fr-CA`	string	Yes
`display.milestoneLabel.many.hy`	string	Yes
`display.milestoneLabel.many.ru`	string	Yes

display.milestoneLabel.other

Field	Type	Required
`display.milestoneLabel.other.en`	string	Yes
`display.milestoneLabel.other.fr-CA`	string	Yes
`display.milestoneLabel.other.hy`	string	Yes
`display.milestoneLabel.other.ru`	string	Yes

installClaim

Field	Type	Required	Details
`installClaim.code`	string	Yes	Twelve characters in groups of four, such as K7Q2-M9XD-4HPA. Hyphens, spaces and case are ignored.
`installClaim.expiresAt`	string	Yes	The claim stops working at this time, at most 7 days after the capture.

Response schema

json

{
  "type": "object",
  "properties": {
    "receipt": {
      "type": "string"
    },
    "checkoutReference": {
      "type": "string",
      "description": "A short signed reference to the same capture, 112 characters, that expires with the receipt. Put it in a Stripe\nCheckout Session's client_reference_id, or in grizzlee_receipt metadata, and a Stripe\nconnection that records invoices claims the referral for the paying customer."
    },
    "programId": {
      "type": "string"
    },
    "placements": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "expiresAt": {
      "type": "string"
    },
    "duration": {
      "anyOf": [
        {
          "type": "string",
          "const": "only_order"
        },
        {
          "type": "string",
          "const": "first_order"
        },
        {
          "type": "string",
          "const": "first_n_orders"
        },
        {
          "type": "string",
          "const": "days"
        },
        {
          "type": "string",
          "const": "months"
        },
        {
          "type": "string",
          "const": "lifetime"
        }
      ]
    },
    "incentive": {
      "anyOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "percent"
            },
            "rateBps": {
              "type": "number"
            },
            "orders": {
              "type": "number",
              "description": "How many of the friend's orders get the incentive."
            },
            "newCustomersOnly": {
              "type": "boolean",
              "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral."
            },
            "expiresAfterDays": {
              "anyOf": [
                {
                  "type": "null"
                },
                {
                  "type": "number"
                }
              ],
              "description": "Days after the referral was captured, claimed or entered. null means it never expires."
            },
            "returnOnFullRefund": {
              "type": "boolean",
              "description": "true: a full refund gives the use back, so the customer can get the offer again."
            },
            "maxDiscountCents": {
              "type": "number",
              "description": "Largest discount for one order."
            },
            "minOrderCents": {
              "type": "number",
              "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout."
            },
            "orderCategories": {
              "type": "object",
              "properties": {
                "include": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "exclude": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies."
            },
            "currency": {
              "anyOf": [
                {
                  "type": "string",
                  "const": "CAD"
                },
                {
                  "type": "string",
                  "const": "USD"
                },
                {
                  "type": "string",
                  "const": "EUR"
                },
                {
                  "type": "string",
                  "const": "GBP"
                }
              ]
            }
          },
          "required": [
            "type",
            "rateBps",
            "orders",
            "newCustomersOnly",
            "expiresAfterDays",
            "returnOnFullRefund",
            "currency"
          ]
        },
        {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "fixed"
            },
            "orders": {
              "type": "number",
              "description": "How many of the friend's orders get the incentive."
            },
            "newCustomersOnly": {
              "type": "boolean",
              "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral."
            },
            "expiresAfterDays": {
              "anyOf": [
                {
                  "type": "null"
                },
                {
                  "type": "number"
                }
              ],
              "description": "Days after the referral was captured, claimed or entered. null means it never expires."
            },
            "returnOnFullRefund": {
              "type": "boolean",
              "description": "true: a full refund gives the use back, so the customer can get the offer again."
            },
            "amountCents": {
              "type": "number"
            },
            "minOrderCents": {
              "type": "number",
              "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout."
            },
            "orderCategories": {
              "type": "object",
              "properties": {
                "include": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "exclude": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              },
              "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies."
            },
            "currency": {
              "anyOf": [
                {
                  "type": "string",
                  "const": "CAD"
                },
                {
                  "type": "string",
                  "const": "USD"
                },
                {
                  "type": "string",
                  "const": "EUR"
                },
                {
                  "type": "string",
                  "const": "GBP"
                }
              ]
            }
          },
          "required": [
            "type",
            "orders",
            "newCustomersOnly",
            "expiresAfterDays",
            "returnOnFullRefund",
            "amountCents",
            "currency"
          ]
        }
      ],
      "description": "The program's current friend incentive, or null when it has none. Says nothing about eligibility."
    },
    "display": {
      "type": "object",
      "properties": {
        "publicName": {
          "type": "object",
          "properties": {
            "en": {
              "type": "string"
            },
            "fr-CA": {
              "type": "string"
            },
            "hy": {
              "type": "string"
            },
            "ru": {
              "type": "string"
            }
          },
          "required": [
            "en",
            "fr-CA",
            "hy",
            "ru"
          ]
        },
        "headline": {
          "type": "object",
          "properties": {
            "en": {
              "type": "string"
            },
            "fr-CA": {
              "type": "string"
            },
            "hy": {
              "type": "string"
            },
            "ru": {
              "type": "string"
            }
          },
          "required": [
            "en",
            "fr-CA",
            "hy",
            "ru"
          ]
        },
        "milestoneLabel": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "type": "object",
              "properties": {
                "one": {
                  "type": "object",
                  "properties": {
                    "en": {
                      "type": "string"
                    },
                    "fr-CA": {
                      "type": "string"
                    },
                    "hy": {
                      "type": "string"
                    },
                    "ru": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "en",
                    "fr-CA",
                    "hy",
                    "ru"
                  ]
                },
                "few": {
                  "type": "object",
                  "properties": {
                    "en": {
                      "type": "string"
                    },
                    "fr-CA": {
                      "type": "string"
                    },
                    "hy": {
                      "type": "string"
                    },
                    "ru": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "en",
                    "fr-CA",
                    "hy",
                    "ru"
                  ]
                },
                "many": {
                  "type": "object",
                  "properties": {
                    "en": {
                      "type": "string"
                    },
                    "fr-CA": {
                      "type": "string"
                    },
                    "hy": {
                      "type": "string"
                    },
                    "ru": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "en",
                    "fr-CA",
                    "hy",
                    "ru"
                  ]
                },
                "other": {
                  "type": "object",
                  "properties": {
                    "en": {
                      "type": "string"
                    },
                    "fr-CA": {
                      "type": "string"
                    },
                    "hy": {
                      "type": "string"
                    },
                    "ru": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "en",
                    "fr-CA",
                    "hy",
                    "ru"
                  ]
                }
              },
              "required": [
                "one",
                "few",
                "many",
                "other"
              ]
            }
          ],
          "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other."
        }
      },
      "required": [
        "publicName",
        "headline",
        "milestoneLabel"
      ],
      "description": "The program's public name, headline and milestone label."
    },
    "installClaim": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "Twelve characters in groups of four, such as K7Q2-M9XD-4HPA. Hyphens, spaces and case are ignored."
        },
        "expiresAt": {
          "type": "string",
          "description": "The claim stops working at this time, at most 7 days after the capture."
        }
      },
      "required": [
        "code",
        "expiresAt"
      ],
      "description": "Present when the capture asked for an install claim."
    }
  },
  "required": [
    "receipt",
    "checkoutReference",
    "programId",
    "placements",
    "expiresAt",
    "duration",
    "incentive",
    "display"
  ]
}

Errors

Failures return { "error": { "code": "...", "message": "...", "details": {} } }. Details are optional. See error statuses. Reuse an unchanged event payload when retrying.