HTTP endpoints
listIncentiveReservations
Latest reservations, or open holds older than the requested number of days.
GET /api/v1/referrals/incentive/reservations
Requires read. Keep the Bearer key on your server.
SDK
ts
grizzlee.listIncentiveReservations(input?: { customerId?: string | undefined; olderThanDays?: number | undefined; }): Promise<{ reservations: IncentiveReservation[]; }>HTTP
Use your backend's HTTP client. The cURL request shows the wire format. Replace path parameters and example values.
sh
curl --fail-with-body --request GET \
'https://app.grizzlee.ca/api/v1/referrals/incentive/reservations' \
-H "Authorization: Bearer $GRIZZLEE_SERVER_KEY"Query parameters
| Field | Type | Required | Details |
|---|---|---|---|
customerId | string | No | |
olderThanDays | integer | No | minimum 0. maximum 100000 |
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 |
|---|---|---|---|
reservations | array | Yes |
reservations[]
| Field | Type | Required | Details |
|---|---|---|---|
reservations.id | string | Yes | |
reservations.companyId | string | Yes | |
reservations.orderId | string | No | The placed order. Absent only on historical quote holds released by migration. |
reservations.customerId | string | Yes | |
reservations.programId | string | Yes | |
reservations.partnerId | string | Yes | |
reservations.status | union | Yes | |
reservations.terms | union | Yes | Terms when the reservation was made. Later program edits leave them alone. |
reservations.incentiveKind | union | No | Absent on historical friend holds. |
reservations.rewardId | string | No | |
reservations.programVersion | number | No | The program version the terms come from. Absent on reservations made before programs had versions. |
reservations.currency | union | Yes | |
reservations.incentiveExpiresAt | union | Yes | When the offer itself stops applying. Earned holds keep the reward's offer expiry. Null when it never expires. |
reservations.referredAt | string | Yes | Earned holds use the reward's createdAt, when the offer was earned. |
reservations.customerOrderNumber | number | Yes | The purchase number Grizzlee expected for the order when it reserved. |
reservations.newCustomer | union | No | The merchant's answer when this hold was made. Omitted, eligibility used recorded purchases. |
reservations.baseCents | number | No | |
reservations.suggestedDiscountCents | number | No | |
reservations.categories | array | No | The categories the order sent when it reserved. The order's own categories are checked again when it completes. |
reservations.createdAt | string | Yes | |
reservations.updatedAt | string | Yes | |
reservations.referralSelection | object | No |
reservations.status
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
reservations.terms
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
reservations.terms.type | "percent" | Yes | |
reservations.terms.rateBps | number | Yes | |
reservations.terms.orders | number | Yes | How many of the friend's orders get the incentive. |
reservations.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. |
reservations.terms.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
reservations.terms.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
reservations.terms.maxDiscountCents | number | No | Largest discount for one order. |
reservations.terms.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
reservations.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. |
reservations.terms.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
reservations.terms.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
reservations.terms.orderCategories.include | array | No | |
reservations.terms.orderCategories.exclude | array | No |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
reservations.terms.type | "fixed" | Yes | |
reservations.terms.orders | number | Yes | How many of the friend's orders get the incentive. |
reservations.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. |
reservations.terms.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
reservations.terms.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
reservations.terms.amountCents | number | Yes | |
reservations.terms.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
reservations.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. |
reservations.terms.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
reservations.terms.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
reservations.terms.orderCategories.include | array | No | |
reservations.terms.orderCategories.exclude | array | No |
Variant 3
| Field | Type | Required | Details |
|---|---|---|---|
reservations.terms.type | "percent" | Yes | |
reservations.terms.rateBps | number | Yes | |
reservations.terms.orders | number | Yes | How many of the friend's orders get the incentive. |
reservations.terms.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
reservations.terms.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
reservations.terms.maxDiscountCents | number | No | Largest discount for one order. |
reservations.terms.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
reservations.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. |
reservations.terms.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
reservations.terms.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
reservations.terms.orderCategories.include | array | No | |
reservations.terms.orderCategories.exclude | array | No |
Variant 4
| Field | Type | Required | Details |
|---|---|---|---|
reservations.terms.type | "fixed" | Yes | |
reservations.terms.orders | number | Yes | How many of the friend's orders get the incentive. |
reservations.terms.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
reservations.terms.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
reservations.terms.amountCents | number | Yes | |
reservations.terms.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
reservations.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. |
reservations.terms.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
reservations.terms.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
reservations.terms.orderCategories.include | array | No | |
reservations.terms.orderCategories.exclude | array | No |
reservations.incentiveKind
Variant 1
Type: string.
Variant 2
Type: string.
reservations.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
reservations.incentiveExpiresAt
Variant 1
Type: null.
Variant 2
Type: string.
reservations.newCustomer
Variant 1
Type: boolean.
Variant 2
Type: boolean.
reservations.referralSelection
| Field | Type | Required | Details |
|---|---|---|---|
reservations.referralSelection.winner | union | Yes | |
reservations.referralSelection.skipped | array | Yes |
reservations.referralSelection.winner
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
reservations.referralSelection.winner.programId | string | Yes | |
reservations.referralSelection.winner.partnerId | string | Yes | |
reservations.referralSelection.winner.occurredAt | string | Yes | |
reservations.referralSelection.winner.type | union | No | |
reservations.referralSelection.winner.providerPromoCodeId | string | No | |
reservations.referralSelection.winner.index | number | No | Absent when the customer's recorded attribution is retained. |
reservations.referralSelection.winner.type
Variant 1
Type: string.
Variant 2
Type: string.
reservations.referralSelection.skipped[]
| Field | Type | Required | Details |
|---|---|---|---|
reservations.referralSelection.skipped.index | number | Yes | |
reservations.referralSelection.skipped.reason | union | Yes |
reservations.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": {
"reservations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"companyId": {
"type": "string"
},
"orderId": {
"type": "string",
"description": "The placed order. Absent only on historical quote holds released by migration."
},
"customerId": {
"type": "string"
},
"programId": {
"type": "string"
},
"partnerId": {
"type": "string"
},
"status": {
"anyOf": [
{
"type": "string",
"const": "open"
},
{
"type": "string",
"const": "consumed"
},
{
"type": "string",
"const": "released"
}
]
},
"terms": {
"anyOf": [
{
"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."
}
},
"required": [
"type",
"rateBps",
"orders",
"newCustomersOnly",
"expiresAfterDays",
"returnOnFullRefund"
]
},
{
"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."
}
},
"required": [
"type",
"orders",
"newCustomersOnly",
"expiresAfterDays",
"returnOnFullRefund",
"amountCents"
]
},
{
"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."
}
},
"required": [
"type",
"rateBps",
"orders",
"expiresAfterDays",
"returnOnFullRefund"
]
},
{
"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."
}
},
"required": [
"type",
"orders",
"expiresAfterDays",
"returnOnFullRefund",
"amountCents"
]
}
],
"description": "Terms when the reservation was made. Later program edits leave them alone."
},
"incentiveKind": {
"anyOf": [
{
"type": "string",
"const": "friend"
},
{
"type": "string",
"const": "earned"
}
],
"description": "Absent on historical friend holds."
},
"rewardId": {
"type": "string"
},
"programVersion": {
"type": "number",
"description": "The program version the terms come from. Absent on reservations made before programs had versions."
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"incentiveExpiresAt": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "When the offer itself stops applying. Earned holds keep the reward's offer expiry. Null when it never expires."
},
"referredAt": {
"type": "string",
"description": "Earned holds use the reward's createdAt, when the offer was earned."
},
"customerOrderNumber": {
"type": "number",
"description": "The purchase number Grizzlee expected for the order when it reserved."
},
"newCustomer": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
],
"description": "The merchant's answer when this hold was made. Omitted, eligibility used recorded purchases."
},
"baseCents": {
"type": "number"
},
"suggestedDiscountCents": {
"type": "number"
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "The categories the order sent when it reserved. The order's own categories are checked again when it completes."
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"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": [
"id",
"companyId",
"customerId",
"programId",
"partnerId",
"status",
"terms",
"currency",
"incentiveExpiresAt",
"referredAt",
"customerOrderNumber",
"createdAt",
"updatedAt"
]
}
}
},
"required": [
"reservations"
]
}Errors
Failures return { "error": { "code": "...", "message": "...", "details": {} } }. Details are optional. See error statuses. Reuse an unchanged event payload when retrying.