HTTP endpoints
claimReferral
POST /api/v1/referrals/claim
Requires partners:write. Keep the Bearer key on your server.
SDK
ts
grizzlee.claimReferral(input: { candidates: ({ type: "receipt"; receipt: string; } | { type: "code"; referralCode: string; programId?: string | undefined; providerPromoCodeId?: string | undefined; enteredAt?: string | undefined; })[]; customerId: string; customerDisplayName?: string | undefined; orderId?: string | undefined; expectedProgramId?: string | undefined; signals?: { email?: string | undefined; phone?: string | undefined; phoneHash?: string | undefined; paymentFingerprint?: string | undefined; deviceId?: string | undefined; ipAddress?: string | undefined; } | undefined; }): Promise<ClaimReferralResult>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 POST \
'https://app.grizzlee.ca/api/v1/referrals/claim' \
-H "Authorization: Bearer $GRIZZLEE_SERVER_KEY" \
-H 'Content-Type: application/json' \
--data '{"candidates":[],"customerId":"customer-example","orderId":"order-example"}'Request body
| Field | Type | Required | Details |
|---|---|---|---|
candidates | array | Yes | |
customerId | string | Yes | |
customerDisplayName | string | No | |
orderId | string | No | |
expectedProgramId | string | 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 |
signals
| Field | Type | Required | Details |
|---|---|---|---|
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
},
"customerId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"customerDisplayName": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"orderId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"expectedProgramId": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"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": [
"candidates",
"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 |
|---|---|---|---|
attribution | union | Yes | |
referralSelection | object | Yes | |
placements | array | Yes |
attribution
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
attribution.id | string | Yes | |
attribution.companyId | string | Yes | |
attribution.partnerId | string | Yes | |
attribution.qualifiedAt | string | No | |
attribution.qualifiedOrderNumber | number | No | |
attribution.programId | string | Yes | |
attribution.referralCode | string | Yes | |
attribution.customerId | string | Yes | |
attribution.occurredAt | string | Yes | |
attribution.channel | union | Yes | |
attribution.providerPromoCodeId | string | No | |
attribution.customerDisplayName | string | No | |
attribution.orderId | string | No |
attribution.channel
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
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": {
"attribution": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"companyId": {
"type": "string"
},
"partnerId": {
"type": "string"
},
"qualifiedAt": {
"type": "string"
},
"qualifiedOrderNumber": {
"type": "number"
},
"programId": {
"type": "string"
},
"referralCode": {
"type": "string"
},
"customerId": {
"type": "string"
},
"occurredAt": {
"type": "string"
},
"channel": {
"anyOf": [
{
"type": "string",
"const": "link"
},
{
"type": "string",
"const": "qr"
},
{
"type": "string",
"const": "coupon"
},
{
"type": "string",
"const": "in_app"
}
]
},
"providerPromoCodeId": {
"type": "string"
},
"customerDisplayName": {
"type": "string"
},
"orderId": {
"type": "string"
}
},
"required": [
"id",
"companyId",
"partnerId",
"programId",
"referralCode",
"customerId",
"occurredAt",
"channel"
]
}
]
},
"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"
]
},
"placements": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"attribution",
"referralSelection",
"placements"
]
}Errors
Failures return { "error": { "code": "...", "message": "...", "details": {} } }. Details are optional. See error statuses. Reuse an unchanged event payload when retrying.