Reference

@grizzlee/sdk

Keep this entry point on your server. It imports Node cryptography for webhook verification. @grizzlee/sdk/server exports the same client and types.

GrizzleeApiError

class GrizzleeApiError {
  constructor(status: number, code: string, message: string, details?: Record<string, unknown> | undefined);
}

Adds a referral to a destination as ?ref=KARL7Q, plus program and channel when given. Pass the program unless the code and destination identify it on their own. Partner summary links already make that choice.

declare const createReferralLink: (options: ReferralLink & { destination: string; }) => string;

readReferralLink

Reads a referral from an absolute link, such as https://shop.example/join?ref=KARL7Q or myapp://open?.... Reads grizzlee_ref, grizzlee_program and grizzlee_channel from older links, then ref, program and channel. Returns null without a code, or when ref holds something that cannot be a partner code.

declare const readReferralLink: (link: string) => ReferralLink | null;

INSTALL_CLAIM_PARAM

The query parameter that carries an install claim code in a Play Store referrer.

declare const INSTALL_CLAIM_PARAM: "grizzlee_claim";

createPlayStoreUrl

Builds a Play Store link whose install referrer carries an install claim code or a referral. The Play Store hands the referrer to the app after install, with no matching on device or IP. extra adds more referrer pairs, such as utm_source.

declare const createPlayStoreUrl: (options: { packageName: string; installClaim?: string | undefined; referral?: ReferralLink | undefined; extra?: Record<string, string> | undefined; }) => string;

isInstallClaimCode

True when the value looks like an install claim code, such as K7Q2-M9XD-4HPA.

declare const isInstallClaimCode: (value: string) => boolean;

normalizeInstallClaimCode

An install claim code in canonical form: uppercase, without spaces or hyphens. Null when the value cannot be one. Codes are 12 characters of Crockford base32, which has no I, L, O or U.

declare const normalizeInstallClaimCode: (value: string) => string | null;

readAppsFlyerReferral

Reads a referral from an AppsFlyer payload. Pass the result of onDeepLink or onInstallConversionData, or its data or deepLink. A JSON string, which Android can deliver, works too. Looks for grizzlee_ref, grizzlee_program and grizzlee_channel, or ref, program and channel, then a referral link in deep_link_value, then deep_link_sub1 (code), deep_link_sub2 (program) and deep_link_sub3 (channel). The program can be left out when the code is a partner code. Deferred deep links for new installs carry only deep_link_value and deep_link_sub1 to deep_link_sub10, so use those in OneLink. Change the sub keys with keys.

Returns null when the deep link was not found, for organic installs, and for conversion data whose is_first_launch is false, so a cached payload is not captured again on every launch.

declare const readAppsFlyerReferral: (payload: unknown, options?: { keys?: Partial<AppsFlyerReferralKeys> | undefined; }) => ReferralLink | null;

readBranchReferral

Reads a referral from a Branch deep link payload. Pass the event from branch.subscribe ({ error, params, uri }) or its params. Looks for grizzlee_ref, grizzlee_program and grizzlee_channel, or ref, program and channel, in the link data first, then in the query of +non_branch_link, ~referring_link, +url, $canonical_url and $deeplink_path. Returns null when Branch reports an error or +clicked_branch_link is false.

declare const readBranchReferral: (payload: unknown) => ReferralLink | null;

readInstallReferrer

Reads the install referrer string from the Play Install Referrer API, such as grizzlee_claim=K7Q2M9XD4HPA&utm_source=store. Returns the claim code when there is one, otherwise a referral from grizzlee_ref and grizzlee_program or from ref, otherwise null.

declare const readInstallReferrer: (referrer: string | null | undefined) => InstallReferrer | null;

AppsFlyerReferralKeys

Where an AppsFlyer payload carries each referral field when the grizzlee_ keys are absent.

type AppsFlyerReferralKeys = AppsFlyerReferralKeys;

InstallReferrer

What a Play Store install referrer carried: an install claim code, or a referral to capture.

type InstallReferrer = ReferralLink | { installClaim: string; };

computeIncentiveCents

Discount for one order in minor units, for your checkout to apply and report as incentiveAppliedCents. baseCents is the amount your checkout discounts. It returns 0 below minOrderCents. A percentage rounds half up and stops at maxDiscountCents. A fixed amount never exceeds baseCents. It does not check eligibility. Ask your backend for that.

declare const computeIncentiveCents: (terms: IncentivePricingTerms, baseCents: number) => number;

fraudRuleIds

Fraud rules beyond self-referral. Each compares hashed identity signals, never raw values. duplicate_accounts: several customers the same partner referred share a card or device (or an IP address, when enabled) seen within the window. rapid_repeats: the partner received several referrals within minutes from customers on the same device (or IP address, when enabled). repeat_customer: the customer shares a phone, card or device with a different customer who already earned a reward in the same program. disposable_email: the customer's email uses a disposable email domain.

declare const fraudRuleIds: readonly ["duplicate_accounts", "rapid_repeats", "repeat_customer", "disposable_email"];

FRAUD_THRESHOLD_MAX

Highest threshold a velocity rule accepts. A lookup reads this many other customers per signal, so any accepted threshold can be reached.

declare const FRAUD_THRESHOLD_MAX: 200;

MAX_ORDER_CATEGORIES

Most categories one order or checkout can carry.

declare const MAX_ORDER_CATEGORIES: 20;

MAX_CATEGORY_RULES

Most categories one include or exclude list can name.

declare const MAX_CATEGORY_RULES: 50;

orderCategoryMismatch

Why an order's categories fail the rules, or undefined when they pass. excluded names the first excluded category the order has. not_included means include is set and the order has none of its categories, which covers an order without categories.

declare const orderCategoryMismatch: (rules: { include?: string[] | undefined; exclude?: string[] | undefined; } | null | undefined, categories: readonly string[] | null | undefined) => { reason: "excluded"; category: string; } | { reason: "not_included"; } | undefined;

normalizeOrderCategory

How every category slug is compared: trimmed and lowercased.

declare const normalizeOrderCategory: (value: string) => string;

IncentivePricingTerms

The pricing part of a friend incentive. IncentiveOffer and FriendIncentive both fit.

type IncentivePricingTerms = { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; };

ReferralLink

type ReferralLink = ReferralLink;

ReferralChannel

type ReferralChannel = "link" | "qr" | "coupon" | "in_app";

TrackingMethods

type TrackingMethods = { links: boolean; qrCodes: boolean; attributionCodes: boolean; providerPromoCodes: boolean; };

ProviderPromoCode

Provider discounts keep their original offer when a program changes.

type ProviderPromoCode = ProviderPromoCode;

ProviderPromoCodeInput

type ProviderPromoCodeInput = { code: string; programId: string; integrationId: string; };

RenameProviderPromoCodeInput

type RenameProviderPromoCodeInput = { code: string; };

ClaimReferralInput

type ClaimReferralInput = { candidates: ({ type: "receipt"; receipt: string; } | { type: "code"; referralCode: string; programId?: string | undefined; providerPromoCodeId?: string | undefined; enteredAt?: string | undefined; })[]; customerId: string; customerDisplayName?: string | undefined; orderId?: string | undefined; expectedProgramId?: string | undefined; signals?: { email?: string | undefined; phone?: string | undefined; phoneHash?: string | undefined; paymentFingerprint?: string | undefined; deviceId?: string | undefined; ipAddress?: string | undefined; } | undefined; };

ClaimReferralResult

type ClaimReferralResult = ClaimReferralResult;

ReferralCandidate

type ReferralCandidate = { type: "receipt"; receipt: string; } | { type: "code"; referralCode: string; programId?: string | undefined; providerPromoCodeId?: string | undefined; enteredAt?: string | undefined; };

ReferralSelection

type ReferralSelection = { winner: { programId: string; partnerId: string; occurredAt: string; type?: "code" | "receipt" | undefined; providerPromoCodeId?: string | undefined; index?: number | undefined; } | null; skipped: { index: number; reason: "expired" | "invalid" | "self_referral" | "wrong_program" | "program_inactive" | "partner_inactive" | "fraud" | "customer_already_referred" | "older"; }[]; };

ReferralSkipReason

type ReferralSkipReason = "expired" | "invalid" | "self_referral" | "wrong_program" | "program_inactive" | "partner_inactive" | "fraud" | "customer_already_referred" | "older";

AttachReferralCodeInput

type AttachReferralCodeInput = { referralCode: string; customerId: string; programId?: string | undefined; customerDisplayName?: string | undefined; orderId?: string | undefined; signals?: { email?: string | undefined; phone?: string | undefined; phoneHash?: string | undefined; paymentFingerprint?: string | undefined; deviceId?: string | undefined; ipAddress?: string | undefined; } | undefined; channel?: "link" | "qr" | "coupon" | "in_app" | undefined; };

AttachReferralCodeResponse

type AttachReferralCodeResponse = AttachReferralCodeResponse;

Attribution

type Attribution = Attribution;

CaptureReferralResponse

Response of the public capture endpoint.

type CaptureReferralResponse = CaptureReferralResponse;

InstallClaim

A single-use code that carries a web capture into a freshly installed app. The landing page puts it in the Play Store referrer or shows it to the visitor, and the app redeems it at first launch.

type InstallClaim = InstallClaim;

FixedRefundMode

type FixedRefundMode = "prorate" | "full_refund_only";

FriendIncentive

type FriendIncentive = { type: "percent"; rateBps: number; orders: number; newCustomersOnly: boolean; expiresAfterDays: number | null; returnOnFullRefund: boolean; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; orders: number; newCustomersOnly: boolean; expiresAfterDays: number | null; returnOnFullRefund: boolean; amountCents: number; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; };

FriendIncentiveInput

type FriendIncentiveInput = { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orders?: number | undefined; newCustomersOnly?: boolean | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; orders?: number | undefined; newCustomersOnly?: boolean | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; };

PartnerOffer

type PartnerOffer = { type: "percent"; rateBps: number; orders: number; expiresAfterDays: number | null; returnOnFullRefund: boolean; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; orders: number; expiresAfterDays: number | null; returnOnFullRefund: boolean; amountCents: number; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; };

PartnerOfferInput

type PartnerOfferInput = { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orders?: number | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; orders?: number | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; };

EarnedOfferTerms

type EarnedOfferTerms = ({ type: "percent"; rateBps: number; orders: number; expiresAfterDays: number | null; returnOnFullRefund: boolean; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; orders: number; expiresAfterDays: number | null; returnOnFullRefund: boolean; amountCents: number; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; }) & { currency: "CAD" | "USD" | "EUR" | "GBP"; };

OfferTerms

Terms a checkout prices.

type OfferTerms = EarnedOfferTerms | IncentiveOffer;

IncentiveKind

type IncentiveKind = "friend" | "earned";

EarnedOfferStatus

type EarnedOfferStatus = "expired" | "pending" | "available" | "used" | "voided";

CustomerImportInput

type CustomerImportInput = { customers: { customerId: string; priorOrderCount: number; }[]; };

IdentitySignals

type IdentitySignals = { email?: string | undefined; phone?: string | undefined; phoneHash?: string | undefined; paymentFingerprint?: string | undefined; deviceId?: string | undefined; ipAddress?: string | undefined; };

IdentitySignalType

type IdentitySignalType = "email" | "phone" | "card" | "device" | "ip";

IncentiveFlag

Recorded on an order Grizzlee accepted with an incentive that did not match the terms.

type IncentiveFlag = IncentiveFlag;

IncentiveFlagReason

type IncentiveFlagReason = "no_reservation" | "reservation_expired" | "reservation_released" | "reservation_consumed" | "reservation_locked" | "no_referral" | "exceeds_terms" | "category_not_eligible";

IncentiveIneligibleReason

no_incentive: the program has no friend incentive. program_inactive: the program is paused. partner_inactive: the partner is paused or left the program. self_referral: the customer is the partner through a customer link, or shares a strong identity signal in a program that blocks matches. fraud: a fraud rule set to block fired on a phone, card or device match. expired: the incentive's days after the referral have passed. not_new_customer: the program requires a new customer and the merchant said false, or the recorded purchase number is past its order count. order_limit_reached: the customer already placed that many orders since the referral. uses_exhausted: the customer already used the incentive on that many orders. reservation_open: another order holds the remaining uses in an open reservation. category_not_eligible: the categories sent have an excluded one, or none of the included ones. offer_voided: the held earned offer was rejected or its earning order was fully refunded.

type IncentiveIneligibleReason = "expired" | "self_referral" | "program_inactive" | "partner_inactive" | "fraud" | "no_referral" | "category_not_eligible" | "no_incentive" | "not_new_customer" | "order_limit_reached" | "uses_exhausted" | "reservation_open" | "offer_voided";

IncentiveOffer

A program's friend incentive with the program currency. Public responses use this shape.

type IncentiveOffer = ({ type: "percent"; rateBps: number; orders: number; newCustomersOnly: boolean; expiresAfterDays: number | null; returnOnFullRefund: boolean; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; orders: number; newCustomersOnly: boolean; expiresAfterDays: number | null; returnOnFullRefund: boolean; amountCents: number; minOrderCents?: number | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; }) & { currency: "CAD" | "USD" | "EUR" | "GBP"; };

IncentiveReservation

An order's hold on an offer. Terms are copied when the reservation is made.

type IncentiveReservation = IncentiveReservation;

IncentiveReservationResult

Response of POST /referrals/incentive/reservations.

type IncentiveReservationResult = IncentiveReservationResult;

IncentiveReservationStatus

Open holds end only when their order completes or the merchant releases them.

type IncentiveReservationStatus = "open" | "consumed" | "released";

ReserveIncentiveInput

type ReserveIncentiveInput = { customerId: string; orderId: string; programId?: string | undefined; candidates?: ({ type: "receipt"; receipt: string; } | { type: "code"; referralCode: string; programId?: string | undefined; providerPromoCodeId?: string | undefined; enteredAt?: string | undefined; })[] | undefined; signals?: { email?: string | undefined; phone?: string | undefined; phoneHash?: string | undefined; paymentFingerprint?: string | undefined; deviceId?: string | undefined; ipAddress?: string | undefined; } | undefined; newCustomer?: boolean | undefined; baseCents?: number | undefined; categories?: string[] | undefined; };

ReferralIncentive

Response of POST /referrals/incentive.

type ReferralIncentive = ReferralIncentive;

ReferralIncentiveInput

type ReferralIncentiveInput = { customerId: string; programId?: string | undefined; candidates?: ({ type: "receipt"; receipt: string; } | { type: "code"; referralCode: string; programId?: string | undefined; providerPromoCodeId?: string | undefined; enteredAt?: string | undefined; })[] | undefined; orderId?: string | undefined; signals?: { email?: string | undefined; phone?: string | undefined; phoneHash?: string | undefined; paymentFingerprint?: string | undefined; deviceId?: string | undefined; ipAddress?: string | undefined; } | undefined; newCustomer?: boolean | undefined; categories?: string[] | undefined; customerOrderNumber?: number | undefined; };

Program

type Program = Program;

ProgramTrigger

type ProgramTrigger = { type: "order"; } | { type: "milestone"; milestone: string; };

Duration

type Duration = { type: "only_order"; } | { type: "first_order"; } | { type: "first_n_orders"; count: number; } | { type: "days"; days: number; } | { type: "months"; months: number; } | { type: "lifetime"; };

Compensation

type Compensation = { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; };

LocalizedText

Text in every supported language: en, fr-CA, hy and ru.

type LocalizedText = { en: string; "fr-CA": string; hy: string; ru: string; };

ProgramRewardTerms

A program's reward terms for one partner. The structured fields are the source of truth. The text is a short generic summary for screens that do not format their own.

type ProgramRewardTerms = ProgramRewardTerms;

ProgramVersion

One saved version of a program. Versions never change. programSnapshot holds every rule as it was when the version was saved. A rename alone adds no version, so the name is the one the program had when this version was saved.

type ProgramVersion = ProgramVersion;

ProgramVersionDetail

Response of GET /programs/:id/versions/:version and each item of the list.

type ProgramVersionDetail = ProgramVersionDetail;

ProgramVersionList

Response of GET /programs/:id/versions. Newest first.

type ProgramVersionList = ProgramVersionList;

TermsCompensation

Compensation in readable terms. Percentage terms carry the rate and its schedule.

type TermsCompensation = { type: "percentage"; rateBps: number; phases: { afterMonths: number; rateBps: number; }[]; } | { type: "fixed"; amountCents: number; };

MilestoneResult

Response of POST /milestones, POST /milestones/revoke, POST /milestones/reinstate and POST /milestones/reverse.

type MilestoneResult = MilestoneResult;

MilestoneStatus

recorded: Grizzlee processed the report. decisions say which programs rewarded it. revoked: the milestone is revoked for this person. A report still counts but earns nothing until a reinstatement. Revocations always return revoked. reinstated: reinstatements always return it, including one that found the milestone not revoked and changed nothing. reversed: reversals always return it, including one for a report that was already reversed.

type MilestoneStatus = "recorded" | "revoked" | "reinstated" | "reversed";

MilestoneRewards

type MilestoneRewards = { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; };

ReinstateMilestoneInput

type ReinstateMilestoneInput = { customerId: string; milestone: string; eventId: string; reason?: string | undefined; };

ReportMilestoneInput

type ReportMilestoneInput = { customerId: string; occurredAt: string; milestone: string; eventId: string; valueCents?: number | undefined; };

ReverseMilestoneReportInput

type ReverseMilestoneReportInput = { eventId: string; reportEventId: string; reason?: string | undefined; };

RevokeMilestoneInput

type RevokeMilestoneInput = { customerId: string; reason: string; milestone: string; eventId: string; };

RejectRewardInput

type RejectRewardInput = { reason?: string | undefined; };

Reward

type Reward = Reward;

TextPart

One sentence of text Grizzlee writes in English, as a stable code and the values it names, so a client can show it in another language. Amounts are minor units of params.currency, rates are basis points and lists are arrays. The English field next to the parts keeps its wording.

type TextPart = TextPart<Code>;

RewardTextCode

Sentences of a reward explanation. fixed, percentage, offer, report, report_percentage and milestone_bonus say how the amount was worked out. The rest follow it and adjust it. An offer names no terms: they are in the reward's offer, or the program's partner offer.

type RewardTextCode = "fixed" | "percentage" | "offer" | "report" | "report_percentage" | "milestone_bonus" | "schedule_month" | "tier_bonus" | "custom_partner_terms" | "custom_customer_terms" | "capped";

DecisionTextCode

Why a program rewarded or skipped. A rewarded decision uses the reward's explanation codes. self_referral_blocked and fraud_blocked name no values: the decision's selfReferral and fraud hold them.

type DecisionTextCode = "no_referral" | RewardTextCode | "no_order_referral" | "no_customer_referral" | "partner_not_in_program" | "self_referral_blocked" | "fraud_blocked" | "milestone_before_referral" | "order_before_referral" | "report_value_missing" | "milestone_window_expired" | "order_window_expired" | "milestone_progress" | "report_limit_reached" | "milestone_already_rewarded" | "report_value_no_reward" | "customer_cap_reached" | "partner_cap_reached" | "category_excluded" | "categories_missing" | "categories_required" | "first_order_only" | "first_order_after_referral_only" | "first_orders_only" | "first_orders_after_referral_only" | "duration_ended" | "rate_no_reward" | "order_no_reward";

PayoutTextCode

Sentences of a Stripe payout's lastError. payout_changed and delivery_failed carry the error Grizzlee hit as errorCode and detail, its English message.

type PayoutTextCode = "retries_stopped" | "connection_disabled" | "connection_unavailable" | "debt_settled" | "payout_changed" | "delivery_failed" | "no_transfer_sent" | "rewards_payable" | "refund_reduced_earnings" | "rewards_not_marked" | "contact_support" | "transfer_unmatched" | "stripe_key_rejected" | "stripe_key_permission" | "stripe_insufficient_funds" | "partner_onboarding" | "partner_account_missing" | "stripe_rejected" | "stripe_rejected_code" | "answer_kept" | "search_failed" | "not_confirmed" | "rewards_kept" | "earnings_reserved" | "transfer_conflict" | "transfers_conflict" | "check_transfer_group" | "check_transfer_metadata" | "cancelled_no_transfer";

RefundEvent

type RefundEvent = { type: "order.refunded"; orderId: string; occurredAt: string; eventId: string; refundedTotalCents?: number | undefined; refundedCommissionableCents?: number | undefined; fullRefund?: boolean | undefined; };

OrderAdjustmentEvent

type OrderAdjustmentEvent = { type: "order.adjusted"; orderId: string; occurredAt: string; eventId: string; reason?: string | undefined; totalCents?: number | undefined; commissionableCents?: number | undefined; };

OrderAdjustment

One applied order adjustment, with the totals it replaced.

type OrderAdjustment = OrderAdjustment;

SelfReferralAction

type SelfReferralAction = "blocked" | "review" | "flagged";

SelfReferralSignalType

type SelfReferralSignalType = "email" | "phone" | "card" | "device" | "ip" | "customer_id";

SelfReferralMatch

A block stops the reward and incentive. Review holds the reward. A flag records the match.

type SelfReferralMatch = SelfReferralMatch;

FraudChecks

type FraudChecks = { selfReferral: { action: "review" | "block" | "flag" | "off"; }; duplicateAccounts: { action: "review" | "block" | "flag" | "off"; accounts: number; windowDays: number; ipAccounts: number | null; }; rapidRepeats: { action: "review" | "block" | "flag" | "off"; referrals: number; windowMinutes: number; ipReferrals: number | null; }; repeatCustomer: { action: "review" | "block" | "flag" | "off"; }; disposableEmail: { action: "review" | "flag" | "off"; }; };

FraudChecksInput

type FraudChecksInput = { selfReferral?: { action?: "review" | "block" | "flag" | "off" | undefined; } | undefined; duplicateAccounts?: { action?: "review" | "block" | "flag" | "off" | undefined; accounts?: number | undefined; windowDays?: number | undefined; ipAccounts?: number | null | undefined; } | undefined; rapidRepeats?: { action?: "review" | "block" | "flag" | "off" | undefined; referrals?: number | undefined; windowMinutes?: number | undefined; ipReferrals?: number | null | undefined; } | undefined; repeatCustomer?: { action?: "review" | "block" | "flag" | "off" | undefined; } | undefined; disposableEmail?: { action?: "review" | "flag" | "off" | undefined; } | undefined; };

FraudMatch

What Grizzlee did about the fraud rules that fired. action is the strongest of the rules: blocked, then review, then flagged. rules lists each rule with its own action.

type FraudMatch = FraudMatch;

FraudRuleAction

type FraudRuleAction = "review" | "block" | "flag" | "off";

FraudRuleId

type FraudRuleId = "duplicate_accounts" | "rapid_repeats" | "repeat_customer" | "disposable_email";

FraudRuleMatch

One rule that fired and what it did.

type FraudRuleMatch = FraudRuleMatch;

OrderCategoryRules

type OrderCategoryRules = { include?: string[] | undefined; exclude?: string[] | undefined; };

OrderCategoryRulesInput

type OrderCategoryRulesInput = { include?: string[] | undefined; exclude?: string[] | undefined; };

OrderEvent

type OrderEvent = { type: "order.completed"; customerId: string; orderId: string; occurredAt: string; eventId: string; commissionableCents: number; currency: "CAD" | "USD" | "EUR" | "GBP"; customerDisplayName?: string | undefined; newCustomer?: boolean | undefined; categories?: string[] | undefined; customerOrderNumber?: number | undefined; totalCents?: number | undefined; customerEmail?: string | undefined; incentiveAppliedCents?: number | undefined; };

AttributionInput

type AttributionInput = { programId: string; referralCode: string; customerId: string; occurredAt: string; channel: "link" | "qr" | "coupon" | "in_app"; providerPromoCodeId?: string | undefined; customerDisplayName?: string | undefined; orderId?: string | undefined; };

EventResult

type EventResult = EventResult;

ProgramCreateInput

type ProgramCreateInput = { name: string; kind: "referral" | "affiliate" | "both"; rewardType: "offer" | "cash" | "credit"; attributionWindowDays: number | null; active: boolean; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; compensation?: { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; } | undefined; currency?: "CAD" | "USD" | "EUR" | "GBP" | undefined; tracking?: { links?: boolean | undefined; qrCodes?: boolean | undefined; attributionCodes?: boolean | undefined; providerPromoCodes?: boolean | undefined; } | undefined; destinationUrl?: string | undefined; display?: { en?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; "fr-CA"?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; hy?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; ru?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; } | undefined; trigger?: { type: "order"; } | { type: "milestone"; milestone: string; } | undefined; milestoneRewards?: { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; } | undefined; fixedRefundMode?: "prorate" | "full_refund_only" | undefined; duration?: { type: "only_order"; } | { type: "first_order"; } | { type: "first_n_orders"; count: number; } | { type: "days"; days: number; } | { type: "months"; months: number; } | { type: "lifetime"; } | undefined; delivery?: { cash?: "grizzlee_wallet" | "merchant" | undefined; credit?: "grizzlee_wallet" | "merchant" | undefined; } | undefined; reviewRewards?: boolean | undefined; fraudChecks?: { selfReferral?: { action?: "review" | "block" | "flag" | "off" | undefined; } | undefined; duplicateAccounts?: { action?: "review" | "block" | "flag" | "off" | undefined; accounts?: number | undefined; windowDays?: number | undefined; ipAccounts?: number | null | undefined; } | undefined; rapidRepeats?: { action?: "review" | "block" | "flag" | "off" | undefined; referrals?: number | undefined; windowMinutes?: number | undefined; ipReferrals?: number | null | undefined; } | undefined; repeatCustomer?: { action?: "review" | "block" | "flag" | "off" | undefined; } | undefined; disposableEmail?: { action?: "review" | "flag" | "off" | undefined; } | undefined; } | undefined; performance?: { metric: "orders" | "new_customers"; tiers: { name: string; minValue: number; bonusBps: number; }[]; windowDays?: number | undefined; } | undefined; limits?: { customerCapCents?: number | undefined; partnerCapCents?: number | undefined; } | undefined; customTerms?: ({ target: "partner"; targetId: string; compensation?: { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; } | undefined; milestoneRewards?: { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; } | undefined; customerCapCents?: number | null | undefined; partnerCapCents?: number | null | undefined; } | { target: "customer"; targetId: string; compensation?: { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; } | undefined; milestoneRewards?: { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; } | undefined; customerCapCents?: number | null | undefined; })[] | undefined; friendIncentive?: { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orders?: number | undefined; newCustomersOnly?: boolean | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; orders?: number | undefined; newCustomersOnly?: boolean | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | undefined; partnerOffer?: { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orders?: number | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; orders?: number | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | undefined; };

ProgramDeletion

What deleteProgram did. deleted: the program had no referrals, rewards or other history, so it is gone with its versions. archived: it had history, so it is paused, hidden and kept.

type ProgramDeletion = ProgramDeletion;

ProgramDisplay

What a partner or customer screen shows for a program, in every supported language. Missing copy falls back: publicName to the default language's public name and then the program name, headline to terms.text.headline, and the milestone label to "step" and "steps".

type ProgramDisplay = ProgramDisplay;

ProgramDisplayInput

type ProgramDisplayInput = { en?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; "fr-CA"?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; hy?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; ru?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; };

ProgramInput

type ProgramInput = { currency: "CAD" | "USD" | "EUR" | "GBP"; name: string; kind: "referral" | "affiliate" | "both"; rewardType: "offer" | "cash" | "credit"; attributionWindowDays: number | null; active: boolean; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; compensation?: { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; } | undefined; tracking?: { links?: boolean | undefined; qrCodes?: boolean | undefined; attributionCodes?: boolean | undefined; providerPromoCodes?: boolean | undefined; } | undefined; destinationUrl?: string | undefined; display?: { en?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; "fr-CA"?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; hy?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; ru?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; } | undefined; trigger?: { type: "order"; } | { type: "milestone"; milestone: string; } | undefined; milestoneRewards?: { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; } | undefined; fixedRefundMode?: "prorate" | "full_refund_only" | undefined; duration?: { type: "only_order"; } | { type: "first_order"; } | { type: "first_n_orders"; count: number; } | { type: "days"; days: number; } | { type: "months"; months: number; } | { type: "lifetime"; } | undefined; delivery?: { cash?: "grizzlee_wallet" | "merchant" | undefined; credit?: "grizzlee_wallet" | "merchant" | undefined; } | undefined; reviewRewards?: boolean | undefined; fraudChecks?: { selfReferral?: { action?: "review" | "block" | "flag" | "off" | undefined; } | undefined; duplicateAccounts?: { action?: "review" | "block" | "flag" | "off" | undefined; accounts?: number | undefined; windowDays?: number | undefined; ipAccounts?: number | null | undefined; } | undefined; rapidRepeats?: { action?: "review" | "block" | "flag" | "off" | undefined; referrals?: number | undefined; windowMinutes?: number | undefined; ipReferrals?: number | null | undefined; } | undefined; repeatCustomer?: { action?: "review" | "block" | "flag" | "off" | undefined; } | undefined; disposableEmail?: { action?: "review" | "flag" | "off" | undefined; } | undefined; } | undefined; performance?: { metric: "orders" | "new_customers"; tiers: { name: string; minValue: number; bonusBps: number; }[]; windowDays?: number | undefined; } | undefined; limits?: { customerCapCents?: number | undefined; partnerCapCents?: number | undefined; } | undefined; customTerms?: ({ target: "partner"; targetId: string; compensation?: { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; } | undefined; milestoneRewards?: { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; } | undefined; customerCapCents?: number | null | undefined; partnerCapCents?: number | null | undefined; } | { target: "customer"; targetId: string; compensation?: { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; } | undefined; milestoneRewards?: { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; } | undefined; customerCapCents?: number | null | undefined; })[] | undefined; friendIncentive?: { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orders?: number | undefined; newCustomersOnly?: boolean | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; orders?: number | undefined; newCustomersOnly?: boolean | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | undefined; partnerOffer?: { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orders?: number | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; orders?: number | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | undefined; };

ProgramUpdateInput

type ProgramUpdateInput = { name: string; kind: "referral" | "affiliate" | "both"; rewardType: "offer" | "cash" | "credit"; attributionWindowDays: number | null; active: boolean; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | null | undefined; compensation?: { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; } | undefined; currency?: "CAD" | "USD" | "EUR" | "GBP" | undefined; tracking?: { links?: boolean | undefined; qrCodes?: boolean | undefined; attributionCodes?: boolean | undefined; providerPromoCodes?: boolean | undefined; } | undefined; destinationUrl?: string | null | undefined; display?: { en?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; "fr-CA"?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; hy?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; ru?: { publicName?: string | undefined; headline?: string | undefined; milestoneLabel?: { one: string; other: string; } | undefined; } | undefined; } | null | undefined; trigger?: { type: "order"; } | { type: "milestone"; milestone: string; } | undefined; milestoneRewards?: { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; } | undefined; fixedRefundMode?: "prorate" | "full_refund_only" | undefined; duration?: { type: "only_order"; } | { type: "first_order"; } | { type: "first_n_orders"; count: number; } | { type: "days"; days: number; } | { type: "months"; months: number; } | { type: "lifetime"; } | undefined; delivery?: { cash?: "grizzlee_wallet" | "merchant" | undefined; credit?: "grizzlee_wallet" | "merchant" | undefined; } | undefined; reviewRewards?: boolean | undefined; fraudChecks?: { selfReferral?: { action?: "review" | "block" | "flag" | "off" | undefined; } | undefined; duplicateAccounts?: { action?: "review" | "block" | "flag" | "off" | undefined; accounts?: number | undefined; windowDays?: number | undefined; ipAccounts?: number | null | undefined; } | undefined; rapidRepeats?: { action?: "review" | "block" | "flag" | "off" | undefined; referrals?: number | undefined; windowMinutes?: number | undefined; ipReferrals?: number | null | undefined; } | undefined; repeatCustomer?: { action?: "review" | "block" | "flag" | "off" | undefined; } | undefined; disposableEmail?: { action?: "review" | "flag" | "off" | undefined; } | undefined; } | undefined; performance?: { metric: "orders" | "new_customers"; tiers: { name: string; minValue: number; bonusBps: number; }[]; windowDays?: number | undefined; } | undefined; limits?: { customerCapCents?: number | undefined; partnerCapCents?: number | undefined; } | undefined; customTerms?: ({ target: "partner"; targetId: string; compensation?: { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; } | undefined; milestoneRewards?: { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; } | undefined; customerCapCents?: number | null | undefined; partnerCapCents?: number | null | undefined; } | { target: "customer"; targetId: string; compensation?: { type: "percentage"; rateBps: number; phases?: { rateBps: number; afterMonths: number; }[] | undefined; } | { type: "fixed"; amountCents: number; } | undefined; milestoneRewards?: { eachReport?: { compensation: { type: "fixed"; amountCents: number; } | { type: "percentage"; rateBps: number; }; limit?: number | undefined; } | undefined; atCount?: { amountCents: number; count: number; } | undefined; } | undefined; customerCapCents?: number | null | undefined; })[] | undefined; friendIncentive?: { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orders?: number | undefined; newCustomersOnly?: boolean | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; orders?: number | undefined; newCustomersOnly?: boolean | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | null | undefined; partnerOffer?: { type: "percent"; rateBps: number; maxDiscountCents?: number | undefined; minOrderCents?: number | undefined; orders?: number | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | { type: "fixed"; amountCents: number; minOrderCents?: number | undefined; orders?: number | undefined; expiresAfterDays?: number | null | undefined; returnOnFullRefund?: boolean | undefined; orderCategories?: { include?: string[] | undefined; exclude?: string[] | undefined; } | undefined; } | undefined; };

Placement

A company key that names one program.

type Placement = Placement;

SetPlacementInput

type SetPlacementInput = { programId: string; };

PartnerInput

type PartnerInput = { email: string; name: string; externalId: string; customerIds?: string[] | undefined; programIds?: string[] | undefined; addProgramIds?: string[] | undefined; removeProgramIds?: string[] | undefined; labels?: string[] | undefined; properties?: Record<string, string | number | boolean> | undefined; stripeAccountId?: string | null | undefined; locale?: "en" | "fr-CA" | "hy" | "ru" | null | undefined; };

Partner

type Partner = Partner;

PartnerUpsertInput

type PartnerUpsertInput = { email: string; name: string; externalId: string; customerIds?: string[] | undefined; programIds?: string[] | undefined; addProgramIds?: string[] | undefined; removeProgramIds?: string[] | undefined; labels?: string[] | undefined; properties?: Record<string, string | number | boolean> | undefined; stripeAccountId?: string | null | undefined; locale?: "en" | "fr-CA" | "hy" | "ru" | null | undefined; };

PartnerUpsertResult

type PartnerUpsertResult = PartnerUpsertResult;

PartnerUpdateInput

type PartnerUpdateInput = { email?: string | undefined; name?: string | undefined; active?: boolean | undefined; customerIds?: string[] | undefined; programIds?: string[] | undefined; addProgramIds?: string[] | undefined; removeProgramIds?: string[] | undefined; labels?: string[] | undefined; properties?: Record<string, string | number | boolean> | undefined; stripeAccountId?: string | null | undefined; locale?: "en" | "fr-CA" | "hy" | "ru" | null | undefined; };

DeliveryMode

type DeliveryMode = "grizzlee_wallet" | "merchant";

PartnerCreditDeliveryInput

type PartnerCreditDeliveryInput = { amountCents: number; currency: "CAD" | "USD" | "EUR" | "GBP"; externalReference: string; };

PartnerCreditDeliveryResult

type PartnerCreditDeliveryResult = PartnerCreditDeliveryResult;

PartnerDebtRecoveryInput

type PartnerDebtRecoveryInput = { amountCents: number; currency: "CAD" | "USD" | "EUR" | "GBP"; rewardType: "cash" | "credit"; externalReference: string; };

PartnerDebtRecoveryResult

type PartnerDebtRecoveryResult = PartnerDebtRecoveryResult;

ProgramDelivery

type ProgramDelivery = { cash: "grizzlee_wallet" | "merchant"; credit: "grizzlee_wallet" | "merchant"; };

RewardDelivery

Append-only delivery attempt or transfer reversal for a merchant-delivered reward.

type RewardDelivery = RewardDelivery;

RewardDeliveryHistory

Response of GET /rewards/:id/deliveries.

type RewardDeliveryHistory = RewardDeliveryHistory;

PartnerDeliveryDebt

type PartnerDeliveryDebt = PartnerDeliveryDebt;

DeliveryDebtSettlement

restored: a reward restoration or transfer reversal reduced the partner's outstanding debt. netted: the merchant kept part of a later delivery. recovered: the merchant collected it another way.

type DeliveryDebtSettlement = DeliveryDebtSettlement;

Payout

type Payout = Payout;

PayoutAllocation

Append-only link between a merchant payout and one reward it pays.

type PayoutAllocation = PayoutAllocation;

PayoutWithAllocations

A payout with the rewards it pays. Wallet payouts have no allocations.

type PayoutWithAllocations = PayoutWithAllocations;

PayoutPage

type PayoutPage = PayoutPage;

PayoutSchedule

Response of GET and PUT /payout-schedule.

type PayoutSchedule = ({ frequency: "weekly"; weekday: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday"; enabled: boolean; minimumCents: number; holdPeriodDays: number; stripeIntegrationId: string | null; missingStripeAccount: "manual" | "wait"; } | { frequency: "monthly"; enabled: boolean; minimumCents: number; holdPeriodDays: number; stripeIntegrationId: string | null; missingStripeAccount: "manual" | "wait"; dayOfMonth: number; }) & { activeSince: string | null; lastRunOn: string | null; nextRunOn: string | null; updatedAt: string | null; };

PayoutScheduleInput

type PayoutScheduleInput = { frequency: "weekly"; weekday: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday"; enabled: boolean; minimumCents?: number | undefined; holdPeriodDays?: number | undefined; stripeIntegrationId?: string | null | undefined; missingStripeAccount?: "manual" | "wait" | undefined; } | { frequency: "monthly"; enabled: boolean; dayOfMonth: number; minimumCents?: number | undefined; holdPeriodDays?: number | undefined; stripeIntegrationId?: string | null | undefined; missingStripeAccount?: "manual" | "wait" | undefined; };

PayoutScheduleRun

The scheduled run that created a payout.

type PayoutScheduleRun = PayoutScheduleRun;

PayoutWeekday

type PayoutWeekday = "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday";

PartnerSummary

Response of GET /partners/.../summary.

type PartnerSummary = PartnerSummary;

PartnerSummaryProgram

type PartnerSummaryProgram = PartnerSummaryProgram;

PartnerProgramWalletBalance

Reward totals attributable to one program. Wallet operations belong to the partner as a whole.

type PartnerProgramWalletBalance = { currency: "CAD" | "USD" | "EUR" | "GBP"; rewardType: MoneyRewardType; pendingApprovalCents: number; approvedCents: number; };

PartnerClickCounts

Recorded link and QR activity, including code attachments marked with either channel.

type PartnerClickCounts = PartnerClickCounts;

PartnerLinkUnavailableReason

Why a program in a partner summary has no referral link.

type PartnerLinkUnavailableReason = "program_inactive" | "partner_inactive" | "tracking_disabled" | "no_published_page" | "invalid_destination";

PartnerWalletBalance

Wallet-mode rewards of one type. Merchant-delivered rewards are never counted here.

type PartnerWalletBalance = PartnerWalletBalance;

PartnerMerchantBalance

Merchant-delivered rewards of one type. Wallet rewards are never counted here.

type PartnerMerchantBalance = PartnerMerchantBalance;

PartnerReferral

type PartnerReferral = PartnerReferral;

PartnerReferralStatus

claimed: this partner holds the referral and no purchase has qualified yet. qualified: a purchase qualified while this partner held it. displaced: a later referral by another partner took it over before any purchase qualified. expired: this partner holds it, nothing qualified and the program's attribution window has passed.

type PartnerReferralStatus = "expired" | "claimed" | "qualified" | "displaced";

PartnerReferralPage

type PartnerReferralPage = PartnerReferralPage;

PartnerReward

type PartnerReward = PartnerReward;

PartnerRewardDelivery

type PartnerRewardDelivery = PartnerRewardDelivery;

PartnerRewardDeliveryStatus

not_applicable: the Grizzlee wallet pays the reward, or a merchant reward was fully reversed before any delivery. undelivered: the merchant still owes some of it. in_payout: an open merchant payout includes it. delivered: the merchant delivered everything it owes. failed: the latest delivery attempt failed and something is still owed.

type PartnerRewardDeliveryStatus = "not_applicable" | "undelivered" | "in_payout" | "delivered" | "failed";

PartnerRewardPage

type PartnerRewardPage = PartnerRewardPage;

CreateEmbedSessionInput

type CreateEmbedSessionInput = { partner: { externalId: string; } | { id: string; }; programIds?: string[] | undefined; locale?: "en" | "fr-CA" | "hy" | "ru" | undefined; layout?: "full" | "simple" | undefined; actions?: ("payout_details:write" | "profile:write")[] | undefined; ttlSeconds?: number | undefined; embedOrigin?: string | undefined; placement?: string | undefined; };

CreateEmbedSessionResponse

type CreateEmbedSessionResponse = CreateEmbedSessionResponse;

EmbedSession

An embed session as the merchant's server sees it. Token hashes never leave the database.

type EmbedSession = EmbedSession;

EmbedAction

type EmbedAction = "payout_details:write" | "profile:write";

EmbedLocale

type EmbedLocale = "en" | "fr-CA" | "hy" | "ru";

EmbedLayout

type EmbedLayout = "full" | "simple";

EmbedExchangeResponse

Response of POST /api/embed/exchange, read by the embedded frame.

type EmbedExchangeResponse = EmbedExchangeResponse;

EmbedSummary

A scoped summary omits wallet operations, which have no program allocations.

type EmbedSummary = EmbedSummary;

EmbedPayout

A payout as the embedded dashboard shows it. Provider errors, references, destinations and internal IDs stay with the merchant.

type EmbedPayout = EmbedPayout;

EmbedPayoutPage

type EmbedPayoutPage = EmbedPayoutPage;

EmbedReferral

Partner-facing rows contain only the fields the frame displays.

type EmbedReferral = EmbedReferral;

EmbedReferralPage

type EmbedReferralPage = EmbedReferralPage;

EmbedReward

type EmbedReward = EmbedReward;

EmbedRewardPage

type EmbedRewardPage = EmbedRewardPage;

ErasureCounts

What one erasure call changed. A repeat call counts only what arrived since the last one, so its counts are usually zero.

type ErasureCounts = ErasureCounts;

PartnerErasureResult

Response of POST /partners/:id/erase and POST /partners/by-external-id/:externalId/erase.

type PartnerErasureResult = PartnerErasureResult;

CustomerErasureResult

Response of POST /customers/:customerId/erase.

type CustomerErasureResult = CustomerErasureResult;

ERASED_PARTNER_NAME

Name an erased partner keeps.

declare const ERASED_PARTNER_NAME: "Erased partner";

ERASED_TEXT

Replaces free text that erasure removes, such as a rejection or revocation reason.

declare const ERASED_TEXT: "[erased]";

RevokeEmbedSessionResponse

type RevokeEmbedSessionResponse = EmbedSession;

GetPartnerByExternalIdResponse

type GetPartnerByExternalIdResponse = Partner;

PartnerSignalsInput

Identity signals sent with a partner. Grizzlee stores keyed hashes, compares them with the customers the partner refers and never returns them.

type PartnerSignalsInput = PartnerSignalsInput;

UpdatePartnerByExternalIdInput

Add or remove enrollments, replace programIds, or send signals alone.

type UpdatePartnerByExternalIdInput = { email?: string | undefined; name?: string | undefined; active?: boolean | undefined; customerIds?: string[] | undefined; programIds?: string[] | undefined; addProgramIds?: string[] | undefined; removeProgramIds?: string[] | undefined; labels?: string[] | undefined; properties?: Record<string, string | number | boolean> | undefined; stripeAccountId?: string | null | undefined; locale?: "en" | "fr-CA" | "hy" | "ru" | null | undefined; } & PartnerSignalsInput;

UpdatePartnerByExternalIdResponse

type UpdatePartnerByExternalIdResponse = Partner;

UpsertPartnerInput

Omit programIds when a sync must preserve enrollments from the dashboard or placements.

type UpsertPartnerInput = { email: string; name: string; externalId: string; customerIds?: string[] | undefined; programIds?: string[] | undefined; addProgramIds?: string[] | undefined; removeProgramIds?: string[] | undefined; labels?: string[] | undefined; properties?: Record<string, string | number | boolean> | undefined; stripeAccountId?: string | null | undefined; locale?: "en" | "fr-CA" | "hy" | "ru" | null | undefined; } & PartnerSignalsInput;

UpsertPartnerResponse

type UpsertPartnerResponse = PartnerUpsertResult;

DeliverRewardInput

type DeliverRewardInput = DeliverRewardInput;

DeliverRewardResponse

type DeliverRewardResponse = RewardDelivery;

FailRewardDeliveryInput

type FailRewardDeliveryInput = FailRewardDeliveryInput;

FailRewardDeliveryResponse

type FailRewardDeliveryResponse = RewardDelivery;

ListRewardDeliveriesResponse

type ListRewardDeliveriesResponse = RewardDeliveryHistory;

RecoverPartnerDebtInput

type RecoverPartnerDebtInput = RecoverPartnerDebtInput;

RecoverPartnerDebtResponse

type RecoverPartnerDebtResponse = PartnerDeliveryDebt;

PartnerReference

Address a partner by your external ID or by Grizzlee's internal ID.

type PartnerReference = { externalId: string; } | { id: string; };

CreatePartnerPayoutInput

mode "grizzlee_wallet" reserves the partner's available wallet cash, with provider "manual" or "stripe". mode "merchant" pays listed merchant-delivered cash rewards: you send the money yourself with provider "manual" (the default), or Grizzlee sends a Stripe transfer of the net amount from your Stripe balance with provider "stripe". Stripe payouts default destination to the partner's stripeAccountId.

type CreatePartnerPayoutInput = { amountCents: number; eventId: string; mode: "grizzlee_wallet"; provider: "manual" | "stripe"; integrationId?: string | undefined; destination?: string | undefined; } | { eventId: string; mode: "merchant"; allocations: { amountCents: number; rewardId: string; }[]; integrationId?: string | undefined; amountCents?: number | undefined; provider?: "manual" | "stripe" | undefined; destination?: string | undefined; nettedDebtCents?: number | undefined; };

CreatePartnerPayoutResponse

type CreatePartnerPayoutResponse = PayoutWithAllocations;

MarkPayoutPaidRequest

type MarkPayoutPaidRequest = { externalReference: string; paidAt?: string | undefined; };

MarkPayoutPaidResponse

type MarkPayoutPaidResponse = PayoutWithAllocations;

CancelPayoutRequest

confirmNoTransfer releases a Stripe payout held for review after you checked Stripe and found no transfer for it. Grizzlee searches Stripe again and refuses if it finds one.

type CancelPayoutRequest = { confirmNoTransfer?: boolean | undefined; };

CancelPayoutResponse

type CancelPayoutResponse = PayoutWithAllocations;

ListPartnerPayoutsOptions

type ListPartnerPayoutsOptions = ListPartnerPayoutsOptions;

ListPartnerPayoutsResponse

type ListPartnerPayoutsResponse = PayoutPage;

GetPartnerSummaryResponse

type GetPartnerSummaryResponse = PartnerSummary;

DeliverPartnerCreditInput

type DeliverPartnerCreditInput = { amountCents: number; currency: "CAD" | "USD" | "EUR" | "GBP"; externalReference: string; };

DeliverPartnerCreditResponse

type DeliverPartnerCreditResponse = PartnerCreditDeliveryResult;

RecoverPartnerDebtsInput

type RecoverPartnerDebtsInput = { amountCents: number; currency: "CAD" | "USD" | "EUR" | "GBP"; rewardType: "cash" | "credit"; externalReference: string; };

RecoverPartnerDebtsResponse

type RecoverPartnerDebtsResponse = PartnerDebtRecoveryResult;

ListPartnerReferralsOptions

type ListPartnerReferralsOptions = ListPartnerReferralsOptions;

ListPartnerReferralsResponse

type ListPartnerReferralsResponse = PartnerReferralPage;

ListPartnerRewardsOptions

type ListPartnerRewardsOptions = ListPartnerRewardsOptions;

ListPartnerRewardsResponse

type ListPartnerRewardsResponse = PartnerRewardPage;

GetPayoutResponse

type GetPayoutResponse = PayoutWithAllocations;

GetPayoutScheduleResponse

type GetPayoutScheduleResponse = ({ frequency: "weekly"; weekday: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday"; enabled: boolean; minimumCents: number; holdPeriodDays: number; stripeIntegrationId: string | null; missingStripeAccount: "manual" | "wait"; } | { frequency: "monthly"; enabled: boolean; minimumCents: number; holdPeriodDays: number; stripeIntegrationId: string | null; missingStripeAccount: "manual" | "wait"; dayOfMonth: number; }) & { activeSince: string | null; lastRunOn: string | null; nextRunOn: string | null; updatedAt: string | null; };

UpdatePayoutScheduleInput

type UpdatePayoutScheduleInput = { frequency: "weekly"; weekday: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday"; enabled: boolean; minimumCents?: number | undefined; holdPeriodDays?: number | undefined; stripeIntegrationId?: string | null | undefined; missingStripeAccount?: "manual" | "wait" | undefined; } | { frequency: "monthly"; enabled: boolean; dayOfMonth: number; minimumCents?: number | undefined; holdPeriodDays?: number | undefined; stripeIntegrationId?: string | null | undefined; missingStripeAccount?: "manual" | "wait" | undefined; };

UpdatePayoutScheduleResponse

type UpdatePayoutScheduleResponse = ({ frequency: "weekly"; weekday: "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday" | "sunday"; enabled: boolean; minimumCents: number; holdPeriodDays: number; stripeIntegrationId: string | null; missingStripeAccount: "manual" | "wait"; } | { frequency: "monthly"; enabled: boolean; minimumCents: number; holdPeriodDays: number; stripeIntegrationId: string | null; missingStripeAccount: "manual" | "wait"; dayOfMonth: number; }) & { activeSince: string | null; lastRunOn: string | null; nextRunOn: string | null; updatedAt: string | null; };

GrizzleeServerClient

Keep this client and its API key on the merchant's server.

class GrizzleeServerClient {
  constructor(options: { baseUrl: string; apiKey: string; fetch?: typeof fetch; });
  getCompany(options?: { page?: number; search?: string; rewardStatus?: "all" | Reward["status"] | "review"; }): Promise<CompanySnapshot>;
  listPlacements(): Promise<Placement[]>;
  getPlacement(key: string): Promise<Placement>;
  setPlacement(key: string, input: SetPlacementInput): Promise<Placement>;
  deletePlacement(key: string): Promise<Placement>;
  createProgram(input: ProgramCreateInput): Promise<Program>;
  updateProgram(id: string, input: ProgramUpdateInput): Promise<Program>;
  deleteProgram(id: string): Promise<ProgramDeletion>;
  listProgramVersions(programId: string): Promise<ProgramVersionList>;
  getProgramVersion(programId: string, version: number): Promise<ProgramVersionDetail>;
  registerPartner(input: PartnerInput & PartnerSignalsInput): Promise<Partner>;
  upsertPartner(input: UpsertPartnerInput): Promise<UpsertPartnerResponse>;
  getPartnerByExternalId(externalId: string): Promise<GetPartnerByExternalIdResponse>;
  updatePartnerByExternalId(externalId: string, input: UpdatePartnerByExternalIdInput): Promise<UpdatePartnerByExternalIdResponse>;
  updatePartner(id: string, input: PartnerUpdateInput & PartnerSignalsInput): Promise<Partner>;
  attribute(input: AttributionInput): Promise<Attribution>;
  attachReferralCode(input: AttachReferralCodeInput): Promise<AttachReferralCodeResponse>;
  getReferralIncentive(input: ReferralIncentiveInput): Promise<ReferralIncentive>;
  reserveIncentive(input: ReserveIncentiveInput): Promise<IncentiveReservationResult>;
  releaseIncentive(reservationId: string): Promise<IncentiveReservation>;
  listIncentiveReservations(input?: { customerId?: string; olderThanDays?: number; }): Promise<{ reservations: IncentiveReservation[]; }>;
  importCustomers(input: CustomerImportInput): Promise<{ imported: number; }>;
  claimReferral(input: ClaimReferralInput): Promise<ClaimReferralResult>;
  sendEvent(event: PlatformEvent): Promise<EventResult>;
  adjustOrder(input: Omit<OrderAdjustmentEvent, "type">): Promise<EventResult>;
  completeOrder(event: OrderEvent, options?: { candidates?: ReferralCandidate[]; reservationId?: string; signals?: IdentitySignals; }): Promise<EventResult>;
  reportMilestone(input: ReportMilestoneInput): Promise<MilestoneResult>;
  revokeMilestone(input: RevokeMilestoneInput): Promise<MilestoneResult>;
  reinstateMilestone(input: ReinstateMilestoneInput): Promise<MilestoneResult>;
  reverseMilestoneReport(input: ReverseMilestoneReportInput): Promise<MilestoneResult>;
  simulate(event: OrderEvent, attribution?: AttributionInput): Promise<{ result: EventResult; rewards: Reward[]; }>;
  approveReward(id: string): Promise<Reward>;
  rejectReward(id: string, input?: RejectRewardInput): Promise<Reward>;
  deliverReward(rewardId: string, input: DeliverRewardInput): Promise<DeliverRewardResponse>;
  failRewardDelivery(rewardId: string, input: FailRewardDeliveryInput): Promise<FailRewardDeliveryResponse>;
  listRewardDeliveries(rewardId: string): Promise<ListRewardDeliveriesResponse>;
  recoverPartnerDebt(externalId: string, debtId: string, input: RecoverPartnerDebtInput): Promise<RecoverPartnerDebtResponse>;
  deliverPartnerCredit(externalId: string, input: DeliverPartnerCreditInput): Promise<DeliverPartnerCreditResponse>;
  recoverPartnerDebts(externalId: string, input: RecoverPartnerDebtsInput): Promise<RecoverPartnerDebtsResponse>;
  createPartnerPayout(partner: PartnerReference, input: CreatePartnerPayoutInput): Promise<CreatePartnerPayoutResponse>;
  markPayoutPaid(payoutId: string, input: MarkPayoutPaidRequest): Promise<MarkPayoutPaidResponse>;
  cancelPayout(payoutId: string, input?: CancelPayoutRequest): Promise<CancelPayoutResponse>;
  getPayoutSchedule(): Promise<GetPayoutScheduleResponse>;
  updatePayoutSchedule(input: UpdatePayoutScheduleInput): Promise<UpdatePayoutScheduleResponse>;
  listPartnerPayouts(partner: PartnerReference, options?: ListPartnerPayoutsOptions): Promise<ListPartnerPayoutsResponse>;
  listPartnerPromoCodes(partner: PartnerReference): Promise<ProviderPromoCode[]>;
  createPartnerPromoCode(partner: PartnerReference, input: ProviderPromoCodeInput): Promise<ProviderPromoCode>;
  renamePartnerPromoCode(partner: PartnerReference, codeId: string, input: RenameProviderPromoCodeInput): Promise<ProviderPromoCode>;
  deactivatePartnerPromoCode(partner: PartnerReference, codeId: string): Promise<ProviderPromoCode>;
  getPartnerSummary(partner: PartnerReference): Promise<GetPartnerSummaryResponse>;
  listPartnerReferrals(partner: PartnerReference, options?: ListPartnerReferralsOptions): Promise<ListPartnerReferralsResponse>;
  listPartnerRewards(partner: PartnerReference, options?: ListPartnerRewardsOptions): Promise<ListPartnerRewardsResponse>;
  erasePartner(partner: PartnerReference): Promise<PartnerErasureResult>;
  eraseCustomer(customerId: string): Promise<CustomerErasureResult>;
  createEmbedSession(input: CreateEmbedSessionInput): Promise<CreateEmbedSessionResponse>;
  revokeEmbedSession(sessionId: string): Promise<RevokeEmbedSessionResponse>;
  getPayout(payoutId: string): Promise<GetPayoutResponse>;
  getWallets(partnerId: string): Promise<WalletBalance[]>;
  redeemCredits(input: { partnerId: string; orderId: string; eventId: string; amountCents: number; }): Promise<CreditRedemption>;
  restoreCredits(id: string, input: { eventId: string; restoredCents: number; }): Promise<CreditRedemption>;
}

verifyWebhook

Verify the untouched request body before parsing JSON or processing an event.

declare const verifyWebhook: (input: { secret: string; body: string; eventId: string; signature: string; now?: number | undefined; toleranceSeconds?: number | undefined; }) => boolean;

parseWebhookEvent

Verify the raw body with verifyWebhook first. Throws for invalid JSON or payloads.

declare const parseWebhookEvent: (body: string) => GrizzleeWebhookEvent;

GrizzleeWebhookEvent

Switch on type to narrow data to that event's payload.

type GrizzleeWebhookEvent = { id: string; companyId: string; type: "order.refunded"; data: OrderRefundedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "order.adjusted"; data: OrderAdjustedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "order.completed"; data: OrderCompletedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "partner.created"; data: PartnerCreatedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.created"; data: RewardCreatedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.approved"; data: RewardApprovedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.reversed"; data: RewardReversedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.restored"; data: RewardRestoredWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.adjusted"; data: RewardAdjustedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.delivered"; data: RewardDeliveredWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.delivery_failed"; data: RewardDeliveryFailedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.debt_recorded"; data: RewardDebtRecordedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "reward.debt_settled"; data: RewardDebtSettledWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.created"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.paid"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.reversed"; data: PayoutReversedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.failed"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.needs_action"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.cancelled"; data: PayoutWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "payout.account_required"; data: PayoutAccountRequiredWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "credit.redeemed"; data: CreditRedeemedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "credit.restored"; data: CreditRestoredWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "incentive.flagged"; data: IncentiveFlaggedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "self_referral.detected"; data: SelfReferralDetectedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "fraud.flagged"; data: FraudFlaggedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "referral.displaced"; data: ReferralDisplacedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "milestone.reported"; data: MilestoneReportedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "milestone.revoked"; data: MilestoneRevokedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "milestone.reinstated"; data: MilestoneReinstatedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "milestone.reversed"; data: MilestoneReversedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "partner.erased"; data: PartnerErasedWebhookPayload; createdAt: string; } | { id: string; companyId: string; type: "customer.erased"; data: CustomerErasedWebhookPayload; createdAt: string; };

GrizzleeWebhookEventType

type GrizzleeWebhookEventType = "order.refunded" | "order.adjusted" | "order.completed" | "partner.created" | "reward.created" | "reward.approved" | "reward.reversed" | "reward.restored" | "reward.adjusted" | "reward.delivered" | "reward.delivery_failed" | "reward.debt_recorded" | "reward.debt_settled" | "payout.created" | "payout.paid" | "payout.reversed" | "payout.failed" | "payout.needs_action" | "payout.cancelled" | "payout.account_required" | "credit.redeemed" | "credit.restored" | "incentive.flagged" | "self_referral.detected" | "fraud.flagged" | "referral.displaced" | "milestone.reported" | "milestone.revoked" | "milestone.reinstated" | "milestone.reversed" | "partner.erased" | "customer.erased";

GrizzleeWebhookPayloads

type GrizzleeWebhookPayloads = GrizzleeWebhookPayloads;

WebhookPartnerReference

type WebhookPartnerReference = WebhookPartnerReference;

RewardWebhookPayload

Switch on trigger, or check milestone, to read the order or the milestone.

type RewardWebhookPayload = RewardWebhookFields & RewardWebhookSource;

RewardWebhookFields

type RewardWebhookFields = RewardWebhookFields;

RewardWebhookSource

What earned a reward. Order rewards carry orderId. Milestone rewards carry milestone and no orderId. Payloads queued before milestones existed have no trigger and are order rewards.

type RewardWebhookSource = { trigger?: "order" | undefined; orderId: string; } | { trigger: "milestone"; milestone: string; };

RewardCreatedWebhookPayload

Keeps the original raw reward fields as well as the nested reward.

type RewardCreatedWebhookPayload = RewardWebhookPayload & Reward;

RewardApprovedWebhookPayload

type RewardApprovedWebhookPayload = RewardWebhookPayload & Reward;

RewardReversedWebhookPayload

Sent after a refund, a milestone revocation or a milestone report reversal reverses part or all of a reward.

type RewardReversedWebhookPayload = RewardWebhookPayload & { reversalCents: number; };

RewardRestoredWebhookPayload

Sent after a lower refund total, a milestone reinstatement or a milestone report that brings the count back to the threshold gives back part or all of a reversed reward.

type RewardRestoredWebhookPayload = RewardWebhookPayload & { restoredCents: number; };

RewardAdjustedWebhookPayload

Sent when an order adjustment changed what an order reward is worth. changeCents is signed: positive when the order total went up, negative when it went down.

type RewardAdjustedWebhookPayload = RewardWebhookPayload & { eventId: string; changeCents: number; };

RewardDeliveredWebhookPayload

type RewardDeliveredWebhookPayload = RewardWebhookPayload & { delivery: RewardDelivery; };

RewardDeliveryFailedWebhookPayload

type RewardDeliveryFailedWebhookPayload = RewardWebhookPayload & { delivery: RewardDelivery; };

RewardDebtRecordedWebhookPayload

Sent when a reversal leaves the partner holding part of a reward the merchant already delivered. debt is the new debt with outstandingCents equal to amountCents.

type RewardDebtRecordedWebhookPayload = RewardWebhookPayload & { debt: PartnerDeliveryDebt; };

RewardDebtSettledWebhookPayload

Sent once for each settlement of a delivery debt. reward is the reward the debt belongs to. debt shows its outstandingCents and settlements right after this settlement.

type RewardDebtSettledWebhookPayload = RewardWebhookPayload & { debt: PartnerDeliveryDebt; settlement: DeliveryDebtSettlement; settledCents: number; };

PayoutWebhookPayload

type PayoutWebhookPayload = PayoutWebhookPayload;

PayoutReversedWebhookPayload

type PayoutReversedWebhookPayload = PayoutReversedWebhookPayload;

PayoutAccountRequiredWebhookPayload

Sent when a scheduled run creates no payout for a partner because the schedule waits for a Stripe account and the partner has none. Sent once per wait: later runs that skip the same partner send nothing until the partner is paid or has nothing payable at a run. The amounts are what the run would have paid. The rewards stay payable and roll over.

type PayoutAccountRequiredWebhookPayload = PayoutAccountRequiredWebhookPayload;

PartnerCreatedWebhookPayload

type PartnerCreatedWebhookPayload = PartnerCreatedWebhookPayload;

OrderWebhookPartners

type OrderWebhookPartners = OrderWebhookPartners;

OrderCompletedWebhookPayload

type OrderCompletedWebhookPayload = { type: "order.completed"; customerId: string; orderId: string; occurredAt: string; eventId: string; commissionableCents: number; currency: "CAD" | "USD" | "EUR" | "GBP"; customerDisplayName?: string | undefined; newCustomer?: boolean | undefined; categories?: string[] | undefined; customerOrderNumber?: number | undefined; totalCents?: number | undefined; customerEmail?: string | undefined; incentiveAppliedCents?: number | undefined; } & OrderWebhookPartners & { customerOrderNumber?: number | undefined; reportedCustomerOrderNumber?: number | undefined; incentiveFlag?: IncentiveFlag | undefined; referralSelection?: { winner: { programId: string; partnerId: string; occurredAt: string; type?: "code" | "receipt" | undefined; providerPromoCodeId?: string | undefined; index?: number | undefined; } | null; skipped: { index: number; reason: "expired" | "invalid" | "self_referral" | "wrong_program" | "program_inactive" | "partner_inactive" | "fraud" | "customer_already_referred" | "older"; }[]; } | undefined; };

OrderRefundedWebhookPayload

type OrderRefundedWebhookPayload = { type: "order.refunded"; orderId: string; occurredAt: string; eventId: string; refundedTotalCents?: number | undefined; refundedCommissionableCents?: number | undefined; fullRefund?: boolean | undefined; } & OrderWebhookPartners;

OrderAdjustedWebhookPayload

Sent once for each applied order adjustment. A stale adjustment sends nothing. Each reward whose value changed also sends reward.adjusted.

type OrderAdjustedWebhookPayload = { type: "order.adjusted"; orderId: string; occurredAt: string; eventId: string; reason?: string | undefined; totalCents?: number | undefined; commissionableCents?: number | undefined; } & OrderWebhookPartners & { customerId: string; currency: "CAD" | "USD" | "EUR" | "GBP"; previousTotalCents?: number | undefined; previousCommissionableCents?: number | undefined; rewardIds: string[]; rewardChangeCents: number; };

CreditRedeemedWebhookPayload

type CreditRedeemedWebhookPayload = CreditRedeemedWebhookPayload;

CreditRestoredWebhookPayload

type CreditRestoredWebhookPayload = CreditRestoredWebhookPayload;

IncentiveFlaggedWebhookPayload

Sent with order.completed when Grizzlee accepted an order whose incentiveAppliedCents did not match its reservation.

type IncentiveFlaggedWebhookPayload = IncentiveFlaggedWebhookPayload;

SelfReferralDetectedWebhookPayload

Sent when a new completed order or milestone report matched a linked customer ID or the referring partner's identity signals. blocked: the program created no reward. review: rewardId names the reward held as pending. flagged: rewardId names a reward that follows the usual approval. signals lists the matching signal types, never their values.

type SelfReferralDetectedWebhookPayload = WebhookPartnerReference & SelfReferralMatch & ({ eventId: string; programId: string; customerId: string; rewardId?: string | undefined; } & ({ trigger: "order"; orderId: string; } | { trigger: "milestone"; milestone: string; }));

FraudFlaggedWebhookPayload

Sent when fraud rules fired on a new completed order or milestone report. It covers every rule in fraudRuleIds. Self-referral matches keep their own self_referral.detected event, and a referral that triggers both sends both. blocked: the program created no reward. review: rewardId names the reward held as pending. flagged: rewardId names a reward that follows the usual approval. rules lists rule IDs and signal types, never values.

type FraudFlaggedWebhookPayload = WebhookPartnerReference & FraudMatch & ({ eventId: string; programId: string; customerId: string; rewardId?: string | undefined; } & ({ trigger: "order"; orderId: string; } | { trigger: "milestone"; milestone: string; }));

ReferralDisplacedWebhookPayload

Sent when a referral by another partner took over a customer's attribution in a program before a purchase or milestone locked it. partnerId names the new partner.

type ReferralDisplacedWebhookPayload = ReferralDisplacedWebhookPayload;

MilestoneWebhookFields

Fields of milestone.reported, milestone.revoked, milestone.reinstated and milestone.reversed. partners lists the distinct partners from the decisions and rewards, with top-level partnerId and partnerExternalId when there is one.

type MilestoneWebhookFields = MilestoneWebhookFields;

MilestoneReportedWebhookPayload

Sent once for each new milestone report, rewarded or not.

type MilestoneReportedWebhookPayload = MilestoneReportedWebhookPayload;

MilestoneRevokedWebhookPayload

Sent when a milestone is revoked for a person. Revoking it again while it is revoked sends nothing. After a reinstatement, the next revocation sends it again.

type MilestoneRevokedWebhookPayload = MilestoneRevokedWebhookPayload;

MilestoneReinstatedWebhookPayload

Sent when a revoked milestone is reinstated for a person. A reinstatement of a milestone that is not revoked sends nothing.

type MilestoneReinstatedWebhookPayload = MilestoneReinstatedWebhookPayload;

MilestoneReversedWebhookPayload

Sent when a report is reversed. Reversing a report that is already reversed sends nothing. rewardIds lists every reward for the person and milestone. The report's own rewards and bonuses whose count fell below their saved threshold reverse and also send reward.reversed.

type MilestoneReversedWebhookPayload = MilestoneReversedWebhookPayload;

PartnerErasedWebhookPayload

Sent the first time a merchant erases a partner. The partner keeps its IDs and amounts.

type PartnerErasedWebhookPayload = PartnerErasedWebhookPayload;

CustomerErasedWebhookPayload

Sent the first time a merchant erases a customer. Orders and rewards keep the customer ID.

type CustomerErasedWebhookPayload = CustomerErasedWebhookPayload;