HTTP endpoints
listPartnerReferrals
Customers the partner referred, including displaced and not-yet-purchased referrals. Needs read.
GET /api/v1/partners/{id}/referrals
GET /api/v1/partners/by-external-id/{externalId}/referrals
Requires read. Keep the Bearer key on your server.
SDK
ts
grizzlee.listPartnerReferrals(partner: { externalId: string; } | { id: string; }, options?: ListPartnerReferralsOptions | undefined): Promise<PartnerReferralPage>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}/referrals' \
-H "Authorization: Bearer $GRIZZLEE_SERVER_KEY"Query parameters
| Field | Type | Required | Details |
|---|---|---|---|
cursor | string | No | |
limit | integer | No | minimum 1. maximum 100. default 50 |
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 |
|---|---|---|---|
referrals | array | Yes | Newest first, by when Grizzlee first recorded this partner's referral. |
nextCursor | union | Yes | Pass as cursor to read the next page. Null on the last page. |
referrals[]
| Field | Type | Required | Details |
|---|---|---|---|
referrals.milestone | string | No | Milestone reports since this referral. Earned bonuses retain their original threshold. |
referrals.milestoneCount | number | No | |
referrals.milestoneThreshold | number | No | Effective at-count bonus count. Absent for each-report-only rules. |
referrals.attributionId | string | Yes | |
referrals.customerId | string | Yes | The merchant's customer ID. |
referrals.customerDisplayName | string | No | |
referrals.programId | string | Yes | |
referrals.orderId | union | Yes | The referred order for order-scoped referrals, otherwise null. |
referrals.channel | union | Yes | |
referrals.referredAt | string | Yes | This partner's latest referral of the customer in this program. |
referrals.status | union | Yes | |
referrals.qualifiedAt | union | Yes | Set when status is qualified. |
referrals.firstOrderId | union | Yes | Earliest order from this referral that earned this partner a reward. |
referrals.orderCount | number | Yes | Orders from this referral that earned this partner a reward. Milestone rewards are not orders. |
referrals.milestones | array | Yes | Milestones from this referral that earned this partner a reward, oldest first. |
referrals.rewardedCents | number | Yes | Those rewards after reversals. |
referrals.incentiveAppliedCents | number | Yes | Friend incentive discounts the merchant applied to this customer's orders through this partner's referral. |
referrals.orderId
Variant 1
Type: null.
Variant 2
Type: string.
referrals.channel
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
referrals.status
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
referrals.qualifiedAt
Variant 1
Type: null.
Variant 2
Type: string.
referrals.firstOrderId
Variant 1
Type: null.
Variant 2
Type: string.
nextCursor
Variant 1
Type: null.
Variant 2
Type: string.
Response schema
json
{
"type": "object",
"properties": {
"referrals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"milestone": {
"type": "string",
"description": "Milestone reports since this referral. Earned bonuses retain their original threshold."
},
"milestoneCount": {
"type": "number"
},
"milestoneThreshold": {
"type": "number",
"description": "Effective at-count bonus count. Absent for each-report-only rules."
},
"attributionId": {
"type": "string"
},
"customerId": {
"type": "string",
"description": "The merchant's customer ID."
},
"customerDisplayName": {
"type": "string"
},
"programId": {
"type": "string"
},
"orderId": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "The referred order for order-scoped referrals, otherwise null."
},
"channel": {
"anyOf": [
{
"type": "string",
"const": "link"
},
{
"type": "string",
"const": "qr"
},
{
"type": "string",
"const": "coupon"
},
{
"type": "string",
"const": "in_app"
}
]
},
"referredAt": {
"type": "string",
"description": "This partner's latest referral of the customer in this program."
},
"status": {
"anyOf": [
{
"type": "string",
"const": "expired"
},
{
"type": "string",
"const": "claimed"
},
{
"type": "string",
"const": "qualified"
},
{
"type": "string",
"const": "displaced"
}
]
},
"qualifiedAt": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "Set when status is qualified."
},
"firstOrderId": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "Earliest order from this referral that earned this partner a reward."
},
"orderCount": {
"type": "number",
"description": "Orders from this referral that earned this partner a reward. Milestone rewards are not orders."
},
"milestones": {
"type": "array",
"items": {
"type": "string"
},
"description": "Milestones from this referral that earned this partner a reward, oldest first."
},
"rewardedCents": {
"type": "number",
"description": "Those rewards after reversals."
},
"incentiveAppliedCents": {
"type": "number",
"description": "Friend incentive discounts the merchant applied to this customer's orders through this partner's referral."
}
},
"required": [
"attributionId",
"customerId",
"programId",
"orderId",
"channel",
"referredAt",
"status",
"qualifiedAt",
"firstOrderId",
"orderCount",
"milestones",
"rewardedCents",
"incentiveAppliedCents"
]
},
"description": "Newest first, by when Grizzlee first recorded this partner's referral."
},
"nextCursor": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "Pass as cursor to read the next page. Null on the last page."
}
},
"required": [
"referrals",
"nextCursor"
]
}Errors
Failures return { "error": { "code": "...", "message": "...", "details": {} } }. Details are optional. See error statuses. Reuse an unchanged event payload when retrying.