HTTP endpoints
getPartnerSummary
GET /api/v1/partners/{id}/summary
GET /api/v1/partners/by-external-id/{externalId}/summary
Requires read. Keep the Bearer key on your server.
SDK
ts
grizzlee.getPartnerSummary(partner: { externalId: string; } | { id: string; }): Promise<PartnerSummary>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}/summary' \
-H "Authorization: Bearer $GRIZZLEE_SERVER_KEY"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 |
|---|---|---|---|
id | string | Yes | |
externalId | string | Yes | |
name | string | Yes | |
active | boolean | Yes | |
referralCode | string | Yes | |
clicks | object | Yes | Link and QR activity across all programs, including former memberships. |
programs | array | Yes | Current memberships in programIds order, then former programs with rewards, referrals, payout allocations or debt, sorted by ID. |
balances | object | Yes | |
payoutAccountRequired | boolean | Yes | True when the payout schedule waits for a Stripe account (missingStripeAccount "wait"), the partner has no stripeAccountId, and the partner earns merchant-delivered cash: it belongs to such a program or has such cash pending or approved. Scheduled runs pay this partner nothing until it gets a stripeAccountId. |
awaitingPayoutAccount | boolean | Yes | True when payoutAccountRequired and a scheduled run already held a payout for it. |
awaitingPayoutAccountSince | union | Yes | Due date (YYYY-MM-DD) of the first run that held a payout. Null unless awaitingPayoutAccount. |
clicks
| Field | Type | Required | Details |
|---|---|---|---|
clicks.total | number | Yes | All recorded activity, including repeat visits and unclaimed or voided receipts. |
clicks.last30Days | number | Yes | Activity in the rolling 30 days ending at the summary's read time. |
programs[]
| Field | Type | Required | Details |
|---|---|---|---|
programs.id | string | Yes | |
programs.name | string | Yes | |
programs.active | boolean | Yes | |
programs.member | boolean | Yes | Whether the partner currently belongs to this program. Former memberships keep their totals. |
programs.tracking | object | Yes | |
programs.attributionCode | union | Yes | |
programs.alias | union | Yes | The partner's short code, such as KARL7Q, when attributionCode is set. Customers can type either. |
programs.promoCodes | array | Yes | |
programs.qrLink | union | Yes | |
programs.currency | union | Yes | |
programs.rewardType | union | Yes | |
programs.trigger | union | Yes | What earns a reward in this program. |
programs.deliveryMode | union | Yes | Who delivers this program's rewards: the Grizzlee wallet or the merchant. |
programs.compensation | union | No | Order compensation, with this partner's custom terms when present. Absent for milestones. |
programs.milestoneRewards | object | No | |
programs.fixedRefundMode | union | Yes | How this program refunds fixed rewards. Percentage rewards keep their commission base. |
programs.incentive | union | Yes | What a referred customer gets in this program. Null without an offer or a current membership. |
programs.terms | object | Yes | Readable reward terms. Former memberships omit the friend incentive from the text. |
programs.display | object | Yes | Public name, headline and milestone label. The headline falls back to terms.text.headline. |
programs.link | union | Yes | Referral link to the program's published destination. Null when unavailable or membership ended. |
programs.linkUnavailableReason | union | Yes | Set when link is null, otherwise null. |
programs.clicks | object | Yes | Link and QR activity in this program. Coupon and in-app channels are excluded. |
programs.earnedCents | number | Yes | Reward value after reversals, across saved reward types and delivery modes. |
programs.reversedCents | number | Yes | Reward value currently reversed. Restorations reduce this total. |
programs.referrals | object | Yes | Each attribution counts once, including displaced referrals and separate order-scoped referrals. |
programs.orderCount | number | Yes | Sum of referral orderCount values in this program. Reversed rewards still count; milestones do not. |
programs.payouts | object | Yes | Paid merchant allocations less returned transfers. Wallet payouts have no program allocations. |
programs.balances | object | Yes |
programs.tracking
| Field | Type | Required | Details |
|---|---|---|---|
programs.tracking.links | boolean | Yes | |
programs.tracking.qrCodes | boolean | Yes | |
programs.tracking.attributionCodes | boolean | Yes | |
programs.tracking.providerPromoCodes | boolean | Yes |
programs.attributionCode
Variant 1
Type: null.
Variant 2
Type: string.
programs.alias
Variant 1
Type: null.
Variant 2
Type: string.
programs.promoCodes[]
| Field | Type | Required | Details |
|---|---|---|---|
programs.promoCodes.id | string | Yes | |
programs.promoCodes.companyId | string | Yes | |
programs.promoCodes.partnerId | string | Yes | |
programs.promoCodes.programId | string | Yes | |
programs.promoCodes.integrationId | string | Yes | |
programs.promoCodes.provider | union | Yes | |
programs.promoCodes.code | string | Yes | |
programs.promoCodes.providerCodeId | union | Yes | Null until Grizzlee has saved the provider discount ID. |
programs.promoCodes.status | union | Yes | |
programs.promoCodes.replacesId | string | No | |
programs.promoCodes.couponId | string | No | |
programs.promoCodes.incentive | union | Yes | |
programs.promoCodes.programVersion | number | Yes | |
programs.promoCodes.active | boolean | Yes | |
programs.promoCodes.createdAt | string | Yes | |
programs.promoCodes.deactivatedAt | string | No |
programs.promoCodes.provider
Variant 1
Type: string.
Variant 2
Type: string.
programs.promoCodes.providerCodeId
Variant 1
Type: null.
Variant 2
Type: string.
programs.promoCodes.status
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
programs.promoCodes.incentive
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programs.promoCodes.incentive.type | "percent" | Yes | |
programs.promoCodes.incentive.rateBps | number | Yes | |
programs.promoCodes.incentive.orders | number | Yes | How many of the friend's orders get the incentive. |
programs.promoCodes.incentive.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. |
programs.promoCodes.incentive.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
programs.promoCodes.incentive.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
programs.promoCodes.incentive.maxDiscountCents | number | No | Largest discount for one order. |
programs.promoCodes.incentive.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programs.promoCodes.incentive.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. |
programs.promoCodes.incentive.currency | union | Yes |
programs.promoCodes.incentive.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programs.promoCodes.incentive.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programs.promoCodes.incentive.orderCategories.include | array | No | |
programs.promoCodes.incentive.orderCategories.exclude | array | No |
programs.promoCodes.incentive.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.promoCodes.incentive.type | "fixed" | Yes | |
programs.promoCodes.incentive.orders | number | Yes | How many of the friend's orders get the incentive. |
programs.promoCodes.incentive.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. |
programs.promoCodes.incentive.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
programs.promoCodes.incentive.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
programs.promoCodes.incentive.amountCents | number | Yes | |
programs.promoCodes.incentive.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programs.promoCodes.incentive.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. |
programs.promoCodes.incentive.currency | union | Yes |
programs.promoCodes.incentive.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programs.promoCodes.incentive.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programs.promoCodes.incentive.orderCategories.include | array | No | |
programs.promoCodes.incentive.orderCategories.exclude | array | No |
programs.promoCodes.incentive.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programs.qrLink
Variant 1
Type: null.
Variant 2
Type: string.
programs.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programs.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
programs.trigger
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programs.trigger.type | "order" | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.trigger.type | "milestone" | Yes | |
programs.trigger.milestone | string | Yes |
programs.deliveryMode
Variant 1
Type: string.
Variant 2
Type: string.
programs.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programs.compensation.type | "percentage" | Yes | |
programs.compensation.rateBps | number | Yes | |
programs.compensation.phases | array | No |
programs.compensation.phases[]
| Field | Type | Required | Details |
|---|---|---|---|
programs.compensation.phases.rateBps | number | Yes | |
programs.compensation.phases.afterMonths | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.compensation.type | "fixed" | Yes | |
programs.compensation.amountCents | number | Yes |
programs.milestoneRewards
| Field | Type | Required | Details |
|---|---|---|---|
programs.milestoneRewards.eachReport | object | No | |
programs.milestoneRewards.atCount | object | No |
programs.milestoneRewards.eachReport
| Field | Type | Required | Details |
|---|---|---|---|
programs.milestoneRewards.eachReport.compensation | union | Yes | |
programs.milestoneRewards.eachReport.limit | number | No | Absent means every counted report. Reversed reports do not count toward the limit. |
programs.milestoneRewards.eachReport.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programs.milestoneRewards.eachReport.compensation.type | "fixed" | Yes | |
programs.milestoneRewards.eachReport.compensation.amountCents | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.milestoneRewards.eachReport.compensation.type | "percentage" | Yes | |
programs.milestoneRewards.eachReport.compensation.rateBps | number | Yes |
programs.milestoneRewards.atCount
| Field | Type | Required | Details |
|---|---|---|---|
programs.milestoneRewards.atCount.amountCents | number | Yes | |
programs.milestoneRewards.atCount.count | number | Yes |
programs.fixedRefundMode
Variant 1
Type: string.
Variant 2
Type: string.
programs.incentive
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.incentive.type | "percent" | Yes | |
programs.incentive.rateBps | number | Yes | |
programs.incentive.orders | number | Yes | How many of the friend's orders get the incentive. |
programs.incentive.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. |
programs.incentive.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
programs.incentive.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
programs.incentive.maxDiscountCents | number | No | Largest discount for one order. |
programs.incentive.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programs.incentive.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. |
programs.incentive.currency | union | Yes |
programs.incentive.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programs.incentive.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programs.incentive.orderCategories.include | array | No | |
programs.incentive.orderCategories.exclude | array | No |
programs.incentive.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
Variant 3
| Field | Type | Required | Details |
|---|---|---|---|
programs.incentive.type | "fixed" | Yes | |
programs.incentive.orders | number | Yes | How many of the friend's orders get the incentive. |
programs.incentive.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. |
programs.incentive.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
programs.incentive.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
programs.incentive.amountCents | number | Yes | |
programs.incentive.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programs.incentive.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. |
programs.incentive.currency | union | Yes |
programs.incentive.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programs.incentive.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programs.incentive.orderCategories.include | array | No | |
programs.incentive.orderCategories.exclude | array | No |
programs.incentive.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programs.terms
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.trigger | union | Yes | |
programs.terms.rewardType | union | Yes | |
programs.terms.currency | union | Yes | |
programs.terms.compensation | union | Yes | What the partner earns. This partner's custom terms replace the program's when it has them. |
programs.terms.partnerOffer | union | Yes | The partner's earned discount with currency. Null for money rewards. |
programs.terms.milestoneRewards | object | No | |
programs.terms.duration | union | Yes | Which orders of a referred customer earn a reward. Null for milestone programs. |
programs.terms.fixedRefundMode | union | Yes | How a partial refund changes a fixed order reward. Null for percentage and milestone rewards. |
programs.terms.referralWindowDays | union | Yes | Days a referral stays open until an order or milestone qualifies it. Null when it never expires. |
programs.terms.text | object | Yes |
programs.terms.trigger
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.trigger.type | "order" | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.trigger.type | "milestone" | Yes | |
programs.terms.trigger.milestone | string | Yes |
programs.terms.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
programs.terms.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programs.terms.compensation
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.compensation.type | "percentage" | Yes | |
programs.terms.compensation.rateBps | number | Yes | Base rate, before any performance tier bonus. |
programs.terms.compensation.phases | array | Yes | Later rates by months after the customer's first rewarded order. Empty when the rate never changes. |
programs.terms.compensation.phases[]
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.compensation.phases.afterMonths | number | Yes | |
programs.terms.compensation.phases.rateBps | number | Yes |
Variant 3
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.compensation.type | "fixed" | Yes | |
programs.terms.compensation.amountCents | number | Yes |
programs.terms.partnerOffer
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.partnerOffer.type | "percent" | Yes | |
programs.terms.partnerOffer.rateBps | number | Yes | |
programs.terms.partnerOffer.orders | number | Yes | How many of the friend's orders get the incentive. |
programs.terms.partnerOffer.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
programs.terms.partnerOffer.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
programs.terms.partnerOffer.maxDiscountCents | number | No | Largest discount for one order. |
programs.terms.partnerOffer.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programs.terms.partnerOffer.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. |
programs.terms.partnerOffer.currency | union | Yes |
programs.terms.partnerOffer.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programs.terms.partnerOffer.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.partnerOffer.orderCategories.include | array | No | |
programs.terms.partnerOffer.orderCategories.exclude | array | No |
programs.terms.partnerOffer.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
Variant 3
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.partnerOffer.type | "fixed" | Yes | |
programs.terms.partnerOffer.orders | number | Yes | How many of the friend's orders get the incentive. |
programs.terms.partnerOffer.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
programs.terms.partnerOffer.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
programs.terms.partnerOffer.amountCents | number | Yes | |
programs.terms.partnerOffer.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programs.terms.partnerOffer.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. |
programs.terms.partnerOffer.currency | union | Yes |
programs.terms.partnerOffer.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programs.terms.partnerOffer.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.partnerOffer.orderCategories.include | array | No | |
programs.terms.partnerOffer.orderCategories.exclude | array | No |
programs.terms.partnerOffer.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programs.terms.milestoneRewards
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.milestoneRewards.eachReport | object | No | |
programs.terms.milestoneRewards.atCount | object | No |
programs.terms.milestoneRewards.eachReport
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.milestoneRewards.eachReport.compensation | union | Yes | |
programs.terms.milestoneRewards.eachReport.limit | number | No | Absent means every counted report. Reversed reports do not count toward the limit. |
programs.terms.milestoneRewards.eachReport.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.milestoneRewards.eachReport.compensation.type | "fixed" | Yes | |
programs.terms.milestoneRewards.eachReport.compensation.amountCents | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.milestoneRewards.eachReport.compensation.type | "percentage" | Yes | |
programs.terms.milestoneRewards.eachReport.compensation.rateBps | number | Yes |
programs.terms.milestoneRewards.atCount
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.milestoneRewards.atCount.amountCents | number | Yes | |
programs.terms.milestoneRewards.atCount.count | number | Yes |
programs.terms.duration
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.duration.type | "only_order" | Yes |
Variant 3
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.duration.type | "first_order" | Yes |
Variant 4
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.duration.type | "first_n_orders" | Yes | |
programs.terms.duration.count | number | Yes |
Variant 5
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.duration.type | "days" | Yes | |
programs.terms.duration.days | number | Yes |
Variant 6
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.duration.type | "months" | Yes | |
programs.terms.duration.months | number | Yes |
Variant 7
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.duration.type | "lifetime" | Yes |
programs.terms.fixedRefundMode
Variant 1
Type: null.
Variant 2
Type: string.
Variant 3
Type: string.
programs.terms.referralWindowDays
Variant 1
Type: null.
Variant 2
Type: number.
programs.terms.text
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.text.reward | object | Yes | What the partner earns, such as "$10 credit when your friend completes their first order after your referral". |
programs.terms.text.incentive | union | Yes | What the referred friend gets, such as "20% off your first order". Null without a friend incentive. |
programs.terms.text.headline | object | Yes | Both sides in a few words, such as "Give 20%, get $10", or "Get $10" without a friend incentive. |
programs.terms.text.reward
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.text.reward.en | string | Yes | |
programs.terms.text.reward.fr-CA | string | Yes | |
programs.terms.text.reward.hy | string | Yes | |
programs.terms.text.reward.ru | string | Yes |
programs.terms.text.incentive
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.text.incentive.en | string | Yes | |
programs.terms.text.incentive.fr-CA | string | Yes | |
programs.terms.text.incentive.hy | string | Yes | |
programs.terms.text.incentive.ru | string | Yes |
programs.terms.text.headline
| Field | Type | Required | Details |
|---|---|---|---|
programs.terms.text.headline.en | string | Yes | |
programs.terms.text.headline.fr-CA | string | Yes | |
programs.terms.text.headline.hy | string | Yes | |
programs.terms.text.headline.ru | string | Yes |
programs.display
| Field | Type | Required | Details |
|---|---|---|---|
programs.display.publicName | object | Yes | |
programs.display.headline | object | Yes | |
programs.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. |
programs.display.publicName
| Field | Type | Required | Details |
|---|---|---|---|
programs.display.publicName.en | string | Yes | |
programs.display.publicName.fr-CA | string | Yes | |
programs.display.publicName.hy | string | Yes | |
programs.display.publicName.ru | string | Yes |
programs.display.headline
| Field | Type | Required | Details |
|---|---|---|---|
programs.display.headline.en | string | Yes | |
programs.display.headline.fr-CA | string | Yes | |
programs.display.headline.hy | string | Yes | |
programs.display.headline.ru | string | Yes |
programs.display.milestoneLabel
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programs.display.milestoneLabel.one | object | Yes | |
programs.display.milestoneLabel.few | object | Yes | |
programs.display.milestoneLabel.many | object | Yes | |
programs.display.milestoneLabel.other | object | Yes |
programs.display.milestoneLabel.one
| Field | Type | Required | Details |
|---|---|---|---|
programs.display.milestoneLabel.one.en | string | Yes | |
programs.display.milestoneLabel.one.fr-CA | string | Yes | |
programs.display.milestoneLabel.one.hy | string | Yes | |
programs.display.milestoneLabel.one.ru | string | Yes |
programs.display.milestoneLabel.few
| Field | Type | Required | Details |
|---|---|---|---|
programs.display.milestoneLabel.few.en | string | Yes | |
programs.display.milestoneLabel.few.fr-CA | string | Yes | |
programs.display.milestoneLabel.few.hy | string | Yes | |
programs.display.milestoneLabel.few.ru | string | Yes |
programs.display.milestoneLabel.many
| Field | Type | Required | Details |
|---|---|---|---|
programs.display.milestoneLabel.many.en | string | Yes | |
programs.display.milestoneLabel.many.fr-CA | string | Yes | |
programs.display.milestoneLabel.many.hy | string | Yes | |
programs.display.milestoneLabel.many.ru | string | Yes |
programs.display.milestoneLabel.other
| Field | Type | Required | Details |
|---|---|---|---|
programs.display.milestoneLabel.other.en | string | Yes | |
programs.display.milestoneLabel.other.fr-CA | string | Yes | |
programs.display.milestoneLabel.other.hy | string | Yes | |
programs.display.milestoneLabel.other.ru | string | Yes |
programs.link
Variant 1
Type: null.
Variant 2
Type: string.
programs.linkUnavailableReason
Variant 1
Type: null.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
Variant 5
Type: string.
Variant 6
Type: string.
programs.clicks
| Field | Type | Required | Details |
|---|---|---|---|
programs.clicks.total | number | Yes | All recorded activity, including repeat visits and unclaimed or voided receipts. |
programs.clicks.last30Days | number | Yes | Activity in the rolling 30 days ending at the summary's read time. |
programs.referrals
| Field | Type | Required | Details |
|---|---|---|---|
programs.referrals.referred | number | Yes | |
programs.referrals.qualified | number | Yes |
programs.payouts
| Field | Type | Required | Details |
|---|---|---|---|
programs.payouts.paidOutCents | number | Yes |
programs.balances
| Field | Type | Required | Details |
|---|---|---|---|
programs.balances.wallet | object | Yes | Wallet spending, reservations and debt cannot be attributed to a program. |
programs.balances.merchant | object | Yes |
programs.balances.wallet
| Field | Type | Required | Details |
|---|---|---|---|
programs.balances.wallet.cash | object | Yes | |
programs.balances.wallet.credit | object | Yes |
programs.balances.wallet.cash
| Field | Type | Required | Details |
|---|---|---|---|
programs.balances.wallet.cash.currency | union | Yes | |
programs.balances.wallet.cash.rewardType | union | Yes | |
programs.balances.wallet.cash.pendingApprovalCents | number | Yes | Pending rewards after reversals. |
programs.balances.wallet.cash.approvedCents | number | Yes | Every approved reward after reversals, including amounts already reserved, paid or redeemed. |
programs.balances.wallet.cash.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programs.balances.wallet.cash.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
programs.balances.wallet.credit
| Field | Type | Required | Details |
|---|---|---|---|
programs.balances.wallet.credit.currency | union | Yes | |
programs.balances.wallet.credit.rewardType | union | Yes | |
programs.balances.wallet.credit.pendingApprovalCents | number | Yes | Pending rewards after reversals. |
programs.balances.wallet.credit.approvedCents | number | Yes | Every approved reward after reversals, including amounts already reserved, paid or redeemed. |
programs.balances.wallet.credit.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programs.balances.wallet.credit.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
programs.balances.merchant
| Field | Type | Required | Details |
|---|---|---|---|
programs.balances.merchant.cash | object | Yes | |
programs.balances.merchant.credit | object | Yes |
programs.balances.merchant.cash
| Field | Type | Required | Details |
|---|---|---|---|
programs.balances.merchant.cash.version | number | Yes | Partner-wide accounting history count shared by cash, credit and program merchant balances. |
programs.balances.merchant.cash.rewardType | union | Yes | |
programs.balances.merchant.cash.currency | union | Yes | |
programs.balances.merchant.cash.pendingApprovalCents | number | Yes | Pending rewards the partner is still owed. |
programs.balances.merchant.cash.approvedUndeliveredCents | number | Yes | Approved and owed, not delivered yet and not in an open merchant payout. |
programs.balances.merchant.cash.inOpenPayoutsCents | number | Yes | Approved and owed, allocated to a merchant payout that is queued, processing or needs action. |
programs.balances.merchant.cash.deliveredGrossCents | number | Yes | Delivered gross amounts less returned transfers, before reward refunds or debt settlements. |
programs.balances.merchant.cash.debtCents | number | Yes | Delivered amounts that later refunds reversed and the partner has not repaid. |
programs.balances.merchant.cash.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
programs.balances.merchant.cash.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programs.balances.merchant.credit
| Field | Type | Required | Details |
|---|---|---|---|
programs.balances.merchant.credit.version | number | Yes | Partner-wide accounting history count shared by cash, credit and program merchant balances. |
programs.balances.merchant.credit.rewardType | union | Yes | |
programs.balances.merchant.credit.currency | union | Yes | |
programs.balances.merchant.credit.pendingApprovalCents | number | Yes | Pending rewards the partner is still owed. |
programs.balances.merchant.credit.approvedUndeliveredCents | number | Yes | Approved and owed, not delivered yet and not in an open merchant payout. |
programs.balances.merchant.credit.inOpenPayoutsCents | number | Yes | Approved and owed, allocated to a merchant payout that is queued, processing or needs action. |
programs.balances.merchant.credit.deliveredGrossCents | number | Yes | Delivered gross amounts less returned transfers, before reward refunds or debt settlements. |
programs.balances.merchant.credit.debtCents | number | Yes | Delivered amounts that later refunds reversed and the partner has not repaid. |
programs.balances.merchant.credit.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
programs.balances.merchant.credit.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
balances
| Field | Type | Required | Details |
|---|---|---|---|
balances.wallet | object | Yes | |
balances.merchant | object | Yes |
balances.wallet
| Field | Type | Required | Details |
|---|---|---|---|
balances.wallet.cash | object | Yes | |
balances.wallet.credit | object | Yes |
balances.wallet.cash
| Field | Type | Required | Details |
|---|---|---|---|
balances.wallet.cash.rewardType | union | Yes | |
balances.wallet.cash.currency | union | Yes | |
balances.wallet.cash.pendingApprovalCents | number | Yes | Pending rewards after reversals. |
balances.wallet.cash.approvedCents | number | Yes | Every approved reward after reversals, including amounts already reserved, paid or redeemed. |
balances.wallet.cash.reservedCents | number | Yes | Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit. |
balances.wallet.cash.paidOrRedeemedCents | number | Yes | Cash paid by finished wallet payouts, or credit redeemed less restorations. |
balances.wallet.cash.availableToSpendCents | number | Yes | What a new wallet payout (cash) or redemption (credit) can use now: approved value minus reserved, paid, redeemed and reversed-after-payout amounts. Never below 0. |
balances.wallet.cash.debtCents | number | Yes | Reversals after money left the wallet that later earnings must cover first. |
balances.wallet.cash.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
balances.wallet.cash.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
balances.wallet.credit
| Field | Type | Required | Details |
|---|---|---|---|
balances.wallet.credit.rewardType | union | Yes | |
balances.wallet.credit.currency | union | Yes | |
balances.wallet.credit.pendingApprovalCents | number | Yes | Pending rewards after reversals. |
balances.wallet.credit.approvedCents | number | Yes | Every approved reward after reversals, including amounts already reserved, paid or redeemed. |
balances.wallet.credit.reservedCents | number | Yes | Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit. |
balances.wallet.credit.paidOrRedeemedCents | number | Yes | Cash paid by finished wallet payouts, or credit redeemed less restorations. |
balances.wallet.credit.availableToSpendCents | number | Yes | What a new wallet payout (cash) or redemption (credit) can use now: approved value minus reserved, paid, redeemed and reversed-after-payout amounts. Never below 0. |
balances.wallet.credit.debtCents | number | Yes | Reversals after money left the wallet that later earnings must cover first. |
balances.wallet.credit.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
balances.wallet.credit.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
balances.merchant
| Field | Type | Required | Details |
|---|---|---|---|
balances.merchant.cash | object | Yes | |
balances.merchant.credit | object | Yes |
balances.merchant.cash
| Field | Type | Required | Details |
|---|---|---|---|
balances.merchant.cash.version | number | Yes | Partner-wide accounting history count shared by cash, credit and program merchant balances. |
balances.merchant.cash.rewardType | union | Yes | |
balances.merchant.cash.currency | union | Yes | |
balances.merchant.cash.pendingApprovalCents | number | Yes | Pending rewards the partner is still owed. |
balances.merchant.cash.approvedUndeliveredCents | number | Yes | Approved and owed, not delivered yet and not in an open merchant payout. |
balances.merchant.cash.inOpenPayoutsCents | number | Yes | Approved and owed, allocated to a merchant payout that is queued, processing or needs action. |
balances.merchant.cash.deliveredGrossCents | number | Yes | Delivered gross amounts less returned transfers, before reward refunds or debt settlements. |
balances.merchant.cash.debtCents | number | Yes | Delivered amounts that later refunds reversed and the partner has not repaid. |
balances.merchant.cash.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
balances.merchant.cash.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
balances.merchant.credit
| Field | Type | Required | Details |
|---|---|---|---|
balances.merchant.credit.version | number | Yes | Partner-wide accounting history count shared by cash, credit and program merchant balances. |
balances.merchant.credit.rewardType | union | Yes | |
balances.merchant.credit.currency | union | Yes | |
balances.merchant.credit.pendingApprovalCents | number | Yes | Pending rewards the partner is still owed. |
balances.merchant.credit.approvedUndeliveredCents | number | Yes | Approved and owed, not delivered yet and not in an open merchant payout. |
balances.merchant.credit.inOpenPayoutsCents | number | Yes | Approved and owed, allocated to a merchant payout that is queued, processing or needs action. |
balances.merchant.credit.deliveredGrossCents | number | Yes | Delivered gross amounts less returned transfers, before reward refunds or debt settlements. |
balances.merchant.credit.debtCents | number | Yes | Delivered amounts that later refunds reversed and the partner has not repaid. |
balances.merchant.credit.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
balances.merchant.credit.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
awaitingPayoutAccountSince
Variant 1
Type: null.
Variant 2
Type: string.
Response schema
json
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"externalId": {
"type": "string"
},
"name": {
"type": "string"
},
"active": {
"type": "boolean"
},
"referralCode": {
"type": "string"
},
"clicks": {
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "All recorded activity, including repeat visits and unclaimed or voided receipts."
},
"last30Days": {
"type": "number",
"description": "Activity in the rolling 30 days ending at the summary's read time."
}
},
"required": [
"total",
"last30Days"
],
"description": "Link and QR activity across all programs, including former memberships."
},
"programs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"active": {
"type": "boolean"
},
"member": {
"type": "boolean",
"description": "Whether the partner currently belongs to this program. Former memberships keep their totals."
},
"tracking": {
"type": "object",
"properties": {
"links": {
"type": "boolean"
},
"qrCodes": {
"type": "boolean"
},
"attributionCodes": {
"type": "boolean"
},
"providerPromoCodes": {
"type": "boolean"
}
},
"required": [
"links",
"qrCodes",
"attributionCodes",
"providerPromoCodes"
]
},
"attributionCode": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
},
"alias": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "The partner's short code, such as KARL7Q, when attributionCode is set. Customers can type either."
},
"promoCodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"companyId": {
"type": "string"
},
"partnerId": {
"type": "string"
},
"programId": {
"type": "string"
},
"integrationId": {
"type": "string"
},
"provider": {
"anyOf": [
{
"type": "string",
"const": "stripe"
},
{
"type": "string",
"const": "shopify"
}
]
},
"code": {
"type": "string"
},
"providerCodeId": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "Null until Grizzlee has saved the provider discount ID."
},
"status": {
"anyOf": [
{
"type": "string",
"const": "pending"
},
{
"type": "string",
"const": "active"
},
{
"type": "string",
"const": "inactive"
}
]
},
"replacesId": {
"type": "string"
},
"couponId": {
"type": "string"
},
"incentive": {
"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."
},
"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"
]
}
]
},
"programVersion": {
"type": "number"
},
"active": {
"type": "boolean"
},
"createdAt": {
"type": "string"
},
"deactivatedAt": {
"type": "string"
}
},
"required": [
"id",
"companyId",
"partnerId",
"programId",
"integrationId",
"provider",
"code",
"providerCodeId",
"status",
"incentive",
"programVersion",
"active",
"createdAt"
]
}
},
"qrLink": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
]
},
"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"
}
]
},
"trigger": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "order"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "milestone"
},
"milestone": {
"type": "string"
}
},
"required": [
"type",
"milestone"
]
}
],
"description": "What earns a reward in this program."
},
"deliveryMode": {
"anyOf": [
{
"type": "string",
"const": "grizzlee_wallet"
},
{
"type": "string",
"const": "merchant"
}
],
"description": "Who delivers this program's rewards: the Grizzlee wallet or the merchant."
},
"compensation": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "percentage"
},
"rateBps": {
"type": "number"
},
"phases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"rateBps": {
"type": "number"
},
"afterMonths": {
"type": "number"
}
},
"required": [
"rateBps",
"afterMonths"
]
}
}
},
"required": [
"type",
"rateBps"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "fixed"
},
"amountCents": {
"type": "number"
}
},
"required": [
"type",
"amountCents"
]
}
],
"description": "Order compensation, with this partner's custom terms when present. Absent for milestones."
},
"milestoneRewards": {
"type": "object",
"properties": {
"eachReport": {
"type": "object",
"properties": {
"compensation": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "fixed"
},
"amountCents": {
"type": "number"
}
},
"required": [
"type",
"amountCents"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "percentage"
},
"rateBps": {
"type": "number"
}
},
"required": [
"type",
"rateBps"
]
}
]
},
"limit": {
"type": "number",
"description": "Absent means every counted report. Reversed reports do not count toward the limit."
}
},
"required": [
"compensation"
]
},
"atCount": {
"type": "object",
"properties": {
"amountCents": {
"type": "number"
},
"count": {
"type": "number"
}
},
"required": [
"amountCents",
"count"
]
}
}
},
"fixedRefundMode": {
"anyOf": [
{
"type": "string",
"const": "prorate"
},
{
"type": "string",
"const": "full_refund_only"
}
],
"description": "How this program refunds fixed rewards. Percentage rewards keep their commission base."
},
"incentive": {
"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."
},
"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": "What a referred customer gets in this program. Null without an offer or a current membership."
},
"terms": {
"type": "object",
"properties": {
"trigger": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "order"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "milestone"
},
"milestone": {
"type": "string"
}
},
"required": [
"type",
"milestone"
]
}
]
},
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "offer"
},
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"compensation": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "percentage"
},
"rateBps": {
"type": "number",
"description": "Base rate, before any performance tier bonus."
},
"phases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"afterMonths": {
"type": "number"
},
"rateBps": {
"type": "number"
}
},
"required": [
"afterMonths",
"rateBps"
]
},
"description": "Later rates by months after the customer's first rewarded order. Empty when the rate never changes."
}
},
"required": [
"type",
"rateBps",
"phases"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "fixed"
},
"amountCents": {
"type": "number"
}
},
"required": [
"type",
"amountCents"
]
}
],
"description": "What the partner earns. This partner's custom terms replace the program's when it has them."
},
"partnerOffer": {
"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"
]
}
],
"description": "The partner's earned discount with currency. Null for money rewards."
},
"milestoneRewards": {
"type": "object",
"properties": {
"eachReport": {
"type": "object",
"properties": {
"compensation": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "fixed"
},
"amountCents": {
"type": "number"
}
},
"required": [
"type",
"amountCents"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "percentage"
},
"rateBps": {
"type": "number"
}
},
"required": [
"type",
"rateBps"
]
}
]
},
"limit": {
"type": "number",
"description": "Absent means every counted report. Reversed reports do not count toward the limit."
}
},
"required": [
"compensation"
]
},
"atCount": {
"type": "object",
"properties": {
"amountCents": {
"type": "number"
},
"count": {
"type": "number"
}
},
"required": [
"amountCents",
"count"
]
}
}
},
"duration": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "only_order"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "first_order"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "first_n_orders"
},
"count": {
"type": "number"
}
},
"required": [
"type",
"count"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "days"
},
"days": {
"type": "number"
}
},
"required": [
"type",
"days"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "months"
},
"months": {
"type": "number"
}
},
"required": [
"type",
"months"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "lifetime"
}
},
"required": [
"type"
]
}
],
"description": "Which orders of a referred customer earn a reward. Null for milestone programs."
},
"fixedRefundMode": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"const": "prorate"
},
{
"type": "string",
"const": "full_refund_only"
}
],
"description": "How a partial refund changes a fixed order reward. Null for percentage and milestone rewards."
},
"referralWindowDays": {
"anyOf": [
{
"type": "null"
},
{
"type": "number"
}
],
"description": "Days a referral stays open until an order or milestone qualifies it. Null when it never expires."
},
"text": {
"type": "object",
"properties": {
"reward": {
"type": "object",
"properties": {
"en": {
"type": "string"
},
"fr-CA": {
"type": "string"
},
"hy": {
"type": "string"
},
"ru": {
"type": "string"
}
},
"required": [
"en",
"fr-CA",
"hy",
"ru"
],
"description": "What the partner earns, such as \"$10 credit when your friend completes their first order after your referral\"."
},
"incentive": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"en": {
"type": "string"
},
"fr-CA": {
"type": "string"
},
"hy": {
"type": "string"
},
"ru": {
"type": "string"
}
},
"required": [
"en",
"fr-CA",
"hy",
"ru"
]
}
],
"description": "What the referred friend gets, such as \"20% off your first order\". Null without a friend incentive."
},
"headline": {
"type": "object",
"properties": {
"en": {
"type": "string"
},
"fr-CA": {
"type": "string"
},
"hy": {
"type": "string"
},
"ru": {
"type": "string"
}
},
"required": [
"en",
"fr-CA",
"hy",
"ru"
],
"description": "Both sides in a few words, such as \"Give 20%, get $10\", or \"Get $10\" without a friend incentive."
}
},
"required": [
"reward",
"incentive",
"headline"
]
}
},
"required": [
"trigger",
"rewardType",
"currency",
"compensation",
"partnerOffer",
"duration",
"fixedRefundMode",
"referralWindowDays",
"text"
],
"description": "Readable reward terms. Former memberships omit the friend incentive from the text."
},
"display": {
"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": "Public name, headline and milestone label. The headline falls back to terms.text.headline."
},
"link": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "Referral link to the program's published destination. Null when unavailable or membership ended."
},
"linkUnavailableReason": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"const": "program_inactive"
},
{
"type": "string",
"const": "partner_inactive"
},
{
"type": "string",
"const": "tracking_disabled"
},
{
"type": "string",
"const": "no_published_page"
},
{
"type": "string",
"const": "invalid_destination"
}
],
"description": "Set when link is null, otherwise null."
},
"clicks": {
"type": "object",
"properties": {
"total": {
"type": "number",
"description": "All recorded activity, including repeat visits and unclaimed or voided receipts."
},
"last30Days": {
"type": "number",
"description": "Activity in the rolling 30 days ending at the summary's read time."
}
},
"required": [
"total",
"last30Days"
],
"description": "Link and QR activity in this program. Coupon and in-app channels are excluded."
},
"earnedCents": {
"type": "number",
"description": "Reward value after reversals, across saved reward types and delivery modes."
},
"reversedCents": {
"type": "number",
"description": "Reward value currently reversed. Restorations reduce this total."
},
"referrals": {
"type": "object",
"properties": {
"referred": {
"type": "number"
},
"qualified": {
"type": "number"
}
},
"required": [
"referred",
"qualified"
],
"description": "Each attribution counts once, including displaced referrals and separate order-scoped referrals."
},
"orderCount": {
"type": "number",
"description": "Sum of referral orderCount values in this program. Reversed rewards still count; milestones do not."
},
"payouts": {
"type": "object",
"properties": {
"paidOutCents": {
"type": "number"
}
},
"required": [
"paidOutCents"
],
"description": "Paid merchant allocations less returned transfers. Wallet payouts have no program allocations."
},
"balances": {
"type": "object",
"properties": {
"wallet": {
"type": "object",
"properties": {
"cash": {
"type": "object",
"properties": {
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"pendingApprovalCents": {
"type": "number",
"description": "Pending rewards after reversals."
},
"approvedCents": {
"type": "number",
"description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed."
}
},
"required": [
"currency",
"rewardType",
"pendingApprovalCents",
"approvedCents"
]
},
"credit": {
"type": "object",
"properties": {
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"pendingApprovalCents": {
"type": "number",
"description": "Pending rewards after reversals."
},
"approvedCents": {
"type": "number",
"description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed."
}
},
"required": [
"currency",
"rewardType",
"pendingApprovalCents",
"approvedCents"
]
}
},
"required": [
"cash",
"credit"
],
"description": "Wallet spending, reservations and debt cannot be attributed to a program."
},
"merchant": {
"type": "object",
"properties": {
"cash": {
"type": "object",
"properties": {
"version": {
"type": "number",
"description": "Partner-wide accounting history count shared by cash, credit and program merchant balances."
},
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"pendingApprovalCents": {
"type": "number",
"description": "Pending rewards the partner is still owed."
},
"approvedUndeliveredCents": {
"type": "number",
"description": "Approved and owed, not delivered yet and not in an open merchant payout."
},
"inOpenPayoutsCents": {
"type": "number",
"description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action."
},
"deliveredGrossCents": {
"type": "number",
"description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements."
},
"debtCents": {
"type": "number",
"description": "Delivered amounts that later refunds reversed and the partner has not repaid."
}
},
"required": [
"version",
"rewardType",
"currency",
"pendingApprovalCents",
"approvedUndeliveredCents",
"inOpenPayoutsCents",
"deliveredGrossCents",
"debtCents"
]
},
"credit": {
"type": "object",
"properties": {
"version": {
"type": "number",
"description": "Partner-wide accounting history count shared by cash, credit and program merchant balances."
},
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"pendingApprovalCents": {
"type": "number",
"description": "Pending rewards the partner is still owed."
},
"approvedUndeliveredCents": {
"type": "number",
"description": "Approved and owed, not delivered yet and not in an open merchant payout."
},
"inOpenPayoutsCents": {
"type": "number",
"description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action."
},
"deliveredGrossCents": {
"type": "number",
"description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements."
},
"debtCents": {
"type": "number",
"description": "Delivered amounts that later refunds reversed and the partner has not repaid."
}
},
"required": [
"version",
"rewardType",
"currency",
"pendingApprovalCents",
"approvedUndeliveredCents",
"inOpenPayoutsCents",
"deliveredGrossCents",
"debtCents"
]
}
},
"required": [
"cash",
"credit"
]
}
},
"required": [
"wallet",
"merchant"
]
}
},
"required": [
"id",
"name",
"active",
"member",
"tracking",
"attributionCode",
"alias",
"promoCodes",
"qrLink",
"currency",
"rewardType",
"trigger",
"deliveryMode",
"fixedRefundMode",
"incentive",
"terms",
"display",
"link",
"linkUnavailableReason",
"clicks",
"earnedCents",
"reversedCents",
"referrals",
"orderCount",
"payouts",
"balances"
]
},
"description": "Current memberships in programIds order, then former programs with rewards, referrals, payout allocations or debt, sorted by ID."
},
"balances": {
"type": "object",
"properties": {
"wallet": {
"type": "object",
"properties": {
"cash": {
"type": "object",
"properties": {
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"pendingApprovalCents": {
"type": "number",
"description": "Pending rewards after reversals."
},
"approvedCents": {
"type": "number",
"description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed."
},
"reservedCents": {
"type": "number",
"description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit."
},
"paidOrRedeemedCents": {
"type": "number",
"description": "Cash paid by finished wallet payouts, or credit redeemed less restorations."
},
"availableToSpendCents": {
"type": "number",
"description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0."
},
"debtCents": {
"type": "number",
"description": "Reversals after money left the wallet that later earnings must cover first."
}
},
"required": [
"rewardType",
"currency",
"pendingApprovalCents",
"approvedCents",
"reservedCents",
"paidOrRedeemedCents",
"availableToSpendCents",
"debtCents"
]
},
"credit": {
"type": "object",
"properties": {
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"pendingApprovalCents": {
"type": "number",
"description": "Pending rewards after reversals."
},
"approvedCents": {
"type": "number",
"description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed."
},
"reservedCents": {
"type": "number",
"description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit."
},
"paidOrRedeemedCents": {
"type": "number",
"description": "Cash paid by finished wallet payouts, or credit redeemed less restorations."
},
"availableToSpendCents": {
"type": "number",
"description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0."
},
"debtCents": {
"type": "number",
"description": "Reversals after money left the wallet that later earnings must cover first."
}
},
"required": [
"rewardType",
"currency",
"pendingApprovalCents",
"approvedCents",
"reservedCents",
"paidOrRedeemedCents",
"availableToSpendCents",
"debtCents"
]
}
},
"required": [
"cash",
"credit"
]
},
"merchant": {
"type": "object",
"properties": {
"cash": {
"type": "object",
"properties": {
"version": {
"type": "number",
"description": "Partner-wide accounting history count shared by cash, credit and program merchant balances."
},
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"pendingApprovalCents": {
"type": "number",
"description": "Pending rewards the partner is still owed."
},
"approvedUndeliveredCents": {
"type": "number",
"description": "Approved and owed, not delivered yet and not in an open merchant payout."
},
"inOpenPayoutsCents": {
"type": "number",
"description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action."
},
"deliveredGrossCents": {
"type": "number",
"description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements."
},
"debtCents": {
"type": "number",
"description": "Delivered amounts that later refunds reversed and the partner has not repaid."
}
},
"required": [
"version",
"rewardType",
"currency",
"pendingApprovalCents",
"approvedUndeliveredCents",
"inOpenPayoutsCents",
"deliveredGrossCents",
"debtCents"
]
},
"credit": {
"type": "object",
"properties": {
"version": {
"type": "number",
"description": "Partner-wide accounting history count shared by cash, credit and program merchant balances."
},
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
]
},
"pendingApprovalCents": {
"type": "number",
"description": "Pending rewards the partner is still owed."
},
"approvedUndeliveredCents": {
"type": "number",
"description": "Approved and owed, not delivered yet and not in an open merchant payout."
},
"inOpenPayoutsCents": {
"type": "number",
"description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action."
},
"deliveredGrossCents": {
"type": "number",
"description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements."
},
"debtCents": {
"type": "number",
"description": "Delivered amounts that later refunds reversed and the partner has not repaid."
}
},
"required": [
"version",
"rewardType",
"currency",
"pendingApprovalCents",
"approvedUndeliveredCents",
"inOpenPayoutsCents",
"deliveredGrossCents",
"debtCents"
]
}
},
"required": [
"cash",
"credit"
]
}
},
"required": [
"wallet",
"merchant"
]
},
"payoutAccountRequired": {
"type": "boolean",
"description": "True when the payout schedule waits for a Stripe account (missingStripeAccount \"wait\"), the\npartner has no stripeAccountId, and the partner earns merchant-delivered cash: it belongs to\nsuch a program or has such cash pending or approved. Scheduled runs pay this partner nothing\nuntil it gets a stripeAccountId."
},
"awaitingPayoutAccount": {
"type": "boolean",
"description": "True when payoutAccountRequired and a scheduled run already held a payout for it."
},
"awaitingPayoutAccountSince": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
}
],
"description": "Due date (YYYY-MM-DD) of the first run that held a payout. Null unless awaitingPayoutAccount."
}
},
"required": [
"id",
"externalId",
"name",
"active",
"referralCode",
"clicks",
"programs",
"balances",
"payoutAccountRequired",
"awaitingPayoutAccount",
"awaitingPayoutAccountSince"
]
}Errors
Failures return { "error": { "code": "...", "message": "...", "details": {} } }. Details are optional. See error statuses. Reuse an unchanged event payload when retrying.