HTTP endpoints

getReferralIncentive

Read-only preview of a friend or earned offer. An eligible friend offer wins. Otherwise linked partner customer IDs can use an earned offer, soonest expiry first. incentiveKind identifies the kind, and earned offers include rewardId. It holds nothing, so two checkouts can both see it. Reserve only when an order is placed. Send newCustomer from your server's order history, or omit it to use Grizzlee's recorded purchases.

POST /api/v1/referrals/incentive

Requires read. Keep the Bearer key on your server.

SDK

grizzlee.getReferralIncentive(input: { customerId: string; programId?: string | undefined; candidates?: ({ type: "receipt"; receipt: string; } | { type: "code"; referralCode: string; programId?: string | undefined; providerPromoCodeId?: string | undefined; enteredAt?: string | undefined; })[] | undefined; orderId?: string | undefined; signals?: { email?: string | undefined; phone?: string | undefined; phoneHash?: string | undefined; paymentFingerprint?: string | undefined; deviceId?: string | undefined; ipAddress?: string | undefined; } | undefined; newCustomer?: boolean | undefined; categories?: string[] | undefined; customerOrderNumber?: number | undefined; }): Promise<ReferralIncentive>

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/v1/referrals/incentive' \
  -H "Authorization: Bearer $GRIZZLEE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"customerId":"customer-example","orderId":"order-example"}'

Request body

Field	Type	Required	Details
`candidates`	array	No
`programId`	string	No
`customerId`	string	Yes
`newCustomer`	boolean	No
`customerOrderNumber`	integer	No	minimum 1. maximum 1000000
`orderId`	string	No
`categories`	array	No
`signals`	object	No

candidates[]

Variant 1

Field	Type	Required	Details
`candidates.type`	"receipt"	Yes
`candidates.receipt`	string	Yes

Variant 2

Field	Type	Required	Details
`candidates.type`	"code"	Yes
`candidates.referralCode`	string	Yes
`candidates.programId`	string	No
`candidates.providerPromoCodeId`	string	No
`candidates.enteredAt`	string	No	date-time

categories[]

Type: string.

signals

Field	Type	Required
`signals.email`	string	No
`signals.phone`	string	No
`signals.phoneHash`	string	No
`signals.paymentFingerprint`	string	No
`signals.deviceId`	string	No
`signals.ipAddress`	string	No

Request schema

json

{
  "type": "object",
  "properties": {
    "candidates": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "receipt"
              },
              "receipt": {
                "type": "string",
                "maxLength": 4096
              }
            },
            "required": [
              "type",
              "receipt"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "const": "code"
              },
              "referralCode": {
                "type": "string",
                "maxLength": 120
              },
              "programId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "providerPromoCodeId": {
                "type": "string",
                "minLength": 1,
                "maxLength": 120
              },
              "enteredAt": {
                "type": "string",
                "format": "date-time"
              }
            },
            "required": [
              "type",
              "referralCode"
            ],
            "additionalProperties": false
          }
        ]
      },
      "maxItems": 50
    },
    "programId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "customerId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "newCustomer": {
      "type": "boolean"
    },
    "customerOrderNumber": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000000
    },
    "orderId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "categories": {
      "type": "array",
      "items": {
        "allOf": [
          {
            "type": "string"
          },
          {
            "type": "string",
            "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$"
          }
        ]
      },
      "maxItems": 20
    },
    "signals": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "maxLength": 254
        },
        "phone": {
          "type": "string",
          "maxLength": 40
        },
        "phoneHash": {
          "type": "string",
          "pattern": "^[0-9a-fA-F]{64}$"
        },
        "paymentFingerprint": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "deviceId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 255
        },
        "ipAddress": {
          "type": "string",
          "maxLength": 64
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "customerId"
  ],
  "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
`incentiveKind`	union	Yes
`rewardId`	string	No	Present only for earned offers.
`programId`	union	Yes
`partnerId`	union	Yes
`terms`	union	Yes	The offer's terms with currency, or null when there is no offer.
`display`	union	Yes	The program's public name, headline and milestone label. Null when programId is null.
`eligible`	boolean	Yes
`reason`	union	No	Present when eligible is false.
`usesRemaining`	number	Yes	Orders, counting this one, that can still get the incentive. 0 when not eligible.
`expiresAt`	union	Yes	When the incentive stops applying. Null when it never expires or the program has none.
`customerOrderNumber`	number	Yes	The purchase number Grizzlee will give this customer's next order.
`selfReferral`	object	No	Present when customer links or identity signals match the partner. blocked comes with reason self_referral. review means the incentive applies and the partner's reward will wait for review. flagged means the incentive and the reward go ahead as usual, with the match recorded.
`fraud`	object	No	Present when fraud rules fired. blocked comes with reason fraud. review means the incentive applies and the partner's reward will wait for review. flagged records the rules only.
`referralSelection`	object	No

incentiveKind

Variant 1

Type: string.

Variant 2

Type: string.

programId

Variant 1

Type: null.

Variant 2

Type: string.

partnerId

Variant 1

Type: null.

Variant 2

Type: string.

terms

Variant 1

Type: null.

Variant 2

Field	Type	Required	Details
`terms.type`	"percent"	Yes
`terms.rateBps`	number	Yes
`terms.orders`	number	Yes	How many of the friend's orders get the incentive.
`terms.expiresAfterDays`	union	Yes	Days after the referral was captured, claimed or entered. null means it never expires.
`terms.returnOnFullRefund`	boolean	Yes	true: a full refund gives the use back, so the customer can get the offer again.
`terms.maxDiscountCents`	number	No	Largest discount for one order.
`terms.minOrderCents`	number	No	The friend's order total before the discount must reach this amount. Checked by the merchant's checkout.
`terms.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.
`terms.currency`	union	Yes

terms.expiresAfterDays

Variant 1

Type: null.

Variant 2

Type: number.

terms.orderCategories

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

terms.currency

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

Variant 3

Field	Type	Required	Details
`terms.type`	"fixed"	Yes
`terms.orders`	number	Yes	How many of the friend's orders get the incentive.
`terms.expiresAfterDays`	union	Yes	Days after the referral was captured, claimed or entered. null means it never expires.
`terms.returnOnFullRefund`	boolean	Yes	true: a full refund gives the use back, so the customer can get the offer again.
`terms.amountCents`	number	Yes
`terms.minOrderCents`	number	No	The friend's order total before the discount must reach this amount. Checked by the merchant's checkout.
`terms.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.
`terms.currency`	union	Yes

terms.expiresAfterDays

Variant 1

Type: null.

Variant 2

Type: number.

terms.orderCategories

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

terms.currency

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

Variant 4

Field	Type	Required	Details
`terms.type`	"percent"	Yes
`terms.rateBps`	number	Yes
`terms.orders`	number	Yes	How many of the friend's orders get the incentive.
`terms.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.
`terms.expiresAfterDays`	union	Yes	Days after the referral was captured, claimed or entered. null means it never expires.
`terms.returnOnFullRefund`	boolean	Yes	true: a full refund gives the use back, so the customer can get the offer again.
`terms.maxDiscountCents`	number	No	Largest discount for one order.
`terms.minOrderCents`	number	No	The friend's order total before the discount must reach this amount. Checked by the merchant's checkout.
`terms.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.
`terms.currency`	union	Yes

terms.expiresAfterDays

Variant 1

Type: null.

Variant 2

Type: number.

terms.orderCategories

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

terms.currency

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

Variant 5

Field	Type	Required	Details
`terms.type`	"fixed"	Yes
`terms.orders`	number	Yes	How many of the friend's orders get the incentive.
`terms.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.
`terms.expiresAfterDays`	union	Yes	Days after the referral was captured, claimed or entered. null means it never expires.
`terms.returnOnFullRefund`	boolean	Yes	true: a full refund gives the use back, so the customer can get the offer again.
`terms.amountCents`	number	Yes
`terms.minOrderCents`	number	No	The friend's order total before the discount must reach this amount. Checked by the merchant's checkout.
`terms.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.
`terms.currency`	union	Yes

terms.expiresAfterDays

Variant 1

Type: null.

Variant 2

Type: number.

terms.orderCategories

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

terms.currency

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

display

Variant 1

Type: null.

Variant 2

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

reason

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

Variant 5

Type: string.

Variant 6

Type: string.

Variant 7

Type: string.

Variant 8

Type: string.

Variant 9

Type: string.

Variant 10

Type: string.

Variant 11

Type: string.

Variant 12

Type: string.

Variant 13

Type: string.

expiresAt

Variant 1

Type: null.

Variant 2

Type: string.

selfReferral

Field	Type	Required	Details
`selfReferral.action`	union	Yes
`selfReferral.signals`	array	Yes

selfReferral.action

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

selfReferral.signals[]

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

Variant 5

Type: string.

Variant 6

Type: string.

fraud

Field	Type	Required	Details
`fraud.action`	union	Yes
`fraud.rules`	array	Yes

fraud.action

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

fraud.rules[]

Field	Type	Required	Details
`fraud.rules.action`	union	Yes
`fraud.rules.rule`	union	Yes
`fraud.rules.signals`	array	Yes	Matching signal types, never values. Empty for disposable_email.
`fraud.rules.count`	number	No	Customers counted, this one included when referred inside the window. Velocity rules only.

fraud.rules.action

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

fraud.rules.rule

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

fraud.rules.signals[]

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

Variant 5

Type: string.

referralSelection

Field	Type	Required	Details
`referralSelection.winner`	union	Yes
`referralSelection.skipped`	array	Yes

referralSelection.winner

Variant 1

Type: null.

Variant 2

Field	Type	Required	Details
`referralSelection.winner.programId`	string	Yes
`referralSelection.winner.partnerId`	string	Yes
`referralSelection.winner.occurredAt`	string	Yes
`referralSelection.winner.type`	union	No
`referralSelection.winner.providerPromoCodeId`	string	No
`referralSelection.winner.index`	number	No	Absent when the customer's recorded attribution is retained.

referralSelection.winner.type

Variant 1

Type: string.

Variant 2

Type: string.

referralSelection.skipped[]

Field	Type	Required	Details
`referralSelection.skipped.index`	number	Yes
`referralSelection.skipped.reason`	union	Yes

referralSelection.skipped.reason

Variant 1

Type: string.

Variant 2

Type: string.

Variant 3

Type: string.

Variant 4

Type: string.

Variant 5

Type: string.

Variant 6

Type: string.

Variant 7

Type: string.

Variant 8

Type: string.

Variant 9

Type: string.

Response schema

json

{
  "type": "object",
  "properties": {
    "incentiveKind": {
      "anyOf": [
        {
          "type": "string",
          "const": "friend"
        },
        {
          "type": "string",
          "const": "earned"
        }
      ]
    },
    "rewardId": {
      "type": "string",
      "description": "Present only for earned offers."
    },
    "programId": {
      "anyOf": [
        {
          "type": "null"
        },
        {
          "type": "string"
        }
      ]
    },
    "partnerId": {
      "anyOf": [
        {
          "type": "null"
        },
        {
          "type": "string"
        }
      ]
    },
    "terms": {
      "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."
            },
            "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",
            "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."
            },
            "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",
            "expiresAfterDays",
            "returnOnFullRefund",
            "amountCents",
            "currency"
          ]
        },
        {
          "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 offer's terms with currency, or null when there is no offer."
    },
    "display": {
      "anyOf": [
        {
          "type": "null"
        },
        {
          "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. Null when programId is null."
    },
    "eligible": {
      "type": "boolean"
    },
    "reason": {
      "anyOf": [
        {
          "type": "string",
          "const": "expired"
        },
        {
          "type": "string",
          "const": "self_referral"
        },
        {
          "type": "string",
          "const": "program_inactive"
        },
        {
          "type": "string",
          "const": "partner_inactive"
        },
        {
          "type": "string",
          "const": "fraud"
        },
        {
          "type": "string",
          "const": "no_referral"
        },
        {
          "type": "string",
          "const": "category_not_eligible"
        },
        {
          "type": "string",
          "const": "no_incentive"
        },
        {
          "type": "string",
          "const": "not_new_customer"
        },
        {
          "type": "string",
          "const": "order_limit_reached"
        },
        {
          "type": "string",
          "const": "uses_exhausted"
        },
        {
          "type": "string",
          "const": "reservation_open"
        },
        {
          "type": "string",
          "const": "offer_voided"
        }
      ],
      "description": "Present when eligible is false."
    },
    "usesRemaining": {
      "type": "number",
      "description": "Orders, counting this one, that can still get the incentive. 0 when not eligible."
    },
    "expiresAt": {
      "anyOf": [
        {
          "type": "null"
        },
        {
          "type": "string"
        }
      ],
      "description": "When the incentive stops applying. Null when it never expires or the program has none."
    },
    "customerOrderNumber": {
      "type": "number",
      "description": "The purchase number Grizzlee will give this customer's next order."
    },
    "selfReferral": {
      "type": "object",
      "properties": {
        "action": {
          "anyOf": [
            {
              "type": "string",
              "const": "blocked"
            },
            {
              "type": "string",
              "const": "review"
            },
            {
              "type": "string",
              "const": "flagged"
            }
          ]
        },
        "signals": {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string",
                "const": "email"
              },
              {
                "type": "string",
                "const": "phone"
              },
              {
                "type": "string",
                "const": "card"
              },
              {
                "type": "string",
                "const": "device"
              },
              {
                "type": "string",
                "const": "ip"
              },
              {
                "type": "string",
                "const": "customer_id"
              }
            ]
          }
        }
      },
      "required": [
        "action",
        "signals"
      ],
      "description": "Present when customer links or identity signals match the partner. blocked comes with reason\nself_referral. review means the incentive applies and the partner's reward will wait for review.\nflagged means the incentive and the reward go ahead as usual, with the match recorded."
    },
    "fraud": {
      "type": "object",
      "properties": {
        "action": {
          "anyOf": [
            {
              "type": "string",
              "const": "blocked"
            },
            {
              "type": "string",
              "const": "review"
            },
            {
              "type": "string",
              "const": "flagged"
            }
          ]
        },
        "rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "action": {
                "anyOf": [
                  {
                    "type": "string",
                    "const": "blocked"
                  },
                  {
                    "type": "string",
                    "const": "review"
                  },
                  {
                    "type": "string",
                    "const": "flagged"
                  }
                ]
              },
              "rule": {
                "anyOf": [
                  {
                    "type": "string",
                    "const": "duplicate_accounts"
                  },
                  {
                    "type": "string",
                    "const": "rapid_repeats"
                  },
                  {
                    "type": "string",
                    "const": "repeat_customer"
                  },
                  {
                    "type": "string",
                    "const": "disposable_email"
                  }
                ]
              },
              "signals": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "string",
                      "const": "email"
                    },
                    {
                      "type": "string",
                      "const": "phone"
                    },
                    {
                      "type": "string",
                      "const": "card"
                    },
                    {
                      "type": "string",
                      "const": "device"
                    },
                    {
                      "type": "string",
                      "const": "ip"
                    }
                  ]
                },
                "description": "Matching signal types, never values. Empty for disposable_email."
              },
              "count": {
                "type": "number",
                "description": "Customers counted, this one included when referred inside the window. Velocity rules only."
              }
            },
            "required": [
              "action",
              "rule",
              "signals"
            ]
          }
        }
      },
      "required": [
        "action",
        "rules"
      ],
      "description": "Present when fraud rules fired. blocked comes with reason fraud. review means the incentive\napplies and the partner's reward will wait for review. flagged records the rules only."
    },
    "referralSelection": {
      "type": "object",
      "properties": {
        "winner": {
          "anyOf": [
            {
              "type": "null"
            },
            {
              "type": "object",
              "properties": {
                "programId": {
                  "type": "string"
                },
                "partnerId": {
                  "type": "string"
                },
                "occurredAt": {
                  "type": "string"
                },
                "type": {
                  "anyOf": [
                    {
                      "type": "string",
                      "const": "code"
                    },
                    {
                      "type": "string",
                      "const": "receipt"
                    }
                  ]
                },
                "providerPromoCodeId": {
                  "type": "string"
                },
                "index": {
                  "type": "number",
                  "description": "Absent when the customer's recorded attribution is retained."
                }
              },
              "required": [
                "programId",
                "partnerId",
                "occurredAt"
              ]
            }
          ]
        },
        "skipped": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "index": {
                "type": "number"
              },
              "reason": {
                "anyOf": [
                  {
                    "type": "string",
                    "const": "expired"
                  },
                  {
                    "type": "string",
                    "const": "invalid"
                  },
                  {
                    "type": "string",
                    "const": "self_referral"
                  },
                  {
                    "type": "string",
                    "const": "wrong_program"
                  },
                  {
                    "type": "string",
                    "const": "program_inactive"
                  },
                  {
                    "type": "string",
                    "const": "partner_inactive"
                  },
                  {
                    "type": "string",
                    "const": "fraud"
                  },
                  {
                    "type": "string",
                    "const": "customer_already_referred"
                  },
                  {
                    "type": "string",
                    "const": "older"
                  }
                ]
              }
            },
            "required": [
              "index",
              "reason"
            ]
          }
        }
      },
      "required": [
        "winner",
        "skipped"
      ]
    }
  },
  "required": [
    "incentiveKind",
    "programId",
    "partnerId",
    "terms",
    "display",
    "eligible",
    "usesRemaining",
    "expiresAt",
    "customerOrderNumber"
  ]
}

Errors

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