HTTP endpoints
getProgramVersion
One saved version of a program, such as the one in reward.programVersion.
GET /api/v1/programs/{programId}/versions/
Requires read. Keep the Bearer key on your server.
SDK
ts
grizzlee.getProgramVersion(programId: string, version: number): Promise<ProgramVersionDetail>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/programs/{programId}/versions/' \
-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 |
|---|---|---|---|
terms | object | Yes | Readable reward terms of this version, with the program's own compensation. |
companyId | string | Yes | |
programId | string | Yes | |
version | number | Yes | |
programSnapshot | object | Yes | |
changedFields | array | Yes | Top-level program fields that differ from the previous version, such as compensation or friendIncentive. Empty for version 1. |
createdAt | string | Yes | When this version took effect. Versions recorded when versioning started use the program's last saved change. |
terms
| Field | Type | Required | Details |
|---|---|---|---|
terms.trigger | union | Yes | |
terms.rewardType | union | Yes | |
terms.currency | union | Yes | |
terms.compensation | union | Yes | What the partner earns. This partner's custom terms replace the program's when it has them. |
terms.partnerOffer | union | Yes | The partner's earned discount with currency. Null for money rewards. |
terms.milestoneRewards | object | No | |
terms.duration | union | Yes | Which orders of a referred customer earn a reward. Null for milestone programs. |
terms.fixedRefundMode | union | Yes | How a partial refund changes a fixed order reward. Null for percentage and milestone rewards. |
terms.referralWindowDays | union | Yes | Days a referral stays open until an order or milestone qualifies it. Null when it never expires. |
terms.text | object | Yes |
terms.trigger
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
terms.trigger.type | "order" | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
terms.trigger.type | "milestone" | Yes | |
terms.trigger.milestone | string | Yes |
terms.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
terms.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
terms.compensation
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
terms.compensation.type | "percentage" | Yes | |
terms.compensation.rateBps | number | Yes | Base rate, before any performance tier bonus. |
terms.compensation.phases | array | Yes | Later rates by months after the customer's first rewarded order. Empty when the rate never changes. |
terms.compensation.phases[]
| Field | Type | Required | Details |
|---|---|---|---|
terms.compensation.phases.afterMonths | number | Yes | |
terms.compensation.phases.rateBps | number | Yes |
Variant 3
| Field | Type | Required | Details |
|---|---|---|---|
terms.compensation.type | "fixed" | Yes | |
terms.compensation.amountCents | number | Yes |
terms.partnerOffer
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
terms.partnerOffer.type | "percent" | Yes | |
terms.partnerOffer.rateBps | number | Yes | |
terms.partnerOffer.orders | number | Yes | How many of the friend's orders get the incentive. |
terms.partnerOffer.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
terms.partnerOffer.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
terms.partnerOffer.maxDiscountCents | number | No | Largest discount for one order. |
terms.partnerOffer.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
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. |
terms.partnerOffer.currency | union | Yes |
terms.partnerOffer.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
terms.partnerOffer.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
terms.partnerOffer.orderCategories.include | array | No | |
terms.partnerOffer.orderCategories.exclude | array | No |
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 |
|---|---|---|---|
terms.partnerOffer.type | "fixed" | Yes | |
terms.partnerOffer.orders | number | Yes | How many of the friend's orders get the incentive. |
terms.partnerOffer.expiresAfterDays | union | Yes | Days after the referral was captured, claimed or entered. null means it never expires. |
terms.partnerOffer.returnOnFullRefund | boolean | Yes | true: a full refund gives the use back, so the customer can get the offer again. |
terms.partnerOffer.amountCents | number | Yes | |
terms.partnerOffer.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
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. |
terms.partnerOffer.currency | union | Yes |
terms.partnerOffer.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
terms.partnerOffer.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
terms.partnerOffer.orderCategories.include | array | No | |
terms.partnerOffer.orderCategories.exclude | array | No |
terms.partnerOffer.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
terms.milestoneRewards
| Field | Type | Required | Details |
|---|---|---|---|
terms.milestoneRewards.eachReport | object | No | |
terms.milestoneRewards.atCount | object | No |
terms.milestoneRewards.eachReport
| Field | Type | Required | Details |
|---|---|---|---|
terms.milestoneRewards.eachReport.compensation | union | Yes | |
terms.milestoneRewards.eachReport.limit | number | No | Absent means every counted report. Reversed reports do not count toward the limit. |
terms.milestoneRewards.eachReport.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
terms.milestoneRewards.eachReport.compensation.type | "fixed" | Yes | |
terms.milestoneRewards.eachReport.compensation.amountCents | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
terms.milestoneRewards.eachReport.compensation.type | "percentage" | Yes | |
terms.milestoneRewards.eachReport.compensation.rateBps | number | Yes |
terms.milestoneRewards.atCount
| Field | Type | Required | Details |
|---|---|---|---|
terms.milestoneRewards.atCount.amountCents | number | Yes | |
terms.milestoneRewards.atCount.count | number | Yes |
terms.duration
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
terms.duration.type | "only_order" | Yes |
Variant 3
| Field | Type | Required | Details |
|---|---|---|---|
terms.duration.type | "first_order" | Yes |
Variant 4
| Field | Type | Required | Details |
|---|---|---|---|
terms.duration.type | "first_n_orders" | Yes | |
terms.duration.count | number | Yes |
Variant 5
| Field | Type | Required | Details |
|---|---|---|---|
terms.duration.type | "days" | Yes | |
terms.duration.days | number | Yes |
Variant 6
| Field | Type | Required | Details |
|---|---|---|---|
terms.duration.type | "months" | Yes | |
terms.duration.months | number | Yes |
Variant 7
| Field | Type | Required | Details |
|---|---|---|---|
terms.duration.type | "lifetime" | Yes |
terms.fixedRefundMode
Variant 1
Type: null.
Variant 2
Type: string.
Variant 3
Type: string.
terms.referralWindowDays
Variant 1
Type: null.
Variant 2
Type: number.
terms.text
| Field | Type | Required | Details |
|---|---|---|---|
terms.text.reward | object | Yes | What the partner earns, such as "$10 credit when your friend completes their first order after your referral". |
terms.text.incentive | union | Yes | What the referred friend gets, such as "20% off your first order". Null without a friend incentive. |
terms.text.headline | object | Yes | Both sides in a few words, such as "Give 20%, get $10", or "Get $10" without a friend incentive. |
terms.text.reward
| Field | Type | Required | Details |
|---|---|---|---|
terms.text.reward.en | string | Yes | |
terms.text.reward.fr-CA | string | Yes | |
terms.text.reward.hy | string | Yes | |
terms.text.reward.ru | string | Yes |
terms.text.incentive
Variant 1
Type: null.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
terms.text.incentive.en | string | Yes | |
terms.text.incentive.fr-CA | string | Yes | |
terms.text.incentive.hy | string | Yes | |
terms.text.incentive.ru | string | Yes |
terms.text.headline
| Field | Type | Required | Details |
|---|---|---|---|
terms.text.headline.en | string | Yes | |
terms.text.headline.fr-CA | string | Yes | |
terms.text.headline.hy | string | Yes | |
terms.text.headline.ru | string | Yes |
programSnapshot
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.currency | union | Yes | Must match the company currency. |
programSnapshot.name | string | Yes | |
programSnapshot.kind | union | Yes | |
programSnapshot.rewardType | union | Yes | |
programSnapshot.attributionWindowDays | union | Yes | Days after a referral that a first purchase, or a milestone, still counts. The latest referral always wins until one qualifies. Only milestone programs may use null, which means the referral never expires. |
programSnapshot.active | boolean | Yes | |
programSnapshot.orderCategories | object | No | Order categories that earn rewards. Order programs only. The friend incentive has its own orderCategories. Absent means every order can earn. |
programSnapshot.compensation | union | No | |
programSnapshot.tracking | object | No | Tracking methods are independent of kind. Provider discounts require a connected provider. |
programSnapshot.destinationUrl | string | No | The page partner links and QR codes open. A published signup page's destination takes precedence. Without either, partners have no link. |
programSnapshot.display | object | No | Optional public name, headline and milestone label for partner and customer screens. |
programSnapshot.trigger | union | No | What earns a reward. Defaults to completed orders. |
programSnapshot.milestoneRewards | object | No | |
programSnapshot.fixedRefundMode | union | No | How fixed rewards change after a partial refund. |
programSnapshot.duration | union | No | |
programSnapshot.delivery | object | No | Who delivers approved rewards of each type. Defaults to the Grizzlee wallet for both. |
programSnapshot.reviewRewards | union | No | When true, new rewards wait as pending until someone approves them. Otherwise they start approved. |
programSnapshot.fraudChecks | object | No | Self-referral and other fraud rules. Absent means every rule uses its default. |
programSnapshot.performance | object | No | |
programSnapshot.limits | object | No | |
programSnapshot.customTerms | array | No | |
programSnapshot.friendIncentive | union | No | Optional offer for the referred customer. |
programSnapshot.partnerOffer | union | No | Offer programs only. What the partner earns per qualifying referred order. |
programSnapshot.currency
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programSnapshot.kind
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
programSnapshot.rewardType
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
programSnapshot.attributionWindowDays
Variant 1
Type: null.
Variant 2
Type: number.
programSnapshot.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.orderCategories.include | array | No | |
programSnapshot.orderCategories.exclude | array | No |
programSnapshot.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.compensation.type | "percentage" | Yes | |
programSnapshot.compensation.rateBps | number | Yes | |
programSnapshot.compensation.phases | array | No |
programSnapshot.compensation.phases[]
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.compensation.phases.rateBps | number | Yes | |
programSnapshot.compensation.phases.afterMonths | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.compensation.type | "fixed" | Yes | |
programSnapshot.compensation.amountCents | number | Yes |
programSnapshot.tracking
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.tracking.links | union | No | |
programSnapshot.tracking.qrCodes | union | No | |
programSnapshot.tracking.attributionCodes | union | No | |
programSnapshot.tracking.providerPromoCodes | union | No |
programSnapshot.tracking.links
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.tracking.qrCodes
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.tracking.attributionCodes
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.tracking.providerPromoCodes
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.display
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.display.en | object | No | |
programSnapshot.display.fr-CA | object | No | |
programSnapshot.display.hy | object | No | |
programSnapshot.display.ru | object | No |
programSnapshot.display.en
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.display.en.publicName | string | No | The name partners and customers see. Falls back to the program name. |
programSnapshot.display.en.headline | string | No | Replaces the generated headline, such as "Give 20%, get $10". |
programSnapshot.display.en.milestoneLabel | object | No | Milestone programs only. What one report counts, such as one: "lesson", other: "lessons". In Russian, other is the genitive plural, such as "уроков", which reward terms put after "число". |
programSnapshot.display.en.milestoneLabel
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.display.en.milestoneLabel.one | string | Yes | |
programSnapshot.display.en.milestoneLabel.other | string | Yes |
programSnapshot.display.fr-CA
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.display.fr-CA.publicName | string | No | The name partners and customers see. Falls back to the program name. |
programSnapshot.display.fr-CA.headline | string | No | Replaces the generated headline, such as "Give 20%, get $10". |
programSnapshot.display.fr-CA.milestoneLabel | object | No | Milestone programs only. What one report counts, such as one: "lesson", other: "lessons". In Russian, other is the genitive plural, such as "уроков", which reward terms put after "число". |
programSnapshot.display.fr-CA.milestoneLabel
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.display.fr-CA.milestoneLabel.one | string | Yes | |
programSnapshot.display.fr-CA.milestoneLabel.other | string | Yes |
programSnapshot.display.hy
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.display.hy.publicName | string | No | The name partners and customers see. Falls back to the program name. |
programSnapshot.display.hy.headline | string | No | Replaces the generated headline, such as "Give 20%, get $10". |
programSnapshot.display.hy.milestoneLabel | object | No | Milestone programs only. What one report counts, such as one: "lesson", other: "lessons". In Russian, other is the genitive plural, such as "уроков", which reward terms put after "число". |
programSnapshot.display.hy.milestoneLabel
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.display.hy.milestoneLabel.one | string | Yes | |
programSnapshot.display.hy.milestoneLabel.other | string | Yes |
programSnapshot.display.ru
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.display.ru.publicName | string | No | The name partners and customers see. Falls back to the program name. |
programSnapshot.display.ru.headline | string | No | Replaces the generated headline, such as "Give 20%, get $10". |
programSnapshot.display.ru.milestoneLabel | object | No | Milestone programs only. What one report counts, such as one: "lesson", other: "lessons". In Russian, other is the genitive plural, such as "уроков", which reward terms put after "число". |
programSnapshot.display.ru.milestoneLabel
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.display.ru.milestoneLabel.one | string | Yes | |
programSnapshot.display.ru.milestoneLabel.other | string | Yes |
programSnapshot.trigger
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.trigger.type | "order" | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.trigger.type | "milestone" | Yes | |
programSnapshot.trigger.milestone | string | Yes |
programSnapshot.milestoneRewards
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.milestoneRewards.eachReport | object | No | |
programSnapshot.milestoneRewards.atCount | object | No |
programSnapshot.milestoneRewards.eachReport
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.milestoneRewards.eachReport.compensation | union | Yes | |
programSnapshot.milestoneRewards.eachReport.limit | number | No | Absent means every counted report. Reversed reports do not count toward the limit. |
programSnapshot.milestoneRewards.eachReport.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.milestoneRewards.eachReport.compensation.type | "fixed" | Yes | |
programSnapshot.milestoneRewards.eachReport.compensation.amountCents | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.milestoneRewards.eachReport.compensation.type | "percentage" | Yes | |
programSnapshot.milestoneRewards.eachReport.compensation.rateBps | number | Yes |
programSnapshot.milestoneRewards.atCount
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.milestoneRewards.atCount.amountCents | number | Yes | |
programSnapshot.milestoneRewards.atCount.count | number | Yes |
programSnapshot.fixedRefundMode
Variant 1
Type: string.
Variant 2
Type: string.
programSnapshot.duration
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.duration.type | "only_order" | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.duration.type | "first_order" | Yes |
Variant 3
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.duration.type | "first_n_orders" | Yes | |
programSnapshot.duration.count | number | Yes |
Variant 4
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.duration.type | "days" | Yes | |
programSnapshot.duration.days | number | Yes |
Variant 5
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.duration.type | "months" | Yes | |
programSnapshot.duration.months | number | Yes |
Variant 6
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.duration.type | "lifetime" | Yes |
programSnapshot.delivery
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.delivery.cash | union | No | |
programSnapshot.delivery.credit | union | No |
programSnapshot.delivery.cash
Variant 1
Type: string.
Variant 2
Type: string.
programSnapshot.delivery.credit
Variant 1
Type: string.
Variant 2
Type: string.
programSnapshot.reviewRewards
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.fraudChecks
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.fraudChecks.selfReferral | object | No | |
programSnapshot.fraudChecks.duplicateAccounts | object | No | |
programSnapshot.fraudChecks.rapidRepeats | object | No | |
programSnapshot.fraudChecks.repeatCustomer | object | No | |
programSnapshot.fraudChecks.disposableEmail | object | No |
programSnapshot.fraudChecks.selfReferral
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.fraudChecks.selfReferral.action | union | No |
programSnapshot.fraudChecks.selfReferral.action
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programSnapshot.fraudChecks.duplicateAccounts
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.fraudChecks.duplicateAccounts.action | union | No | |
programSnapshot.fraudChecks.duplicateAccounts.accounts | number | No | Customers sharing one card or device that trigger the rule. This one counts when referred inside the window. |
programSnapshot.fraudChecks.duplicateAccounts.windowDays | number | No | |
programSnapshot.fraudChecks.duplicateAccounts.ipAccounts | union | No | Customers sharing one IP address that trigger the rule. null leaves IP addresses out. |
programSnapshot.fraudChecks.duplicateAccounts.action
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programSnapshot.fraudChecks.duplicateAccounts.ipAccounts
Variant 1
Type: null.
Variant 2
Type: number.
programSnapshot.fraudChecks.rapidRepeats
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.fraudChecks.rapidRepeats.action | union | No | |
programSnapshot.fraudChecks.rapidRepeats.referrals | number | No | Referrals from one device that trigger the rule. This one counts when referred inside the window. |
programSnapshot.fraudChecks.rapidRepeats.windowMinutes | number | No | |
programSnapshot.fraudChecks.rapidRepeats.ipReferrals | union | No | Referrals from one IP address that trigger the rule. null leaves IP addresses out. |
programSnapshot.fraudChecks.rapidRepeats.action
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programSnapshot.fraudChecks.rapidRepeats.ipReferrals
Variant 1
Type: null.
Variant 2
Type: number.
programSnapshot.fraudChecks.repeatCustomer
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.fraudChecks.repeatCustomer.action | union | No |
programSnapshot.fraudChecks.repeatCustomer.action
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
Variant 4
Type: string.
programSnapshot.fraudChecks.disposableEmail
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.fraudChecks.disposableEmail.action | union | No | A disposable address does not show a second person, so this rule cannot block. |
programSnapshot.fraudChecks.disposableEmail.action
Variant 1
Type: string.
Variant 2
Type: string.
Variant 3
Type: string.
programSnapshot.performance
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.performance.metric | union | Yes | |
programSnapshot.performance.tiers | array | Yes | |
programSnapshot.performance.windowDays | number | No |
programSnapshot.performance.metric
Variant 1
Type: string.
Variant 2
Type: string.
programSnapshot.performance.tiers[]
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.performance.tiers.name | string | Yes | |
programSnapshot.performance.tiers.minValue | number | Yes | |
programSnapshot.performance.tiers.bonusBps | number | Yes |
programSnapshot.limits
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.limits.customerCapCents | number | No | |
programSnapshot.limits.partnerCapCents | number | No |
programSnapshot.customTerms[]
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.target | "partner" | Yes | |
programSnapshot.customTerms.targetId | string | Yes | |
programSnapshot.customTerms.compensation | union | No | |
programSnapshot.customTerms.milestoneRewards | object | No | |
programSnapshot.customTerms.customerCapCents | union | No | |
programSnapshot.customTerms.partnerCapCents | union | No |
programSnapshot.customTerms.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.compensation.type | "percentage" | Yes | |
programSnapshot.customTerms.compensation.rateBps | number | Yes | |
programSnapshot.customTerms.compensation.phases | array | No |
programSnapshot.customTerms.compensation.phases[]
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.compensation.phases.rateBps | number | Yes | |
programSnapshot.customTerms.compensation.phases.afterMonths | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.compensation.type | "fixed" | Yes | |
programSnapshot.customTerms.compensation.amountCents | number | Yes |
programSnapshot.customTerms.milestoneRewards
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.eachReport | object | No | |
programSnapshot.customTerms.milestoneRewards.atCount | object | No |
programSnapshot.customTerms.milestoneRewards.eachReport
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.eachReport.compensation | union | Yes | |
programSnapshot.customTerms.milestoneRewards.eachReport.limit | number | No | Absent means every counted report. Reversed reports do not count toward the limit. |
programSnapshot.customTerms.milestoneRewards.eachReport.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.eachReport.compensation.type | "fixed" | Yes | |
programSnapshot.customTerms.milestoneRewards.eachReport.compensation.amountCents | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.eachReport.compensation.type | "percentage" | Yes | |
programSnapshot.customTerms.milestoneRewards.eachReport.compensation.rateBps | number | Yes |
programSnapshot.customTerms.milestoneRewards.atCount
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.atCount.amountCents | number | Yes | |
programSnapshot.customTerms.milestoneRewards.atCount.count | number | Yes |
programSnapshot.customTerms.customerCapCents
Variant 1
Type: null.
Variant 2
Type: number.
programSnapshot.customTerms.partnerCapCents
Variant 1
Type: null.
Variant 2
Type: number.
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.target | "customer" | Yes | |
programSnapshot.customTerms.targetId | string | Yes | |
programSnapshot.customTerms.compensation | union | No | |
programSnapshot.customTerms.milestoneRewards | object | No | |
programSnapshot.customTerms.customerCapCents | union | No |
programSnapshot.customTerms.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.compensation.type | "percentage" | Yes | |
programSnapshot.customTerms.compensation.rateBps | number | Yes | |
programSnapshot.customTerms.compensation.phases | array | No |
programSnapshot.customTerms.compensation.phases[]
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.compensation.phases.rateBps | number | Yes | |
programSnapshot.customTerms.compensation.phases.afterMonths | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.compensation.type | "fixed" | Yes | |
programSnapshot.customTerms.compensation.amountCents | number | Yes |
programSnapshot.customTerms.milestoneRewards
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.eachReport | object | No | |
programSnapshot.customTerms.milestoneRewards.atCount | object | No |
programSnapshot.customTerms.milestoneRewards.eachReport
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.eachReport.compensation | union | Yes | |
programSnapshot.customTerms.milestoneRewards.eachReport.limit | number | No | Absent means every counted report. Reversed reports do not count toward the limit. |
programSnapshot.customTerms.milestoneRewards.eachReport.compensation
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.eachReport.compensation.type | "fixed" | Yes | |
programSnapshot.customTerms.milestoneRewards.eachReport.compensation.amountCents | number | Yes |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.eachReport.compensation.type | "percentage" | Yes | |
programSnapshot.customTerms.milestoneRewards.eachReport.compensation.rateBps | number | Yes |
programSnapshot.customTerms.milestoneRewards.atCount
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.customTerms.milestoneRewards.atCount.amountCents | number | Yes | |
programSnapshot.customTerms.milestoneRewards.atCount.count | number | Yes |
programSnapshot.customTerms.customerCapCents
Variant 1
Type: null.
Variant 2
Type: number.
programSnapshot.friendIncentive
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.friendIncentive.type | "percent" | Yes | |
programSnapshot.friendIncentive.rateBps | number | Yes | |
programSnapshot.friendIncentive.maxDiscountCents | number | No | Largest discount for one order. |
programSnapshot.friendIncentive.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programSnapshot.friendIncentive.orders | number | No | How many of the friend's orders get the incentive. |
programSnapshot.friendIncentive.newCustomersOnly | union | No | 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. |
programSnapshot.friendIncentive.expiresAfterDays | union | No | Days after the referral was captured, claimed or entered. null means it never expires. |
programSnapshot.friendIncentive.returnOnFullRefund | union | No | true: a full refund gives the use back, so the customer can get the offer again. |
programSnapshot.friendIncentive.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. |
programSnapshot.friendIncentive.newCustomersOnly
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.friendIncentive.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programSnapshot.friendIncentive.returnOnFullRefund
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.friendIncentive.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.friendIncentive.orderCategories.include | array | No | |
programSnapshot.friendIncentive.orderCategories.exclude | array | No |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.friendIncentive.type | "fixed" | Yes | |
programSnapshot.friendIncentive.amountCents | number | Yes | |
programSnapshot.friendIncentive.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programSnapshot.friendIncentive.orders | number | No | How many of the friend's orders get the incentive. |
programSnapshot.friendIncentive.newCustomersOnly | union | No | 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. |
programSnapshot.friendIncentive.expiresAfterDays | union | No | Days after the referral was captured, claimed or entered. null means it never expires. |
programSnapshot.friendIncentive.returnOnFullRefund | union | No | true: a full refund gives the use back, so the customer can get the offer again. |
programSnapshot.friendIncentive.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. |
programSnapshot.friendIncentive.newCustomersOnly
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.friendIncentive.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programSnapshot.friendIncentive.returnOnFullRefund
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.friendIncentive.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.friendIncentive.orderCategories.include | array | No | |
programSnapshot.friendIncentive.orderCategories.exclude | array | No |
programSnapshot.partnerOffer
Variant 1
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.partnerOffer.type | "percent" | Yes | |
programSnapshot.partnerOffer.rateBps | number | Yes | |
programSnapshot.partnerOffer.maxDiscountCents | number | No | Largest discount for one order. |
programSnapshot.partnerOffer.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programSnapshot.partnerOffer.orders | number | No | How many of the friend's orders get the incentive. |
programSnapshot.partnerOffer.expiresAfterDays | union | No | Days after the referral was captured, claimed or entered. null means it never expires. |
programSnapshot.partnerOffer.returnOnFullRefund | union | No | true: a full refund gives the use back, so the customer can get the offer again. |
programSnapshot.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. |
programSnapshot.partnerOffer.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programSnapshot.partnerOffer.returnOnFullRefund
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.partnerOffer.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.partnerOffer.orderCategories.include | array | No | |
programSnapshot.partnerOffer.orderCategories.exclude | array | No |
Variant 2
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.partnerOffer.type | "fixed" | Yes | |
programSnapshot.partnerOffer.amountCents | number | Yes | |
programSnapshot.partnerOffer.minOrderCents | number | No | The friend's order total before the discount must reach this amount. Checked by the merchant's checkout. |
programSnapshot.partnerOffer.orders | number | No | How many of the friend's orders get the incentive. |
programSnapshot.partnerOffer.expiresAfterDays | union | No | Days after the referral was captured, claimed or entered. null means it never expires. |
programSnapshot.partnerOffer.returnOnFullRefund | union | No | true: a full refund gives the use back, so the customer can get the offer again. |
programSnapshot.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. |
programSnapshot.partnerOffer.expiresAfterDays
Variant 1
Type: null.
Variant 2
Type: number.
programSnapshot.partnerOffer.returnOnFullRefund
Variant 1
Type: boolean.
Variant 2
Type: boolean.
programSnapshot.partnerOffer.orderCategories
| Field | Type | Required | Details |
|---|---|---|---|
programSnapshot.partnerOffer.orderCategories.include | array | No | |
programSnapshot.partnerOffer.orderCategories.exclude | array | No |
Response schema
json
{
"type": "object",
"properties": {
"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 of this version, with the program's own compensation."
},
"companyId": {
"type": "string"
},
"programId": {
"type": "string"
},
"version": {
"type": "number"
},
"programSnapshot": {
"type": "object",
"properties": {
"currency": {
"anyOf": [
{
"type": "string",
"const": "CAD"
},
{
"type": "string",
"const": "USD"
},
{
"type": "string",
"const": "EUR"
},
{
"type": "string",
"const": "GBP"
}
],
"description": "Must match the company currency."
},
"name": {
"type": "string"
},
"kind": {
"anyOf": [
{
"type": "string",
"const": "referral"
},
{
"type": "string",
"const": "affiliate"
},
{
"type": "string",
"const": "both"
}
]
},
"rewardType": {
"anyOf": [
{
"type": "string",
"const": "offer"
},
{
"type": "string",
"const": "cash"
},
{
"type": "string",
"const": "credit"
}
]
},
"attributionWindowDays": {
"anyOf": [
{
"type": "null"
},
{
"type": "number"
}
],
"description": "Days after a referral that a first purchase, or a milestone, still counts. The latest\nreferral always wins until one qualifies. Only milestone programs may use null, which means\nthe referral never expires."
},
"active": {
"type": "boolean"
},
"orderCategories": {
"type": "object",
"properties": {
"include": {
"type": "array",
"items": {
"type": "string"
}
},
"exclude": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Order categories that earn rewards. Order programs only. The friend incentive has its own\norderCategories. Absent means every order can earn."
},
"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"
]
}
]
},
"tracking": {
"type": "object",
"properties": {
"links": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
]
},
"qrCodes": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
]
},
"attributionCodes": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
]
},
"providerPromoCodes": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
]
}
},
"description": "Tracking methods are independent of kind. Provider discounts require a connected provider."
},
"destinationUrl": {
"type": "string",
"description": "The page partner links and QR codes open. A published signup page's destination takes\nprecedence. Without either, partners have no link."
},
"display": {
"type": "object",
"properties": {
"en": {
"type": "object",
"properties": {
"publicName": {
"type": "string",
"description": "The name partners and customers see. Falls back to the program name."
},
"headline": {
"type": "string",
"description": "Replaces the generated headline, such as \"Give 20%, get $10\"."
},
"milestoneLabel": {
"type": "object",
"properties": {
"one": {
"type": "string"
},
"other": {
"type": "string"
}
},
"required": [
"one",
"other"
],
"description": "Milestone programs only. What one report counts, such as one: \"lesson\", other: \"lessons\".\nIn Russian, other is the genitive plural, such as \"уроков\", which reward terms put after\n\"число\"."
}
}
},
"fr-CA": {
"type": "object",
"properties": {
"publicName": {
"type": "string",
"description": "The name partners and customers see. Falls back to the program name."
},
"headline": {
"type": "string",
"description": "Replaces the generated headline, such as \"Give 20%, get $10\"."
},
"milestoneLabel": {
"type": "object",
"properties": {
"one": {
"type": "string"
},
"other": {
"type": "string"
}
},
"required": [
"one",
"other"
],
"description": "Milestone programs only. What one report counts, such as one: \"lesson\", other: \"lessons\".\nIn Russian, other is the genitive plural, such as \"уроков\", which reward terms put after\n\"число\"."
}
}
},
"hy": {
"type": "object",
"properties": {
"publicName": {
"type": "string",
"description": "The name partners and customers see. Falls back to the program name."
},
"headline": {
"type": "string",
"description": "Replaces the generated headline, such as \"Give 20%, get $10\"."
},
"milestoneLabel": {
"type": "object",
"properties": {
"one": {
"type": "string"
},
"other": {
"type": "string"
}
},
"required": [
"one",
"other"
],
"description": "Milestone programs only. What one report counts, such as one: \"lesson\", other: \"lessons\".\nIn Russian, other is the genitive plural, such as \"уроков\", which reward terms put after\n\"число\"."
}
}
},
"ru": {
"type": "object",
"properties": {
"publicName": {
"type": "string",
"description": "The name partners and customers see. Falls back to the program name."
},
"headline": {
"type": "string",
"description": "Replaces the generated headline, such as \"Give 20%, get $10\"."
},
"milestoneLabel": {
"type": "object",
"properties": {
"one": {
"type": "string"
},
"other": {
"type": "string"
}
},
"required": [
"one",
"other"
],
"description": "Milestone programs only. What one report counts, such as one: \"lesson\", other: \"lessons\".\nIn Russian, other is the genitive plural, such as \"уроков\", which reward terms put after\n\"число\"."
}
}
}
},
"description": "Optional public name, headline and milestone label for partner and customer screens."
},
"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. Defaults to completed orders."
},
"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 fixed rewards change after a partial refund."
},
"duration": {
"anyOf": [
{
"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"
]
}
]
},
"delivery": {
"type": "object",
"properties": {
"cash": {
"anyOf": [
{
"type": "string",
"const": "grizzlee_wallet"
},
{
"type": "string",
"const": "merchant"
}
]
},
"credit": {
"anyOf": [
{
"type": "string",
"const": "grizzlee_wallet"
},
{
"type": "string",
"const": "merchant"
}
]
}
},
"description": "Who delivers approved rewards of each type. Defaults to the Grizzlee wallet for both."
},
"reviewRewards": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
],
"description": "When true, new rewards wait as pending until someone approves them. Otherwise they start approved."
},
"fraudChecks": {
"type": "object",
"properties": {
"selfReferral": {
"type": "object",
"properties": {
"action": {
"anyOf": [
{
"type": "string",
"const": "review"
},
{
"type": "string",
"const": "block"
},
{
"type": "string",
"const": "flag"
},
{
"type": "string",
"const": "off"
}
]
}
}
},
"duplicateAccounts": {
"type": "object",
"properties": {
"action": {
"anyOf": [
{
"type": "string",
"const": "review"
},
{
"type": "string",
"const": "block"
},
{
"type": "string",
"const": "flag"
},
{
"type": "string",
"const": "off"
}
]
},
"accounts": {
"type": "number",
"description": "Customers sharing one card or device that trigger the rule. This one counts when referred inside the window."
},
"windowDays": {
"type": "number"
},
"ipAccounts": {
"anyOf": [
{
"type": "null"
},
{
"type": "number"
}
],
"description": "Customers sharing one IP address that trigger the rule. null leaves IP addresses out."
}
}
},
"rapidRepeats": {
"type": "object",
"properties": {
"action": {
"anyOf": [
{
"type": "string",
"const": "review"
},
{
"type": "string",
"const": "block"
},
{
"type": "string",
"const": "flag"
},
{
"type": "string",
"const": "off"
}
]
},
"referrals": {
"type": "number",
"description": "Referrals from one device that trigger the rule. This one counts when referred inside the window."
},
"windowMinutes": {
"type": "number"
},
"ipReferrals": {
"anyOf": [
{
"type": "null"
},
{
"type": "number"
}
],
"description": "Referrals from one IP address that trigger the rule. null leaves IP addresses out."
}
}
},
"repeatCustomer": {
"type": "object",
"properties": {
"action": {
"anyOf": [
{
"type": "string",
"const": "review"
},
{
"type": "string",
"const": "block"
},
{
"type": "string",
"const": "flag"
},
{
"type": "string",
"const": "off"
}
]
}
}
},
"disposableEmail": {
"type": "object",
"properties": {
"action": {
"anyOf": [
{
"type": "string",
"const": "review"
},
{
"type": "string",
"const": "flag"
},
{
"type": "string",
"const": "off"
}
],
"description": "A disposable address does not show a second person, so this rule cannot block."
}
}
}
},
"description": "Self-referral and other fraud rules. Absent means every rule uses its default."
},
"performance": {
"type": "object",
"properties": {
"metric": {
"anyOf": [
{
"type": "string",
"const": "orders"
},
{
"type": "string",
"const": "new_customers"
}
]
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"minValue": {
"type": "number"
},
"bonusBps": {
"type": "number"
}
},
"required": [
"name",
"minValue",
"bonusBps"
]
}
},
"windowDays": {
"type": "number"
}
},
"required": [
"metric",
"tiers"
]
},
"limits": {
"type": "object",
"properties": {
"customerCapCents": {
"type": "number"
},
"partnerCapCents": {
"type": "number"
}
}
},
"customTerms": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"target": {
"type": "string",
"const": "partner"
},
"targetId": {
"type": "string"
},
"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"
]
}
]
},
"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"
]
}
}
},
"customerCapCents": {
"anyOf": [
{
"type": "null"
},
{
"type": "number"
}
]
},
"partnerCapCents": {
"anyOf": [
{
"type": "null"
},
{
"type": "number"
}
]
}
},
"required": [
"target",
"targetId"
]
},
{
"type": "object",
"properties": {
"target": {
"type": "string",
"const": "customer"
},
"targetId": {
"type": "string"
},
"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"
]
}
]
},
"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"
]
}
}
},
"customerCapCents": {
"anyOf": [
{
"type": "null"
},
{
"type": "number"
}
]
}
},
"required": [
"target",
"targetId"
]
}
]
}
},
"friendIncentive": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "percent"
},
"rateBps": {
"type": "number"
},
"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."
},
"orders": {
"type": "number",
"description": "How many of the friend's orders get the incentive."
},
"newCustomersOnly": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
],
"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": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
],
"description": "true: a full refund gives the use back, so the customer can get the offer again."
},
"orderCategories": {
"type": "object",
"properties": {
"include": {
"type": "array",
"items": {
"type": "string"
}
},
"exclude": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies."
}
},
"required": [
"type",
"rateBps"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "fixed"
},
"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."
},
"orders": {
"type": "number",
"description": "How many of the friend's orders get the incentive."
},
"newCustomersOnly": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
],
"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": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
],
"description": "true: a full refund gives the use back, so the customer can get the offer again."
},
"orderCategories": {
"type": "object",
"properties": {
"include": {
"type": "array",
"items": {
"type": "string"
}
},
"exclude": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies."
}
},
"required": [
"type",
"amountCents"
]
}
],
"description": "Optional offer for the referred customer."
},
"partnerOffer": {
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "percent"
},
"rateBps": {
"type": "number"
},
"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."
},
"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": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
],
"description": "true: a full refund gives the use back, so the customer can get the offer again."
},
"orderCategories": {
"type": "object",
"properties": {
"include": {
"type": "array",
"items": {
"type": "string"
}
},
"exclude": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies."
}
},
"required": [
"type",
"rateBps"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "fixed"
},
"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."
},
"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": {
"anyOf": [
{
"type": "boolean",
"const": false
},
{
"type": "boolean",
"const": true
}
],
"description": "true: a full refund gives the use back, so the customer can get the offer again."
},
"orderCategories": {
"type": "object",
"properties": {
"include": {
"type": "array",
"items": {
"type": "string"
}
},
"exclude": {
"type": "array",
"items": {
"type": "string"
}
}
},
"description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies."
}
},
"required": [
"type",
"amountCents"
]
}
],
"description": "Offer programs only. What the partner earns per qualifying referred order."
}
},
"required": [
"currency",
"name",
"kind",
"rewardType",
"attributionWindowDays",
"active"
]
},
"changedFields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Top-level program fields that differ from the previous version, such as compensation or\nfriendIncentive. Empty for version 1."
},
"createdAt": {
"type": "string",
"description": "When this version took effect. Versions recorded when versioning started use the program's last saved change."
}
},
"required": [
"terms",
"companyId",
"programId",
"version",
"programSnapshot",
"changedFields",
"createdAt"
]
}Errors
Failures return { "error": { "code": "...", "message": "...", "details": {} } }. Details are optional. See error statuses. Reuse an unchanged event payload when retrying.