HTTP endpoints
listPartnerRewards
The partner's rewards, newest first, with delivery state. Needs read.
GET /api/v1/partners/{id}/rewards
GET /api/v1/partners/by-external-id/{externalId}/rewards
Requires read. Keep the Bearer key on your server.
SDK
ts
grizzlee.listPartnerRewards(partner: { externalId: string; } | { id: string; }, options?: ListPartnerRewardsOptions | undefined): Promise<PartnerRewardPage>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/partners/{id}/rewards' \
-H "Authorization: Bearer $GRIZZLEE_SERVER_KEY"Query parameters
| Field | Type | Required | Details |
|---|---|---|---|
cursor | string | No | |
limit | integer | No | minimum 1. maximum 100. default 50 |
status | "pending", "approved", "reversed" | No | |
programId | string | No | |
rewardType | "cash", "credit", "offer" | No |
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 |
|---|---|---|---|
rewards | array | Yes | Newest first, ordered by creation time and then ID. |
nextCursor | union | Yes | Pass as cursor to read the next page. Null on the last page. |
rewards[]
| Field | Type | Required | Details |
|---|---|---|---|
rewards.milestoneCount | number | No | Current milestone reports. |
rewards.milestoneThreshold | number | No | Saved at-count bonus count. Absent for each-report rewards. |
rewards.id | string | Yes | |
rewards.trigger | union | Yes | What earned the reward. |
rewards.orderId | union | Yes | The order that earned it. Null for milestone rewards. |
rewards.milestone | union | Yes | The milestone that earned it. Null for order rewards. |
rewards.reportEventId | string | No | |
rewards.valueCents | number | No | |
rewards.programId | string | Yes | |
rewards.programVersion | union | Yes | The program version the reward was earned under. Null for rewards earned before programs had versions. |
rewards.customerId | string | Yes | The merchant's customer ID. |
rewards.currency | union | Yes | |
rewards.rewardType | union | Yes | |
rewards.offer | object | No | Offer rewards only. |
rewards.status | union | Yes | |
rewards.amountCents | number | Yes | Current value: originalCents + adjustedCents - reversedCents. |
rewards.originalCents | number | Yes | |
rewards.adjustedCents | number | Yes | Signed total that order adjustments added or removed. 0 when the order was never adjusted. |
rewards.reversedCents | number | Yes | |
rewards.deliveryMode | union | Yes | |
rewards.delivery | object | Yes | |
rewards.createdAt | string | Yes | |
rewards.approvedAt | union | Yes | First recorded approval. Rewards that started approved use createdAt. Null if never approved. |
rewards.availableAt | string | Yes |
rewards.trigger
Variant 1
Type: string.
Variant 2
Type: string.
rewards.orderId
Variant 1
Type: null.
Variant 2
Type: string.
rewards.milestone
Variant 1
Type: null.
Variant 2
Type: string.
rewards.programVersion
Variant 1
Type: null.
Variant 2
Type: number.
rewards.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
rewards.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
rewards.offer
| Field | Type | Required | Details |
|---|---|---|---|
rewards.offer.terms | union | Yes | |
rewards.offer.status | union | Yes | |
rewards.offer.usesRemaining | number | Yes | |
rewards.offer.usedCount | number | Yes | |
rewards.offer.heldCount | number | Yes | |
rewards.offer.expiresAt | union | Yes |
rewards.offer.terms
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
rewards.offer.terms.type | "percent" | Yes | |
rewards.offer.terms.rateBps | number | Yes | |
rewards.offer.terms.orders | number | Yes | How many of the friend's orders get the incentive. |
rewards.offer.terms.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
rewards.offer.terms.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
rewards.offer.terms.maxDiscountCents | number | No | Largest discount for one order. |
rewards.offer.terms.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
rewards.offer.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. |
rewards.offer.terms.currency | union | Yes |
rewards.offer.terms.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
rewards.offer.terms.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
rewards.offer.terms.orderCategories.include | array | No | |
rewards.offer.terms.orderCategories.exclude | array | No |
rewards.offer.terms.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
rewards.offer.terms.type | "fixed" | Yes | |
rewards.offer.terms.orders | number | Yes | How many of the friend's orders get the incentive. |
rewards.offer.terms.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
rewards.offer.terms.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
rewards.offer.terms.amountCents | number | Yes | |
rewards.offer.terms.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
rewards.offer.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. |
rewards.offer.terms.currency | union | Yes |
rewards.offer.terms.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
rewards.offer.terms.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
rewards.offer.terms.orderCategories.include | array | No | |
rewards.offer.terms.orderCategories.exclude | array | No |
rewards.offer.terms.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
rewards.offer.status
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
Variant 5
Type: string.
rewards.offer.expiresAt
Variant 1
Type: null.
Variant 2
Type: string.
rewards.status
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
rewards.deliveryMode
Variant 1
Type: string.
Variant 2
Type: string.
rewards.delivery
| Field | Type | Required | Details |
|---|---|---|---|
rewards.delivery.status | union | Yes | |
rewards.delivery.externalReference | union | Yes | Reference of the latest delivered record, or of the failed attempt when status is failed. Null if none. |
rewards.delivery.deliveredAt | union | Yes | When the latest delivered record says the partner received it. |
rewards.delivery.payoutId | union | Yes | The open payout when status is in_payout. Otherwise the payout that recorded the latest delivery, if any. |
rewards.delivery.status
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
Variant 5
Type: string.
rewards.delivery.externalReference
Variant 1
Type: null.
Variant 2
Type: string.
rewards.delivery.deliveredAt
Variant 1
Type: null.
Variant 2
Type: string.
rewards.delivery.payoutId
Variant 1
Type: null.
Variant 2
Type: string.
rewards.approvedAt
Variant 1
Type: null.
Variant 2
Type: string.
nextCursor
Variant 1
Type: null.
Variant 2
Type: string.
Response schema
json
{
"type": "object",
"properties": {
"rewards": {
"type": "array",
"items": {
"type": "object",
"properties": {
"milestoneCount": {
"type": "number",
"description": "Current milestone reports."
},
"milestoneThreshold": {
"type": "number",
"description": "Saved at-count bonus count. Absent for each-report rewards."
},
"id": {
"type": "string"
},
"trigger": {
"anyOf": [
{
"type": "string",
"const": "order"
},
{
"type": "string",
"const": "milestone"
}
],
"description": "What earned the reward."
},
"orderId": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "The order that earned it. Null for milestone rewards."
},
"milestone": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "The milestone that earned it. Null for order rewards."
},
"reportEventId": {
"type": "string"
},
"valueCents": {
"type": "number"
},
"programId": {
"type": "string"
},
"programVersion": {
"anyOf": [
{
"type": "null"
},
{
"type": "number"
}
],
"description": "The program version the reward was earned under. Null for rewards earned before programs had versions."
},
"customerId": {
"type": "string",
"description": "The merchant's customer ID."
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "offer"
},
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"offer": {
"type": "object",
"properties": {
"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."
},
"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"
]
}
]
},
"status": {
"anyOf": [
{
"type": "string",
"const": "expired"
},
{
"type": "string",
"const": "pending"
},
{
"type": "string",
"const": "available"
},
{
"type": "string",
"const": "used"
},
{
"type": "string",
"const": "voided"
}
]
},
"usesRemaining": {
"type": "number"
},
"usedCount": {
"type": "number"
},
"heldCount": {
"type": "number"
},
"expiresAt": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
}
},
"required": [
"terms",
"status",
"usesRemaining",
"usedCount",
"heldCount",
"expiresAt"
],
"description": "Offer rewards only."
},
"status": {
"anyOf": [
{
"type": "string",
"const": "pending"
},
{
"type": "string",
"const": "reversed"
},
{
"type": "string",
"const": "approved"
}
]
},
"amountCents": {
"type": "number",
"description": "Current value: originalCents + adjustedCents - reversedCents."
},
"originalCents": {
"type": "number"
},
"adjustedCents": {
"type": "number",
"description": "Signed total that order adjustments added or removed. 0 when the order was never adjusted."
},
"reversedCents": {
"type": "number"
},
"deliveryMode": {
"anyOf": [
{
"type": "string",
"const": "grizzlee_wallet"
},
{
"type": "string",
"const": "merchant"
}
]
},
"delivery": {
"type": "object",
"properties": {
"status": {
"anyOf": [
{
"type": "string",
"const": "not_applicable"
},
{
"type": "string",
"const": "undelivered"
},
{
"type": "string",
"const": "in_payout"
},
{
"type": "string",
"const": "delivered"
},
{
"type": "string",
"const": "failed"
}
]
},
"externalReference": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "Reference of the latest delivered record, or of the failed attempt when status is failed. Null if none."
},
"deliveredAt": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "When the latest delivered record says the partner received it."
},
"payoutId": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "The open payout when status is in_payout. Otherwise the payout that recorded the latest delivery, if any."
}
},
"required": [
"status",
"externalReference",
"deliveredAt",
"payoutId"
]
},
"createdAt": {
"type": "string"
},
"approvedAt": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "First recorded approval. Rewards that started approved use createdAt. Null if never approved."
},
"availableAt": {
"type": "string"
}
},
"required": [
"id",
"trigger",
"orderId",
"milestone",
"programId",
"programVersion",
"customerId",
"currency",
"rewardType",
"status",
"amountCents",
"originalCents",
"adjustedCents",
"reversedCents",
"deliveryMode",
"delivery",
"createdAt",
"approvedAt",
"availableAt"
]
},
"description": "Newest first, ordered by creation time and then ID."
},
"nextCursor": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "Pass as cursor to read the next page. Null on the last page."
}
},
"required": [
"rewards",
"nextCursor"
]
}Errors
Failures return { "error": { "code": "...", "message": "...", "details": {} } }. Details are optional. See error statuses. Reuse an unchanged event payload when retrying.