{ "openapi": "3.1.0", "info": { "title": "Grizzlee API", "version": "0.30.0" }, "servers": [ { "url": "https://app.grizzlee.ca" } ], "components": { "securitySchemes": { "serverKey": { "type": "http", "scheme": "bearer" } } }, "paths": { "/api/v1/company": { "get": { "operationId": "getCompany", "summary": "getCompany", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "rewardStatus", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "review" }, { "type": "string", "const": "all" }, { "type": "string", "const": "approved" } ], "description": "review lists rewards a self-referral match or fraud rule recorded, held or not." } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "languages": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ] }, "description": "Languages partners and customers see, in order. The first is the default. Companies saved\nbefore languages existed have none, which means English only. See companyLanguages." }, "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" } ] } }, "required": [ "cash", "credit" ], "description": "Who delivers approved cash and store credit rewards for programs created from the dashboard.\nAbsent means the Grizzlee wallet for both. Programs keep their own delivery. This is only the\ndefault a new program starts with." }, "partnerFields": { "type": "array", "items": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "const": "number" }, { "type": "string", "const": "boolean" }, { "type": "string", "const": "text" }, { "type": "string", "const": "select" } ] }, "name": { "type": "string" }, "id": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "name", "id" ] } } }, "required": [ "id", "name", "currency" ] }, "programs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "createdAt": { "type": "string" }, "version": { "type": "number", "description": "1 when created. Every saved change except a rename adds 1. Rewards and incentive reservations\nrecord the version they were made under." }, "updatedAt": { "type": "string", "description": "Last saved change, including renames." }, "archivedAt": { "type": "string", "description": "When deleteProgram archived the program because it has history. An archived program stays\ninactive, has no placement keys and refuses changes. Its referrals, rewards and versions stay." }, "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": [ "id", "companyId", "createdAt", "version", "updatedAt", "currency", "name", "kind", "rewardType", "attributionWindowDays", "active" ] } }, "placements": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } }, "programVersions": { "type": "array", "items": { "type": "object", "properties": { "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": [ "companyId", "programId", "version", "programSnapshot", "changedFields", "createdAt" ] }, "description": "Every saved version of the listed programs, oldest first." }, "programPages": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "programId", "destination" ] } }, "partners": { "type": "array", "items": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } }, "attributions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "qualifiedAt": { "type": "string" }, "qualifiedOrderNumber": { "type": "number" }, "programId": { "type": "string" }, "referralCode": { "type": "string" }, "customerId": { "type": "string" }, "occurredAt": { "type": "string" }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "providerPromoCodeId": { "type": "string" }, "customerDisplayName": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "referralCode", "customerId", "occurredAt", "channel" ] } }, "orders": { "type": "array", "items": { "type": "object", "properties": { "companyId": { "type": "string" }, "customerOrderNumber": { "type": "number", "description": "Grizzlee's count of the customer's purchases, including this one. Never renumbered." }, "reportedCustomerOrderNumber": { "type": "number", "description": "The merchant's customerOrderNumber when it disagreed with Grizzlee's." }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] } }, "rewarded": { "type": "boolean" }, "refundedTotalCents": { "type": "number" }, "refundedCommissionableCents": { "type": "number" }, "fullyRefunded": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "lastRefundAt": { "type": "string", "description": "occurredAt of the latest refund event applied to this order. Older refund events are ignored." }, "incentiveFlag": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "const": "no_reservation" }, { "type": "string", "const": "reservation_expired" }, { "type": "string", "const": "reservation_released" }, { "type": "string", "const": "reservation_consumed" }, { "type": "string", "const": "reservation_locked" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "exceeds_terms" }, { "type": "string", "const": "category_not_eligible" } ] }, "rewardId": { "type": "string" }, "programId": { "type": "string", "description": "Program of the reservation or referral checked. Absent for no_referral." }, "reservationId": { "type": "string", "description": "The reservation sent with the order, when there was one." }, "maxCents": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Largest discount the terms allow on one order. Null when they set no cap or there are no terms." }, "reportedCents": { "type": "number", "description": "incentiveAppliedCents as the merchant reported it." } }, "required": [ "reason", "maxCents", "reportedCents" ], "description": "Present when incentiveAppliedCents did not match the referral's friend incentive." }, "adjustedTotalCents": { "type": "number", "description": "The reporting total after the latest adjustment. totalCents keeps the completed value." }, "adjustedCommissionableCents": { "type": "number", "description": "The commissionable amount after the latest adjustment. commissionableCents keeps the completed value." }, "lastAdjustedAt": { "type": "string", "description": "occurredAt of the latest adjustment applied to this order. Older adjustments are ignored." }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string" }, "totalCents": { "type": "number" }, "previousTotalCents": { "type": "number" }, "commissionableCents": { "type": "number" }, "previousCommissionableCents": { "type": "number" }, "reason": { "type": "string" }, "occurredAt": { "type": "string" }, "rewardChangeCents": { "type": "number", "description": "Signed change to the value of the order's rewards." } }, "required": [ "eventId", "occurredAt", "rewardChangeCents" ] }, "description": "Every applied adjustment, oldest first." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] }, "type": { "type": "string", "const": "order.completed" }, "customerId": { "type": "string" }, "orderId": { "type": "string" }, "occurredAt": { "type": "string" }, "eventId": { "type": "string" }, "commissionableCents": { "type": "number", "description": "Merchant-selected amount for percentage rewards and fixed-reward refund proration." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "customerDisplayName": { "type": "string" }, "newCustomer": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "The merchant's answer from its own order history. Omitted, Grizzlee uses recorded purchases." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The order's categories, such as its product or service types. Programs and friend incentives\ncan include or exclude them. Lowercased, sorted and deduplicated. An order without them\nstill counts as a purchase." }, "totalCents": { "type": "number", "description": "What the customer paid. Used only for reporting." }, "customerEmail": { "type": "string" }, "incentiveAppliedCents": { "type": "number", "description": "Friend incentive discount the merchant's checkout applied to this order. Merchant servers\nonly. Grizzlee stores it as reported and flags the order when it does not match the terms\nof the reservation sent with it. It never rejects the order over it." } }, "required": [ "companyId", "customerOrderNumber", "decisions", "rewarded", "refundedTotalCents", "refundedCommissionableCents", "type", "customerId", "orderId", "occurredAt", "eventId", "commissionableCents", "currency" ] } }, "rewards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The order that earned the reward. Absent on milestone rewards." }, "milestone": { "type": "string", "description": "The milestone that earned the reward. Absent on order rewards. Exactly one of the two is set." }, "reportEventId": { "type": "string", "description": "Each-report rewards name their source. Absent on at-count bonuses." }, "milestoneReportReversed": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "valueCents": { "type": "number" }, "milestoneCount": { "type": "number", "description": "Milestone rewards: the person's reports of the milestone that count for this program now,\nthose at or after the referral minus reversed ones. Grizzlee updates it with every report,\nreversal, revocation and reinstatement for the person and milestone. Absent on rewards no\nmilestone event has touched since milestones were counted." }, "milestoneRevoked": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "Milestone rewards: true while the milestone is revoked for the person. Updated with\nmilestoneCount. Absent when not revoked, and on rewards no milestone event has touched since\nmilestones were counted." }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "customerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ] }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "expiresAt" ], "description": "Offer rewards only. Terms copied when earned. Later program edits leave them alone." }, "originalCents": { "type": "number", "description": "What the reward earned when it was created. Never changes." }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added to or removed from originalCents. Absent until the\norder is adjusted. The reward is worth originalCents + adjustedCents - reversedCents." }, "reversedCents": { "type": "number", "description": "Reversed by refunds, a rejection or a milestone revocation." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. With action review the\nreward started pending and waits for someone to approve or reject it, and automatic approval\nskips it. With action flagged it follows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. rules lists each rule ID with its signal types, never values.\nWith action review the reward started pending, waits for someone to approve or reject it, and\nautomatic approval skips it. With action flagged it follows the program's usual approval." }, "rejectedAt": { "type": "string", "description": "When someone rejected the pending reward. A rejected reward is reversed for good." }, "rejectionReason": { "type": "string", "description": "Why it was rejected, as entered." }, "statusBeforeReversal": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "approved" } ], "description": "Status the reward had when a refund fully reversed it. A later restoration returns it to this status." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Delivery mode when earned. Absent on older money rewards, which use the Grizzlee wallet. Absent on offer rewards. Readers ignore delivery for offers." }, "createdAt": { "type": "string" }, "availableAt": { "type": "string", "description": "Rewards no longer have a hold, so new rewards use createdAt. Older rewards keep their original date." }, "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" ] }, "programVersion": { "type": "number", "description": "The program version the reward was earned under. Absent on rewards earned before programs had\nversions. programSnapshot holds their rules either way." }, "historicalBasis": { "type": "string", "const": "total", "description": "Historical subtotal rewards keep their reporting-total basis for refunds and adjustments." }, "basisCents": { "type": "number" }, "explanation": { "type": "string" }, "explanationParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "explanation as codes. Absent on rewards earned before codes existed." }, "calculation": { "type": "object", "properties": { "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" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "Saved for fixed reward refunds. Older rewards default to prorate." }, "phaseAfterMonths": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "minValue": { "type": "number" }, "bonusBps": { "type": "number" }, "value": { "type": "number" } }, "required": [ "name", "minValue", "bonusBps", "value" ] }, "customTerms": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "string", "const": "partner" }, { "type": "string", "const": "customer" } ] }, "targetId": { "type": "string" } }, "required": [ "target", "targetId" ] }, "uncappedCents": { "type": "number" }, "customerCapCents": { "type": "number" }, "partnerCapCents": { "type": "number" } }, "required": [ "compensation", "uncappedCents" ] } }, "required": [ "id", "companyId", "programId", "partnerId", "customerId", "currency", "rewardType", "originalCents", "reversedCents", "status", "createdAt", "availableAt", "programSnapshot", "explanation" ] } }, "ledger": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "eventId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "earned" }, { "type": "string", "const": "refund" }, { "type": "string", "const": "restoration" }, { "type": "string", "const": "revocation" }, { "type": "string", "const": "reversal" }, { "type": "string", "const": "rejection" }, { "type": "string", "const": "adjustment" } ], "description": "earned is positive, refund is negative, and restoration is positive after a refund total goes\ndown. revocation is negative and reverses what remains of a milestone reward. reversal is\nnegative and reverses a milestone reward after a reversed report dropped the person's count\nbelow the reward's threshold. rejection is negative and reverses what remains of a pending\nreward someone rejected. adjustment is the signed change to the reward's value after an order\nadjustment." }, "amountCents": { "type": "number" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "eventId", "kind", "amountCents", "currency", "createdAt" ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "entityId": { "type": "string" }, "action": { "type": "string" }, "detail": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "entityId", "action", "detail", "createdAt" ] } }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "type": "string", "description": "New attempts require a reference. Older failures may have none." }, "amountCents": { "type": "number", "description": "Gross amount delivered, amount owed for a failure, or cash returned by a transfer reversal." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "deliveredAt": { "type": "string", "description": "Present when delivered." }, "failureReason": { "type": "string", "description": "Present when failed." }, "nettedDebtCents": { "type": "number", "description": "Present when a delivery settled part of the partner's earlier delivery debt." }, "payoutId": { "type": "string", "description": "Present when a paid merchant payout recorded this delivery." }, "reversalOfId": { "type": "string", "description": "Original delivery this append-only transfer reversal reduces." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "partnerId", "status", "amountCents", "currency", "rewardType", "createdAt" ] }, "description": "Delivery and transfer reversal history for the listed rewards, oldest first." }, "reservations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The placed order. Absent only on historical quote holds released by migration." }, "customerId": { "type": "string" }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "open" }, { "type": "string", "const": "consumed" }, { "type": "string", "const": "released" } ] }, "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] }, { "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ], "description": "Terms when the reservation was made. Later program edits leave them alone." }, "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ], "description": "Absent on historical friend holds." }, "rewardId": { "type": "string" }, "programVersion": { "type": "number", "description": "The program version the terms come from. Absent on reservations made before programs had versions." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "incentiveExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the offer itself stops applying. Earned holds keep the reward's offer expiry. Null when it never expires." }, "referredAt": { "type": "string", "description": "Earned holds use the reward's createdAt, when the offer was earned." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee expected for the order when it reserved." }, "newCustomer": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "The merchant's answer when this hold was made. Omitted, eligibility used recorded purchases." }, "baseCents": { "type": "number" }, "suggestedDiscountCents": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The categories the order sent when it reserved. The order's own categories are checked again when it completes." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "id", "companyId", "customerId", "programId", "partnerId", "status", "terms", "currency", "incentiveExpiresAt", "referredAt", "customerOrderNumber", "createdAt", "updatedAt" ] }, "description": "Open friend incentive holds, oldest first." }, "pagination": { "type": "object", "properties": { "number": { "type": "number" }, "size": { "type": "number" }, "hasNext": { "type": "boolean" }, "partnersHasNext": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "rewardsHasNext": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "partnerIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "number", "size", "hasNext", "partnerIds" ] }, "report": { "type": "object", "properties": { "rewardedOrders": { "type": "number" }, "reportedOrders": { "type": "number" }, "purchaseRevenueCents": { "type": "number" }, "earningsCents": { "type": "number" }, "pendingCents": { "type": "number" }, "activePartners": { "type": "number" }, "partnersTotal": { "type": "number" }, "rewardsTotal": { "type": "number" }, "filteredRewardsTotal": { "type": "number" }, "pendingRewards": { "type": "number" }, "heldRewards": { "type": "number", "description": "Pending rewards a self-referral match or fraud rule held for a person to approve or reject." }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "purchaseRevenueCents": { "type": "number" }, "unreportedOrders": { "type": "number" } }, "required": [ "day", "purchaseRevenueCents", "unreportedOrders" ] } }, "partners": { "type": "object", "properties": {}, "additionalProperties": { "type": "object", "properties": { "earningsCents": { "type": "number" }, "referredCustomers": { "type": "number" }, "rewardedOrders": { "type": "number" } }, "required": [ "earningsCents", "referredCustomers", "rewardedOrders" ] } }, "programs": { "type": "object", "properties": {}, "additionalProperties": { "type": "object", "properties": { "rewards": { "type": "number" } }, "required": [ "rewards" ] } }, "leaders": { "type": "array", "items": { "type": "object", "properties": { "partner": { "type": "object", "properties": { "name": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" } }, "required": [ "name", "id" ] }, "earningsCents": { "type": "number" }, "rewardedOrders": { "type": "number" } }, "required": [ "partner", "earningsCents", "rewardedOrders" ] } } }, "required": [ "rewardedOrders", "reportedOrders", "purchaseRevenueCents", "earningsCents", "pendingCents", "activePartners", "partnersTotal", "rewardsTotal", "pendingRewards", "daily", "partners", "programs" ] }, "usage": { "type": "object", "properties": { "rewardedTransactions": { "type": "number", "description": "Rewarded orders plus rewarded milestone reports recorded this month." }, "rewardedMilestones": { "type": "number", "description": "The part of rewardedTransactions that came from milestone reports." }, "estimatedFeeUsd": { "type": "string" }, "month": { "type": "string" } }, "required": [ "rewardedTransactions", "estimatedFeeUsd", "month" ] } }, "required": [ "company", "programs", "partners", "attributions", "orders", "rewards", "ledger", "audit", "usage" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "languages": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ] }, "description": "Languages partners and customers see, in order. The first is the default. Companies saved\nbefore languages existed have none, which means English only. See companyLanguages." }, "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" } ] } }, "required": [ "cash", "credit" ], "description": "Who delivers approved cash and store credit rewards for programs created from the dashboard.\nAbsent means the Grizzlee wallet for both. Programs keep their own delivery. This is only the\ndefault a new program starts with." }, "partnerFields": { "type": "array", "items": { "type": "object", "properties": { "type": { "anyOf": [ { "type": "string", "const": "number" }, { "type": "string", "const": "boolean" }, { "type": "string", "const": "text" }, { "type": "string", "const": "select" } ] }, "name": { "type": "string" }, "id": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "name", "id" ] } } }, "required": [ "id", "name", "currency" ] }, "programs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "createdAt": { "type": "string" }, "version": { "type": "number", "description": "1 when created. Every saved change except a rename adds 1. Rewards and incentive reservations\nrecord the version they were made under." }, "updatedAt": { "type": "string", "description": "Last saved change, including renames." }, "archivedAt": { "type": "string", "description": "When deleteProgram archived the program because it has history. An archived program stays\ninactive, has no placement keys and refuses changes. Its referrals, rewards and versions stay." }, "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": [ "id", "companyId", "createdAt", "version", "updatedAt", "currency", "name", "kind", "rewardType", "attributionWindowDays", "active" ] } }, "placements": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } }, "programVersions": { "type": "array", "items": { "type": "object", "properties": { "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": [ "companyId", "programId", "version", "programSnapshot", "changedFields", "createdAt" ] }, "description": "Every saved version of the listed programs, oldest first." }, "programPages": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "programId", "destination" ] } }, "partners": { "type": "array", "items": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } }, "attributions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "qualifiedAt": { "type": "string" }, "qualifiedOrderNumber": { "type": "number" }, "programId": { "type": "string" }, "referralCode": { "type": "string" }, "customerId": { "type": "string" }, "occurredAt": { "type": "string" }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "providerPromoCodeId": { "type": "string" }, "customerDisplayName": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "referralCode", "customerId", "occurredAt", "channel" ] } }, "orders": { "type": "array", "items": { "type": "object", "properties": { "companyId": { "type": "string" }, "customerOrderNumber": { "type": "number", "description": "Grizzlee's count of the customer's purchases, including this one. Never renumbered." }, "reportedCustomerOrderNumber": { "type": "number", "description": "The merchant's customerOrderNumber when it disagreed with Grizzlee's." }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] } }, "rewarded": { "type": "boolean" }, "refundedTotalCents": { "type": "number" }, "refundedCommissionableCents": { "type": "number" }, "fullyRefunded": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "lastRefundAt": { "type": "string", "description": "occurredAt of the latest refund event applied to this order. Older refund events are ignored." }, "incentiveFlag": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "const": "no_reservation" }, { "type": "string", "const": "reservation_expired" }, { "type": "string", "const": "reservation_released" }, { "type": "string", "const": "reservation_consumed" }, { "type": "string", "const": "reservation_locked" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "exceeds_terms" }, { "type": "string", "const": "category_not_eligible" } ] }, "rewardId": { "type": "string" }, "programId": { "type": "string", "description": "Program of the reservation or referral checked. Absent for no_referral." }, "reservationId": { "type": "string", "description": "The reservation sent with the order, when there was one." }, "maxCents": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Largest discount the terms allow on one order. Null when they set no cap or there are no terms." }, "reportedCents": { "type": "number", "description": "incentiveAppliedCents as the merchant reported it." } }, "required": [ "reason", "maxCents", "reportedCents" ], "description": "Present when incentiveAppliedCents did not match the referral's friend incentive." }, "adjustedTotalCents": { "type": "number", "description": "The reporting total after the latest adjustment. totalCents keeps the completed value." }, "adjustedCommissionableCents": { "type": "number", "description": "The commissionable amount after the latest adjustment. commissionableCents keeps the completed value." }, "lastAdjustedAt": { "type": "string", "description": "occurredAt of the latest adjustment applied to this order. Older adjustments are ignored." }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "eventId": { "type": "string" }, "totalCents": { "type": "number" }, "previousTotalCents": { "type": "number" }, "commissionableCents": { "type": "number" }, "previousCommissionableCents": { "type": "number" }, "reason": { "type": "string" }, "occurredAt": { "type": "string" }, "rewardChangeCents": { "type": "number", "description": "Signed change to the value of the order's rewards." } }, "required": [ "eventId", "occurredAt", "rewardChangeCents" ] }, "description": "Every applied adjustment, oldest first." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] }, "type": { "type": "string", "const": "order.completed" }, "customerId": { "type": "string" }, "orderId": { "type": "string" }, "occurredAt": { "type": "string" }, "eventId": { "type": "string" }, "commissionableCents": { "type": "number", "description": "Merchant-selected amount for percentage rewards and fixed-reward refund proration." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "customerDisplayName": { "type": "string" }, "newCustomer": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "The merchant's answer from its own order history. Omitted, Grizzlee uses recorded purchases." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The order's categories, such as its product or service types. Programs and friend incentives\ncan include or exclude them. Lowercased, sorted and deduplicated. An order without them\nstill counts as a purchase." }, "totalCents": { "type": "number", "description": "What the customer paid. Used only for reporting." }, "customerEmail": { "type": "string" }, "incentiveAppliedCents": { "type": "number", "description": "Friend incentive discount the merchant's checkout applied to this order. Merchant servers\nonly. Grizzlee stores it as reported and flags the order when it does not match the terms\nof the reservation sent with it. It never rejects the order over it." } }, "required": [ "companyId", "customerOrderNumber", "decisions", "rewarded", "refundedTotalCents", "refundedCommissionableCents", "type", "customerId", "orderId", "occurredAt", "eventId", "commissionableCents", "currency" ] } }, "rewards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The order that earned the reward. Absent on milestone rewards." }, "milestone": { "type": "string", "description": "The milestone that earned the reward. Absent on order rewards. Exactly one of the two is set." }, "reportEventId": { "type": "string", "description": "Each-report rewards name their source. Absent on at-count bonuses." }, "milestoneReportReversed": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "valueCents": { "type": "number" }, "milestoneCount": { "type": "number", "description": "Milestone rewards: the person's reports of the milestone that count for this program now,\nthose at or after the referral minus reversed ones. Grizzlee updates it with every report,\nreversal, revocation and reinstatement for the person and milestone. Absent on rewards no\nmilestone event has touched since milestones were counted." }, "milestoneRevoked": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "Milestone rewards: true while the milestone is revoked for the person. Updated with\nmilestoneCount. Absent when not revoked, and on rewards no milestone event has touched since\nmilestones were counted." }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "customerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ] }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "expiresAt" ], "description": "Offer rewards only. Terms copied when earned. Later program edits leave them alone." }, "originalCents": { "type": "number", "description": "What the reward earned when it was created. Never changes." }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added to or removed from originalCents. Absent until the\norder is adjusted. The reward is worth originalCents + adjustedCents - reversedCents." }, "reversedCents": { "type": "number", "description": "Reversed by refunds, a rejection or a milestone revocation." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. With action review the\nreward started pending and waits for someone to approve or reject it, and automatic approval\nskips it. With action flagged it follows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. rules lists each rule ID with its signal types, never values.\nWith action review the reward started pending, waits for someone to approve or reject it, and\nautomatic approval skips it. With action flagged it follows the program's usual approval." }, "rejectedAt": { "type": "string", "description": "When someone rejected the pending reward. A rejected reward is reversed for good." }, "rejectionReason": { "type": "string", "description": "Why it was rejected, as entered." }, "statusBeforeReversal": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "approved" } ], "description": "Status the reward had when a refund fully reversed it. A later restoration returns it to this status." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Delivery mode when earned. Absent on older money rewards, which use the Grizzlee wallet. Absent on offer rewards. Readers ignore delivery for offers." }, "createdAt": { "type": "string" }, "availableAt": { "type": "string", "description": "Rewards no longer have a hold, so new rewards use createdAt. Older rewards keep their original date." }, "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" ] }, "programVersion": { "type": "number", "description": "The program version the reward was earned under. Absent on rewards earned before programs had\nversions. programSnapshot holds their rules either way." }, "historicalBasis": { "type": "string", "const": "total", "description": "Historical subtotal rewards keep their reporting-total basis for refunds and adjustments." }, "basisCents": { "type": "number" }, "explanation": { "type": "string" }, "explanationParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "explanation as codes. Absent on rewards earned before codes existed." }, "calculation": { "type": "object", "properties": { "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" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "Saved for fixed reward refunds. Older rewards default to prorate." }, "phaseAfterMonths": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "minValue": { "type": "number" }, "bonusBps": { "type": "number" }, "value": { "type": "number" } }, "required": [ "name", "minValue", "bonusBps", "value" ] }, "customTerms": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "string", "const": "partner" }, { "type": "string", "const": "customer" } ] }, "targetId": { "type": "string" } }, "required": [ "target", "targetId" ] }, "uncappedCents": { "type": "number" }, "customerCapCents": { "type": "number" }, "partnerCapCents": { "type": "number" } }, "required": [ "compensation", "uncappedCents" ] } }, "required": [ "id", "companyId", "programId", "partnerId", "customerId", "currency", "rewardType", "originalCents", "reversedCents", "status", "createdAt", "availableAt", "programSnapshot", "explanation" ] } }, "ledger": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "eventId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "earned" }, { "type": "string", "const": "refund" }, { "type": "string", "const": "restoration" }, { "type": "string", "const": "revocation" }, { "type": "string", "const": "reversal" }, { "type": "string", "const": "rejection" }, { "type": "string", "const": "adjustment" } ], "description": "earned is positive, refund is negative, and restoration is positive after a refund total goes\ndown. revocation is negative and reverses what remains of a milestone reward. reversal is\nnegative and reverses a milestone reward after a reversed report dropped the person's count\nbelow the reward's threshold. rejection is negative and reverses what remains of a pending\nreward someone rejected. adjustment is the signed change to the reward's value after an order\nadjustment." }, "amountCents": { "type": "number" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "eventId", "kind", "amountCents", "currency", "createdAt" ] } }, "audit": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "entityId": { "type": "string" }, "action": { "type": "string" }, "detail": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "entityId", "action", "detail", "createdAt" ] } }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "type": "string", "description": "New attempts require a reference. Older failures may have none." }, "amountCents": { "type": "number", "description": "Gross amount delivered, amount owed for a failure, or cash returned by a transfer reversal." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "deliveredAt": { "type": "string", "description": "Present when delivered." }, "failureReason": { "type": "string", "description": "Present when failed." }, "nettedDebtCents": { "type": "number", "description": "Present when a delivery settled part of the partner's earlier delivery debt." }, "payoutId": { "type": "string", "description": "Present when a paid merchant payout recorded this delivery." }, "reversalOfId": { "type": "string", "description": "Original delivery this append-only transfer reversal reduces." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "partnerId", "status", "amountCents", "currency", "rewardType", "createdAt" ] }, "description": "Delivery and transfer reversal history for the listed rewards, oldest first." }, "reservations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The placed order. Absent only on historical quote holds released by migration." }, "customerId": { "type": "string" }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "open" }, { "type": "string", "const": "consumed" }, { "type": "string", "const": "released" } ] }, "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] }, { "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ], "description": "Terms when the reservation was made. Later program edits leave them alone." }, "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ], "description": "Absent on historical friend holds." }, "rewardId": { "type": "string" }, "programVersion": { "type": "number", "description": "The program version the terms come from. Absent on reservations made before programs had versions." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "incentiveExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the offer itself stops applying. Earned holds keep the reward's offer expiry. Null when it never expires." }, "referredAt": { "type": "string", "description": "Earned holds use the reward's createdAt, when the offer was earned." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee expected for the order when it reserved." }, "newCustomer": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "The merchant's answer when this hold was made. Omitted, eligibility used recorded purchases." }, "baseCents": { "type": "number" }, "suggestedDiscountCents": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The categories the order sent when it reserved. The order's own categories are checked again when it completes." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "id", "companyId", "customerId", "programId", "partnerId", "status", "terms", "currency", "incentiveExpiresAt", "referredAt", "customerOrderNumber", "createdAt", "updatedAt" ] }, "description": "Open friend incentive holds, oldest first." }, "pagination": { "type": "object", "properties": { "number": { "type": "number" }, "size": { "type": "number" }, "hasNext": { "type": "boolean" }, "partnersHasNext": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "rewardsHasNext": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "partnerIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "number", "size", "hasNext", "partnerIds" ] }, "report": { "type": "object", "properties": { "rewardedOrders": { "type": "number" }, "reportedOrders": { "type": "number" }, "purchaseRevenueCents": { "type": "number" }, "earningsCents": { "type": "number" }, "pendingCents": { "type": "number" }, "activePartners": { "type": "number" }, "partnersTotal": { "type": "number" }, "rewardsTotal": { "type": "number" }, "filteredRewardsTotal": { "type": "number" }, "pendingRewards": { "type": "number" }, "heldRewards": { "type": "number", "description": "Pending rewards a self-referral match or fraud rule held for a person to approve or reject." }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "purchaseRevenueCents": { "type": "number" }, "unreportedOrders": { "type": "number" } }, "required": [ "day", "purchaseRevenueCents", "unreportedOrders" ] } }, "partners": { "type": "object", "properties": {}, "additionalProperties": { "type": "object", "properties": { "earningsCents": { "type": "number" }, "referredCustomers": { "type": "number" }, "rewardedOrders": { "type": "number" } }, "required": [ "earningsCents", "referredCustomers", "rewardedOrders" ] } }, "programs": { "type": "object", "properties": {}, "additionalProperties": { "type": "object", "properties": { "rewards": { "type": "number" } }, "required": [ "rewards" ] } }, "leaders": { "type": "array", "items": { "type": "object", "properties": { "partner": { "type": "object", "properties": { "name": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" } }, "required": [ "name", "id" ] }, "earningsCents": { "type": "number" }, "rewardedOrders": { "type": "number" } }, "required": [ "partner", "earningsCents", "rewardedOrders" ] } } }, "required": [ "rewardedOrders", "reportedOrders", "purchaseRevenueCents", "earningsCents", "pendingCents", "activePartners", "partnersTotal", "rewardsTotal", "pendingRewards", "daily", "partners", "programs" ] }, "usage": { "type": "object", "properties": { "rewardedTransactions": { "type": "number", "description": "Rewarded orders plus rewarded milestone reports recorded this month." }, "rewardedMilestones": { "type": "number", "description": "The part of rewardedTransactions that came from milestone reports." }, "estimatedFeeUsd": { "type": "string" }, "month": { "type": "string" } }, "required": [ "rewardedTransactions", "estimatedFeeUsd", "month" ] } }, "required": [ "company", "programs", "partners", "attributions", "orders", "rewards", "ledger", "audit", "usage" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/placements": { "get": { "operationId": "listPlacements", "summary": "listPlacements", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/placements/{key}": { "get": { "operationId": "getPlacement", "summary": "getPlacement", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "put": { "operationId": "setPlacement", "summary": "Points key at a program, creating the key if needed. Needs programs:write.", "description": "Creates the key or moves it to another program. The program's version does not change.", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "programs:write" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "programId" ], "additionalProperties": false }, "example": { "programId": "program-example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "delete": { "operationId": "deletePlacement", "summary": "Removes the key and returns the mapping it had. Needs programs:write.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "programs:write" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "key": { "type": "string" }, "programId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "key", "programId", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/programs": { "post": { "operationId": "createProgram", "summary": "createProgram", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "programs:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "kind": { "type": "string", "enum": [ "referral", "affiliate", "both" ] }, "tracking": { "type": "object", "properties": { "links": { "type": "boolean", "default": true }, "qrCodes": { "type": "boolean", "default": true }, "attributionCodes": { "type": "boolean", "default": true }, "providerPromoCodes": { "type": "boolean", "default": false } }, "additionalProperties": false, "default": {} }, "currency": { "type": "string", "enum": [ "CAD", "USD", "EUR", "GBP" ] }, "destinationUrl": { "type": "string", "maxLength": 2000, "format": "uri" }, "display": { "type": "object", "properties": { "en": { "type": "object", "properties": { "publicName": { "type": "string", "minLength": 1, "maxLength": 100 }, "headline": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestoneLabel": { "type": "object", "properties": { "one": { "type": "string", "minLength": 1, "maxLength": 40 }, "other": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "one", "other" ], "additionalProperties": false } }, "additionalProperties": false }, "fr-CA": { "type": "object", "properties": { "publicName": { "type": "string", "minLength": 1, "maxLength": 100 }, "headline": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestoneLabel": { "type": "object", "properties": { "one": { "type": "string", "minLength": 1, "maxLength": 40 }, "other": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "one", "other" ], "additionalProperties": false } }, "additionalProperties": false }, "hy": { "type": "object", "properties": { "publicName": { "type": "string", "minLength": 1, "maxLength": 100 }, "headline": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestoneLabel": { "type": "object", "properties": { "one": { "type": "string", "minLength": 1, "maxLength": 40 }, "other": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "one", "other" ], "additionalProperties": false } }, "additionalProperties": false }, "ru": { "type": "object", "properties": { "publicName": { "type": "string", "minLength": 1, "maxLength": 100 }, "headline": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestoneLabel": { "type": "object", "properties": { "one": { "type": "string", "minLength": 1, "maxLength": 40 }, "other": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "one", "other" ], "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,79}$" } }, "required": [ "type", "milestone" ], "additionalProperties": false } ], "default": { "type": "order" } }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "integer", "minimum": 1, "maximum": 1200 }, "rateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "afterMonths", "rateBps" ], "additionalProperties": false }, "minItems": 1, "maxItems": 12 } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "type", "rateBps" ], "additionalProperties": false } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "compensation" ], "additionalProperties": false }, "atCount": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 10000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "count", "amountCents" ], "additionalProperties": false } }, "additionalProperties": false }, "fixedRefundMode": { "type": "string", "enum": [ "prorate", "full_refund_only" ], "default": "prorate" }, "duration": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "only_order" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_order" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_n_orders" }, "count": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "type", "count" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "days" }, "days": { "type": "integer", "minimum": 1, "maximum": 36500 } }, "required": [ "type", "days" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "months" }, "months": { "type": "integer", "minimum": 1, "maximum": 1200 } }, "required": [ "type", "months" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime" } }, "required": [ "type" ], "additionalProperties": false } ] }, "rewardType": { "type": "string", "enum": [ "cash", "credit", "offer" ] }, "delivery": { "type": "object", "properties": { "cash": { "type": "string", "enum": [ "grizzlee_wallet", "merchant" ], "default": "grizzlee_wallet" }, "credit": { "type": "string", "enum": [ "grizzlee_wallet", "merchant" ], "default": "grizzlee_wallet" } }, "additionalProperties": false, "default": {} }, "attributionWindowDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "reviewRewards": { "type": "boolean" }, "fraudChecks": { "type": "object", "properties": { "selfReferral": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block", "review", "flag", "off" ], "default": "block" } }, "additionalProperties": false, "default": {} }, "duplicateAccounts": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block", "review", "flag", "off" ], "default": "flag" }, "accounts": { "type": "integer", "minimum": 2, "maximum": 200, "default": 3 }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 }, "ipAccounts": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 200 }, { "type": "null" } ], "default": null } }, "additionalProperties": false, "default": {} }, "rapidRepeats": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block", "review", "flag", "off" ], "default": "flag" }, "referrals": { "type": "integer", "minimum": 2, "maximum": 200, "default": 3 }, "windowMinutes": { "type": "integer", "minimum": 1, "maximum": 10080, "default": 60 }, "ipReferrals": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 200 }, { "type": "null" } ], "default": null } }, "additionalProperties": false, "default": {} }, "repeatCustomer": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block", "review", "flag", "off" ], "default": "flag" } }, "additionalProperties": false, "default": {} }, "disposableEmail": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "review", "flag", "off" ], "default": "flag" } }, "additionalProperties": false, "default": {} } }, "additionalProperties": false }, "active": { "type": "boolean" }, "performance": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "new_customers", "orders" ] }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "minValue": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "bonusBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "name", "minValue", "bonusBps" ], "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "metric", "tiers" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "customerCapCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "partnerCapCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "additionalProperties": false }, "customTerms": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "target": { "type": "string", "const": "partner" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 120 }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "integer", "minimum": 1, "maximum": 1200 }, "rateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "afterMonths", "rateBps" ], "additionalProperties": false }, "minItems": 1, "maxItems": 12 } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "type", "rateBps" ], "additionalProperties": false } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "compensation" ], "additionalProperties": false }, "atCount": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 10000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "count", "amountCents" ], "additionalProperties": false } }, "additionalProperties": false }, "customerCapCents": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, { "type": "null" } ] }, "partnerCapCents": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, { "type": "null" } ] } }, "required": [ "target", "targetId" ], "additionalProperties": false }, { "type": "object", "properties": { "target": { "type": "string", "const": "customer" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 120 }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "integer", "minimum": 1, "maximum": 1200 }, "rateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "afterMonths", "rateBps" ], "additionalProperties": false }, "minItems": 1, "maxItems": 12 } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "type", "rateBps" ], "additionalProperties": false } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "compensation" ], "additionalProperties": false }, "atCount": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 10000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "count", "amountCents" ], "additionalProperties": false } }, "additionalProperties": false }, "customerCapCents": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, { "type": "null" } ] } }, "required": [ "target", "targetId" ], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 100 }, "friendIncentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDiscountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "minOrderCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "orders": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "newCustomersOnly": { "type": "boolean", "default": true }, "expiresAfterDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ], "default": null }, "returnOnFullRefund": { "type": "boolean", "default": false }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "minOrderCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "orders": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "newCustomersOnly": { "type": "boolean", "default": true }, "expiresAfterDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ], "default": null }, "returnOnFullRefund": { "type": "boolean", "default": false }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, "partnerOffer": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDiscountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "minOrderCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "orders": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "expiresAfterDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ], "default": null }, "returnOnFullRefund": { "type": "boolean", "default": false }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "minOrderCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "orders": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "expiresAfterDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ], "default": null }, "returnOnFullRefund": { "type": "boolean", "default": false }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false } }, "required": [ "name", "kind", "rewardType", "attributionWindowDays", "active" ], "additionalProperties": false }, "example": { "name": "Example referral program", "kind": "referral", "trigger": { "type": "order" }, "rewardType": "cash", "attributionWindowDays": 1, "active": true, "compensation": { "type": "fixed", "amountCents": 1000 }, "duration": { "type": "first_order" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "createdAt": { "type": "string" }, "version": { "type": "number", "description": "1 when created. Every saved change except a rename adds 1. Rewards and incentive reservations\nrecord the version they were made under." }, "updatedAt": { "type": "string", "description": "Last saved change, including renames." }, "archivedAt": { "type": "string", "description": "When deleteProgram archived the program because it has history. An archived program stays\ninactive, has no placement keys and refuses changes. Its referrals, rewards and versions stay." }, "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": [ "id", "companyId", "createdAt", "version", "updatedAt", "currency", "name", "kind", "rewardType", "attributionWindowDays", "active" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "createdAt": { "type": "string" }, "version": { "type": "number", "description": "1 when created. Every saved change except a rename adds 1. Rewards and incentive reservations\nrecord the version they were made under." }, "updatedAt": { "type": "string", "description": "Last saved change, including renames." }, "archivedAt": { "type": "string", "description": "When deleteProgram archived the program because it has history. An archived program stays\ninactive, has no placement keys and refuses changes. Its referrals, rewards and versions stay." }, "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": [ "id", "companyId", "createdAt", "version", "updatedAt", "currency", "name", "kind", "rewardType", "attributionWindowDays", "active" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/programs/{id}": { "put": { "operationId": "updateProgram", "summary": "updateProgram", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "programs:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "kind": { "type": "string", "enum": [ "referral", "affiliate", "both" ] }, "tracking": { "type": "object", "properties": { "links": { "type": "boolean", "default": true }, "qrCodes": { "type": "boolean", "default": true }, "attributionCodes": { "type": "boolean", "default": true }, "providerPromoCodes": { "type": "boolean", "default": false } }, "additionalProperties": false }, "currency": { "type": "string", "enum": [ "CAD", "USD", "EUR", "GBP" ] }, "destinationUrl": { "anyOf": [ { "type": "string", "maxLength": 2000, "format": "uri" }, { "type": "null" } ] }, "display": { "anyOf": [ { "type": "object", "properties": { "en": { "type": "object", "properties": { "publicName": { "type": "string", "minLength": 1, "maxLength": 100 }, "headline": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestoneLabel": { "type": "object", "properties": { "one": { "type": "string", "minLength": 1, "maxLength": 40 }, "other": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "one", "other" ], "additionalProperties": false } }, "additionalProperties": false }, "fr-CA": { "type": "object", "properties": { "publicName": { "type": "string", "minLength": 1, "maxLength": 100 }, "headline": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestoneLabel": { "type": "object", "properties": { "one": { "type": "string", "minLength": 1, "maxLength": 40 }, "other": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "one", "other" ], "additionalProperties": false } }, "additionalProperties": false }, "hy": { "type": "object", "properties": { "publicName": { "type": "string", "minLength": 1, "maxLength": 100 }, "headline": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestoneLabel": { "type": "object", "properties": { "one": { "type": "string", "minLength": 1, "maxLength": 40 }, "other": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "one", "other" ], "additionalProperties": false } }, "additionalProperties": false }, "ru": { "type": "object", "properties": { "publicName": { "type": "string", "minLength": 1, "maxLength": 100 }, "headline": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestoneLabel": { "type": "object", "properties": { "one": { "type": "string", "minLength": 1, "maxLength": 40 }, "other": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "one", "other" ], "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, { "type": "null" } ] }, "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,79}$" } }, "required": [ "type", "milestone" ], "additionalProperties": false } ] }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "integer", "minimum": 1, "maximum": 1200 }, "rateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "afterMonths", "rateBps" ], "additionalProperties": false }, "minItems": 1, "maxItems": 12 } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "type", "rateBps" ], "additionalProperties": false } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "compensation" ], "additionalProperties": false }, "atCount": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 10000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "count", "amountCents" ], "additionalProperties": false } }, "additionalProperties": false }, "fixedRefundMode": { "type": "string", "enum": [ "prorate", "full_refund_only" ] }, "duration": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "only_order" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_order" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_n_orders" }, "count": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "type", "count" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "days" }, "days": { "type": "integer", "minimum": 1, "maximum": 36500 } }, "required": [ "type", "days" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "months" }, "months": { "type": "integer", "minimum": 1, "maximum": 1200 } }, "required": [ "type", "months" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime" } }, "required": [ "type" ], "additionalProperties": false } ] }, "rewardType": { "type": "string", "enum": [ "cash", "credit", "offer" ] }, "delivery": { "type": "object", "properties": { "cash": { "type": "string", "enum": [ "grizzlee_wallet", "merchant" ], "default": "grizzlee_wallet" }, "credit": { "type": "string", "enum": [ "grizzlee_wallet", "merchant" ], "default": "grizzlee_wallet" } }, "additionalProperties": false }, "attributionWindowDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "reviewRewards": { "type": "boolean" }, "fraudChecks": { "type": "object", "properties": { "selfReferral": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block", "review", "flag", "off" ], "default": "block" } }, "additionalProperties": false, "default": {} }, "duplicateAccounts": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block", "review", "flag", "off" ], "default": "flag" }, "accounts": { "type": "integer", "minimum": 2, "maximum": 200, "default": 3 }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30 }, "ipAccounts": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 200 }, { "type": "null" } ], "default": null } }, "additionalProperties": false, "default": {} }, "rapidRepeats": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block", "review", "flag", "off" ], "default": "flag" }, "referrals": { "type": "integer", "minimum": 2, "maximum": 200, "default": 3 }, "windowMinutes": { "type": "integer", "minimum": 1, "maximum": 10080, "default": 60 }, "ipReferrals": { "anyOf": [ { "type": "integer", "minimum": 2, "maximum": 200 }, { "type": "null" } ], "default": null } }, "additionalProperties": false, "default": {} }, "repeatCustomer": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block", "review", "flag", "off" ], "default": "flag" } }, "additionalProperties": false, "default": {} }, "disposableEmail": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "review", "flag", "off" ], "default": "flag" } }, "additionalProperties": false, "default": {} } }, "additionalProperties": false }, "active": { "type": "boolean" }, "performance": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "new_customers", "orders" ] }, "windowDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 40 }, "minValue": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "bonusBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "name", "minValue", "bonusBps" ], "additionalProperties": false }, "minItems": 1, "maxItems": 10 } }, "required": [ "metric", "tiers" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "customerCapCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "partnerCapCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "additionalProperties": false }, "customTerms": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "target": { "type": "string", "const": "partner" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 120 }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "integer", "minimum": 1, "maximum": 1200 }, "rateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "afterMonths", "rateBps" ], "additionalProperties": false }, "minItems": 1, "maxItems": 12 } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "type", "rateBps" ], "additionalProperties": false } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "compensation" ], "additionalProperties": false }, "atCount": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 10000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "count", "amountCents" ], "additionalProperties": false } }, "additionalProperties": false }, "customerCapCents": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, { "type": "null" } ] }, "partnerCapCents": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, { "type": "null" } ] } }, "required": [ "target", "targetId" ], "additionalProperties": false }, { "type": "object", "properties": { "target": { "type": "string", "const": "customer" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 120 }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "integer", "minimum": 1, "maximum": 1200 }, "rateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "afterMonths", "rateBps" ], "additionalProperties": false }, "minItems": 1, "maxItems": 12 } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "type", "amountCents" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "type", "rateBps" ], "additionalProperties": false } ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "compensation" ], "additionalProperties": false }, "atCount": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 10000 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "count", "amountCents" ], "additionalProperties": false } }, "additionalProperties": false }, "customerCapCents": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, { "type": "null" } ] } }, "required": [ "target", "targetId" ], "additionalProperties": false } ] }, "minItems": 1, "maxItems": 100 }, "friendIncentive": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDiscountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "minOrderCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "orders": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "newCustomersOnly": { "type": "boolean", "default": true }, "expiresAfterDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ], "default": null }, "returnOnFullRefund": { "type": "boolean", "default": false }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "minOrderCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "orders": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "newCustomersOnly": { "type": "boolean", "default": true }, "expiresAfterDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ], "default": null }, "returnOnFullRefund": { "type": "boolean", "default": false }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "partnerOffer": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "integer", "minimum": 1, "maximum": 10000 }, "maxDiscountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "minOrderCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "orders": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "expiresAfterDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ], "default": null }, "returnOnFullRefund": { "type": "boolean", "default": false }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false } }, "required": [ "type", "rateBps" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "minOrderCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "orders": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 1 }, "expiresAfterDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ], "default": null }, "returnOnFullRefund": { "type": "boolean", "default": false }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false } }, "required": [ "type", "amountCents" ], "additionalProperties": false } ] }, "orderCategories": { "anyOf": [ { "type": "object", "properties": { "include": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 }, "exclude": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "minItems": 1, "maxItems": 50 } }, "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "name", "kind", "rewardType", "attributionWindowDays", "active" ], "additionalProperties": false }, "example": { "name": "Example referral program", "kind": "referral", "trigger": { "type": "order" }, "rewardType": "cash", "attributionWindowDays": 1, "active": true, "compensation": { "type": "fixed", "amountCents": 1000 }, "duration": { "type": "first_order" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "createdAt": { "type": "string" }, "version": { "type": "number", "description": "1 when created. Every saved change except a rename adds 1. Rewards and incentive reservations\nrecord the version they were made under." }, "updatedAt": { "type": "string", "description": "Last saved change, including renames." }, "archivedAt": { "type": "string", "description": "When deleteProgram archived the program because it has history. An archived program stays\ninactive, has no placement keys and refuses changes. Its referrals, rewards and versions stay." }, "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": [ "id", "companyId", "createdAt", "version", "updatedAt", "currency", "name", "kind", "rewardType", "attributionWindowDays", "active" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "createdAt": { "type": "string" }, "version": { "type": "number", "description": "1 when created. Every saved change except a rename adds 1. Rewards and incentive reservations\nrecord the version they were made under." }, "updatedAt": { "type": "string", "description": "Last saved change, including renames." }, "archivedAt": { "type": "string", "description": "When deleteProgram archived the program because it has history. An archived program stays\ninactive, has no placement keys and refuses changes. Its referrals, rewards and versions stay." }, "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": [ "id", "companyId", "createdAt", "version", "updatedAt", "currency", "name", "kind", "rewardType", "attributionWindowDays", "active" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "delete": { "operationId": "deleteProgram", "summary": "Deletes a program with no referrals, rewards or other history. A program with history is\narchived instead: paused, stripped of its placement keys and kept. The result says which.", "description": "A program with referrals, rewards or other history is archived instead: paused, hidden, stripped of its placement keys and kept. The result says which happened.", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "programs:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "result": { "anyOf": [ { "type": "string", "const": "deleted" }, { "type": "string", "const": "archived" } ] } }, "required": [ "id", "result" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "result": { "anyOf": [ { "type": "string", "const": "deleted" }, { "type": "string", "const": "archived" } ] } }, "required": [ "id", "result" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/programs/{programId}/versions": { "get": { "operationId": "listProgramVersions", "summary": "Every saved version of a program, newest first, with readable terms.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "versions": { "type": "array", "items": { "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" ] } } }, "required": [ "versions" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "versions": { "type": "array", "items": { "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" ] } } }, "required": [ "versions" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/programs/{programId}/versions/": { "get": { "operationId": "getProgramVersion", "summary": "One saved version of a program, such as the one in reward.programVersion.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "programId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "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" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "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" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners": { "post": { "operationId": "registerPartner", "summary": "registerPartner", "description": "Setting stripeAccountId also requires payouts:write. Keys without payouts:write receive a partner without stripeAccountId.", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "programIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "addProgramIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "removeProgramIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 }, "maxItems": 10 }, "properties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number", "minimum": -1000000000000, "maximum": 1000000000000 }, { "type": "boolean" } ] } }, "stripeAccountId": { "anyOf": [ { "type": "string", "maxLength": 255, "pattern": "^acct_[A-Za-z0-9]+$" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string", "enum": [ "en", "fr-CA", "hy", "ru" ] }, { "type": "null" } ] }, "signals": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 40 }, "phoneHash": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, "paymentFingerprint": { "type": "string", "minLength": 1, "maxLength": 255 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ipAddress": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "externalId", "name", "email" ], "additionalProperties": false }, "example": { "externalId": "merchant-partner-001", "customerIds": [ "customer-example" ], "name": "Example referral program", "email": "partner@example.com" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}": { "get": { "operationId": "getPartnerByExternalId", "summary": "getPartnerByExternalId", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "put": { "operationId": "updatePartnerByExternalId", "summary": "updatePartnerByExternalId", "description": "Send at least one update or signals. Setting stripeAccountId also requires payouts:write.", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "programIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "addProgramIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "removeProgramIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 }, "maxItems": 10 }, "properties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number", "minimum": -1000000000000, "maximum": 1000000000000 }, { "type": "boolean" } ] } }, "stripeAccountId": { "anyOf": [ { "type": "string", "maxLength": 255, "pattern": "^acct_[A-Za-z0-9]+$" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string", "enum": [ "en", "fr-CA", "hy", "ru" ] }, { "type": "null" } ] }, "active": { "type": "boolean" }, "signals": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 40 }, "phoneHash": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, "paymentFingerprint": { "type": "string", "minLength": 1, "maxLength": 255 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ipAddress": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "customerIds": [ "customer-example" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/{id}": { "put": { "operationId": "updatePartner", "summary": "updatePartner", "description": "Send at least one update or signals. Setting stripeAccountId also requires payouts:write.", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "programIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "addProgramIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "removeProgramIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "maxItems": 100 }, "labels": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 }, "maxItems": 10 }, "properties": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number", "minimum": -1000000000000, "maximum": 1000000000000 }, { "type": "boolean" } ] } }, "stripeAccountId": { "anyOf": [ { "type": "string", "maxLength": 255, "pattern": "^acct_[A-Za-z0-9]+$" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string", "enum": [ "en", "fr-CA", "hy", "ru" ] }, { "type": "null" } ] }, "active": { "type": "boolean" }, "signals": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 40 }, "phoneHash": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, "paymentFingerprint": { "type": "string", "minLength": 1, "maxLength": 255 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ipAddress": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "additionalProperties": false }, "example": { "customerIds": [ "customer-example" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "programIds": { "type": "array", "items": { "type": "string" } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "referralCode": { "type": "string" }, "alias": { "type": "string", "description": "The partner's short code, such as KARL7Q. Unique in the company and accepted wherever\nreferralCode is, in any case. It never changes after creation, except that erasure replaces it\nwith the uppercase referralCode." }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the merchant erased the partner's personal data. An erased partner is named\nERASED_PARTNER_NAME, has an empty email and no customer links, labels or properties. It stays\ninactive and its external ID cannot be registered again." }, "email": { "type": "string" }, "name": { "type": "string" }, "externalId": { "type": "string" }, "customerIds": { "type": "array", "items": { "type": "string" }, "description": "Merchant customer IDs belonging to this partner. Supplied lists replace the links." }, "labels": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] } }, "stripeAccountId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's Stripe connected account on the merchant's Stripe platform. Scheduled payouts\nsend Stripe transfers here when the payout schedule names a Stripe connection. Setting it\nneeds payouts:write. Null removes it." }, "locale": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ], "description": "The partner's language: en, fr-CA, hy or ru. Emails, the embedded dashboard and the partner\nportal use it when the company uses it, and the company's default otherwise. Null\nremoves it." } }, "required": [ "programIds", "id", "companyId", "referralCode", "alias", "active", "createdAt", "email", "name", "externalId" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/attributions": { "post": { "operationId": "attribute", "summary": "attribute", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerDisplayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "referralCode": { "type": "string", "minLength": 1, "maxLength": 120 }, "providerPromoCodeId": { "type": "string", "minLength": 1, "maxLength": 120 }, "channel": { "type": "string", "enum": [ "link", "qr", "coupon", "in_app" ] }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "programId", "customerId", "referralCode", "channel", "occurredAt" ], "additionalProperties": false }, "example": { "programId": "program-example", "customerId": "customer-example", "orderId": "order-example", "referralCode": "EXAMPLE", "channel": "link", "occurredAt": "2026-10-11T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "qualifiedAt": { "type": "string" }, "qualifiedOrderNumber": { "type": "number" }, "programId": { "type": "string" }, "referralCode": { "type": "string" }, "customerId": { "type": "string" }, "occurredAt": { "type": "string" }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "providerPromoCodeId": { "type": "string" }, "customerDisplayName": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "referralCode", "customerId", "occurredAt", "channel" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "qualifiedAt": { "type": "string" }, "qualifiedOrderNumber": { "type": "number" }, "programId": { "type": "string" }, "referralCode": { "type": "string" }, "customerId": { "type": "string" }, "occurredAt": { "type": "string" }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "providerPromoCodeId": { "type": "string" }, "customerDisplayName": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "referralCode", "customerId", "occurredAt", "channel" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/referrals/code": { "post": { "operationId": "attachReferralCode", "summary": "attachReferralCode", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerDisplayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "referralCode": { "type": "string", "minLength": 1, "maxLength": 120 }, "channel": { "type": "string", "enum": [ "link", "qr", "coupon", "in_app" ], "default": "coupon" }, "signals": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 40 }, "phoneHash": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, "paymentFingerprint": { "type": "string", "minLength": 1, "maxLength": 255 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ipAddress": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "customerId", "referralCode" ], "additionalProperties": false }, "example": { "customerId": "customer-example", "orderId": "order-example", "referralCode": "EXAMPLE" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "receipt": { "type": "string" }, "programId": { "type": "string" }, "placements": { "type": "array", "items": { "type": "string" } }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" }, "expiresAt": { "type": "string" }, "duration": { "anyOf": [ { "type": "string", "const": "only_order" }, { "type": "string", "const": "first_order" }, { "type": "string", "const": "first_n_orders" }, { "type": "string", "const": "days" }, { "type": "string", "const": "months" }, { "type": "string", "const": "lifetime" } ] }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The program's current friend incentive, or null when it has none. Says nothing about eligibility." }, "display": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ] } ], "description": "The program's public name, headline and milestone label. Null when the program is gone." }, "attribution": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "qualifiedAt": { "type": "string" }, "qualifiedOrderNumber": { "type": "number" }, "programId": { "type": "string" }, "referralCode": { "type": "string" }, "customerId": { "type": "string" }, "occurredAt": { "type": "string" }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "providerPromoCodeId": { "type": "string" }, "customerDisplayName": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "referralCode", "customerId", "occurredAt", "channel" ], "description": "Present for customer programs. It may retain a previously qualified partner." }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when customer links or identity signals match the partner: review or flagged. A blocked match throws self_referral." } }, "required": [ "receipt", "programId", "placements", "partnerId", "partnerExternalId", "expiresAt", "duration", "incentive", "display" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "receipt": { "type": "string" }, "programId": { "type": "string" }, "placements": { "type": "array", "items": { "type": "string" } }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" }, "expiresAt": { "type": "string" }, "duration": { "anyOf": [ { "type": "string", "const": "only_order" }, { "type": "string", "const": "first_order" }, { "type": "string", "const": "first_n_orders" }, { "type": "string", "const": "days" }, { "type": "string", "const": "months" }, { "type": "string", "const": "lifetime" } ] }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The program's current friend incentive, or null when it has none. Says nothing about eligibility." }, "display": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ] } ], "description": "The program's public name, headline and milestone label. Null when the program is gone." }, "attribution": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "qualifiedAt": { "type": "string" }, "qualifiedOrderNumber": { "type": "number" }, "programId": { "type": "string" }, "referralCode": { "type": "string" }, "customerId": { "type": "string" }, "occurredAt": { "type": "string" }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "providerPromoCodeId": { "type": "string" }, "customerDisplayName": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "referralCode", "customerId", "occurredAt", "channel" ], "description": "Present for customer programs. It may retain a previously qualified partner." }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when customer links or identity signals match the partner: review or flagged. A blocked match throws self_referral." } }, "required": [ "receipt", "programId", "placements", "partnerId", "partnerExternalId", "expiresAt", "duration", "incentive", "display" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/referrals/incentive": { "post": { "operationId": "getReferralIncentive", "summary": "Read-only preview of a friend or earned offer. An eligible friend offer wins. Otherwise linked\npartner customer IDs can use an earned offer, soonest expiry first. incentiveKind identifies\nthe kind, and earned offers include rewardId. It holds nothing, so two\ncheckouts can both see it. Reserve only when an order is placed. Send newCustomer\nfrom your server's order history, or omit it to use Grizzlee's recorded purchases.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "receipt" }, "receipt": { "type": "string", "maxLength": 4096 } }, "required": [ "type", "receipt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "referralCode": { "type": "string", "maxLength": 120 }, "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "providerPromoCodeId": { "type": "string", "minLength": 1, "maxLength": 120 }, "enteredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "referralCode" ], "additionalProperties": false } ] }, "maxItems": 50 }, "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "newCustomer": { "type": "boolean" }, "customerOrderNumber": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "categories": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "maxItems": 20 }, "signals": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 40 }, "phoneHash": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, "paymentFingerprint": { "type": "string", "minLength": 1, "maxLength": 255 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ipAddress": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "customerId" ], "additionalProperties": false }, "example": { "customerId": "customer-example", "orderId": "order-example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ] }, "rewardId": { "type": "string", "description": "Present only for earned offers." }, "programId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "partnerId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "terms": { "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" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The offer's terms with currency, or null when there is no offer." }, "display": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ] } ], "description": "The program's public name, headline and milestone label. Null when programId is null." }, "eligible": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "category_not_eligible" }, { "type": "string", "const": "no_incentive" }, { "type": "string", "const": "not_new_customer" }, { "type": "string", "const": "order_limit_reached" }, { "type": "string", "const": "uses_exhausted" }, { "type": "string", "const": "reservation_open" }, { "type": "string", "const": "offer_voided" } ], "description": "Present when eligible is false." }, "usesRemaining": { "type": "number", "description": "Orders, counting this one, that can still get the incentive. 0 when not eligible." }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the incentive stops applying. Null when it never expires or the program has none." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee will give this customer's next order." }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when customer links or identity signals match the partner. blocked comes with reason\nself_referral. review means the incentive applies and the partner's reward will wait for review.\nflagged means the incentive and the reward go ahead as usual, with the match recorded." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with reason fraud. review means the incentive\napplies and the partner's reward will wait for review. flagged records the rules only." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "incentiveKind", "programId", "partnerId", "terms", "display", "eligible", "usesRemaining", "expiresAt", "customerOrderNumber" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ] }, "rewardId": { "type": "string", "description": "Present only for earned offers." }, "programId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "partnerId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "terms": { "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" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The offer's terms with currency, or null when there is no offer." }, "display": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ] } ], "description": "The program's public name, headline and milestone label. Null when programId is null." }, "eligible": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "category_not_eligible" }, { "type": "string", "const": "no_incentive" }, { "type": "string", "const": "not_new_customer" }, { "type": "string", "const": "order_limit_reached" }, { "type": "string", "const": "uses_exhausted" }, { "type": "string", "const": "reservation_open" }, { "type": "string", "const": "offer_voided" } ], "description": "Present when eligible is false." }, "usesRemaining": { "type": "number", "description": "Orders, counting this one, that can still get the incentive. 0 when not eligible." }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the incentive stops applying. Null when it never expires or the program has none." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee will give this customer's next order." }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when customer links or identity signals match the partner. blocked comes with reason\nself_referral. review means the incentive applies and the partner's reward will wait for review.\nflagged means the incentive and the reward go ahead as usual, with the match recorded." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with reason fraud. review means the incentive\napplies and the partner's reward will wait for review. flagged records the rules only." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "incentiveKind", "programId", "partnerId", "terms", "display", "eligible", "usesRemaining", "expiresAt", "customerOrderNumber" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/referrals/incentive/reservations": { "post": { "operationId": "reserveIncentive", "summary": "Holds a friend or earned offer for a placed order until completion or release. An eligible\nfriend offer wins. Earned holds include rewardId and incentiveKind. Repeating orderId returns\nthe same hold. Other orders holding the remaining uses return eligible false. A supplied\nnewCustomer must match the saved answer. Omit it on a replay to keep that answer.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "newCustomer": { "type": "boolean" }, "candidates": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "receipt" }, "receipt": { "type": "string", "maxLength": 4096 } }, "required": [ "type", "receipt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "referralCode": { "type": "string", "maxLength": 120 }, "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "providerPromoCodeId": { "type": "string", "minLength": 1, "maxLength": 120 }, "enteredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "referralCode" ], "additionalProperties": false } ] }, "maxItems": 50 }, "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "baseCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "categories": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "maxItems": 20 }, "signals": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 40 }, "phoneHash": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, "paymentFingerprint": { "type": "string", "minLength": 1, "maxLength": 255 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ipAddress": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "customerId", "orderId" ], "additionalProperties": false }, "example": { "customerId": "customer-example", "orderId": "order-example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ] }, "rewardId": { "type": "string", "description": "Present only for earned offers." }, "reservationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null when the customer is not eligible. Nothing is held then. A replayed order returns its\nreservation with eligible false once it is consumed or released." }, "status": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "open" }, { "type": "string", "const": "consumed" }, { "type": "string", "const": "released" } ] }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "eligible": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "category_not_eligible" }, { "type": "string", "const": "no_incentive" }, { "type": "string", "const": "not_new_customer" }, { "type": "string", "const": "order_limit_reached" }, { "type": "string", "const": "uses_exhausted" }, { "type": "string", "const": "reservation_open" }, { "type": "string", "const": "offer_voided" } ] }, "programId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "partnerId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "terms": { "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" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The terms the reservation holds, with currency, or the program's current offer when none is held." }, "programVersion": { "type": "number", "description": "The program version terms come from: the reservation's version, or the current version when\nnothing is held. Absent for reservations made before programs had versions." }, "suggestedDiscountCents": { "type": "number", "description": "computeIncentiveCents(terms, baseCents). Present when baseCents was sent and the customer is eligible." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee expects for this order." }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when customer links or identity signals match the partner. Works like the lookup's." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. Works like the lookup's." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "incentiveKind", "reservationId", "status", "orderId", "eligible", "programId", "partnerId", "terms", "customerOrderNumber" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ] }, "rewardId": { "type": "string", "description": "Present only for earned offers." }, "reservationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null when the customer is not eligible. Nothing is held then. A replayed order returns its\nreservation with eligible false once it is consumed or released." }, "status": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "open" }, { "type": "string", "const": "consumed" }, { "type": "string", "const": "released" } ] }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "eligible": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "category_not_eligible" }, { "type": "string", "const": "no_incentive" }, { "type": "string", "const": "not_new_customer" }, { "type": "string", "const": "order_limit_reached" }, { "type": "string", "const": "uses_exhausted" }, { "type": "string", "const": "reservation_open" }, { "type": "string", "const": "offer_voided" } ] }, "programId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "partnerId": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "terms": { "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" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The terms the reservation holds, with currency, or the program's current offer when none is held." }, "programVersion": { "type": "number", "description": "The program version terms come from: the reservation's version, or the current version when\nnothing is held. Absent for reservations made before programs had versions." }, "suggestedDiscountCents": { "type": "number", "description": "computeIncentiveCents(terms, baseCents). Present when baseCents was sent and the customer is eligible." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee expects for this order." }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when customer links or identity signals match the partner. Works like the lookup's." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. Works like the lookup's." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "incentiveKind", "reservationId", "status", "orderId", "eligible", "programId", "partnerId", "terms", "customerOrderNumber" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "get": { "operationId": "listIncentiveReservations", "summary": "Latest reservations, or open holds older than the requested number of days.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "olderThanDays", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 100000 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "reservations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The placed order. Absent only on historical quote holds released by migration." }, "customerId": { "type": "string" }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "open" }, { "type": "string", "const": "consumed" }, { "type": "string", "const": "released" } ] }, "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] }, { "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ], "description": "Terms when the reservation was made. Later program edits leave them alone." }, "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ], "description": "Absent on historical friend holds." }, "rewardId": { "type": "string" }, "programVersion": { "type": "number", "description": "The program version the terms come from. Absent on reservations made before programs had versions." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "incentiveExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the offer itself stops applying. Earned holds keep the reward's offer expiry. Null when it never expires." }, "referredAt": { "type": "string", "description": "Earned holds use the reward's createdAt, when the offer was earned." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee expected for the order when it reserved." }, "newCustomer": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "The merchant's answer when this hold was made. Omitted, eligibility used recorded purchases." }, "baseCents": { "type": "number" }, "suggestedDiscountCents": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The categories the order sent when it reserved. The order's own categories are checked again when it completes." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "id", "companyId", "customerId", "programId", "partnerId", "status", "terms", "currency", "incentiveExpiresAt", "referredAt", "customerOrderNumber", "createdAt", "updatedAt" ] } } }, "required": [ "reservations" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "reservations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The placed order. Absent only on historical quote holds released by migration." }, "customerId": { "type": "string" }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "open" }, { "type": "string", "const": "consumed" }, { "type": "string", "const": "released" } ] }, "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] }, { "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ], "description": "Terms when the reservation was made. Later program edits leave them alone." }, "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ], "description": "Absent on historical friend holds." }, "rewardId": { "type": "string" }, "programVersion": { "type": "number", "description": "The program version the terms come from. Absent on reservations made before programs had versions." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "incentiveExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the offer itself stops applying. Earned holds keep the reward's offer expiry. Null when it never expires." }, "referredAt": { "type": "string", "description": "Earned holds use the reward's createdAt, when the offer was earned." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee expected for the order when it reserved." }, "newCustomer": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "The merchant's answer when this hold was made. Omitted, eligibility used recorded purchases." }, "baseCents": { "type": "number" }, "suggestedDiscountCents": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The categories the order sent when it reserved. The order's own categories are checked again when it completes." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "id", "companyId", "customerId", "programId", "partnerId", "status", "terms", "currency", "incentiveExpiresAt", "referredAt", "customerOrderNumber", "createdAt", "updatedAt" ] } } }, "required": [ "reservations" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/referrals/incentive/reservations/{reservationId}/release": { "post": { "operationId": "releaseIncentive", "summary": "Frees an open hold when its order is cancelled. Safe to repeat.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [ { "name": "reservationId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The placed order. Absent only on historical quote holds released by migration." }, "customerId": { "type": "string" }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "open" }, { "type": "string", "const": "consumed" }, { "type": "string", "const": "released" } ] }, "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] }, { "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ], "description": "Terms when the reservation was made. Later program edits leave them alone." }, "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ], "description": "Absent on historical friend holds." }, "rewardId": { "type": "string" }, "programVersion": { "type": "number", "description": "The program version the terms come from. Absent on reservations made before programs had versions." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "incentiveExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the offer itself stops applying. Earned holds keep the reward's offer expiry. Null when it never expires." }, "referredAt": { "type": "string", "description": "Earned holds use the reward's createdAt, when the offer was earned." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee expected for the order when it reserved." }, "newCustomer": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "The merchant's answer when this hold was made. Omitted, eligibility used recorded purchases." }, "baseCents": { "type": "number" }, "suggestedDiscountCents": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The categories the order sent when it reserved. The order's own categories are checked again when it completes." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "id", "companyId", "customerId", "programId", "partnerId", "status", "terms", "currency", "incentiveExpiresAt", "referredAt", "customerOrderNumber", "createdAt", "updatedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The placed order. Absent only on historical quote holds released by migration." }, "customerId": { "type": "string" }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "open" }, { "type": "string", "const": "consumed" }, { "type": "string", "const": "released" } ] }, "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] }, { "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ], "description": "Terms when the reservation was made. Later program edits leave them alone." }, "incentiveKind": { "anyOf": [ { "type": "string", "const": "friend" }, { "type": "string", "const": "earned" } ], "description": "Absent on historical friend holds." }, "rewardId": { "type": "string" }, "programVersion": { "type": "number", "description": "The program version the terms come from. Absent on reservations made before programs had versions." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "incentiveExpiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the offer itself stops applying. Earned holds keep the reward's offer expiry. Null when it never expires." }, "referredAt": { "type": "string", "description": "Earned holds use the reward's createdAt, when the offer was earned." }, "customerOrderNumber": { "type": "number", "description": "The purchase number Grizzlee expected for the order when it reserved." }, "newCustomer": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "The merchant's answer when this hold was made. Omitted, eligibility used recorded purchases." }, "baseCents": { "type": "number" }, "suggestedDiscountCents": { "type": "number" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "The categories the order sent when it reserved. The order's own categories are checked again when it completes." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "id", "companyId", "customerId", "programId", "partnerId", "status", "terms", "currency", "incentiveExpiresAt", "referredAt", "customerOrderNumber", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/customers/import": { "post": { "operationId": "importCustomers", "summary": "Sets how many successful orders each customer had before you reported orders to Grizzlee, so\nreturning customers are not counted as new. Up to 1,000 customers per call. Safe to repeat.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customers": { "type": "array", "items": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "priorOrderCount": { "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "customerId", "priorOrderCount" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } }, "required": [ "customers" ], "additionalProperties": false }, "example": { "customers": [ { "customerId": "customer-example", "priorOrderCount": 1 } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "imported": { "type": "number" } }, "required": [ "imported" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "imported": { "type": "number" } }, "required": [ "imported" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/referrals/claim": { "post": { "operationId": "claimReferral", "summary": "claimReferral", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "receipt" }, "receipt": { "type": "string", "maxLength": 4096 } }, "required": [ "type", "receipt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "referralCode": { "type": "string", "maxLength": 120 }, "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "providerPromoCodeId": { "type": "string", "minLength": 1, "maxLength": 120 }, "enteredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "referralCode" ], "additionalProperties": false } ] }, "maxItems": 50 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerDisplayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "expectedProgramId": { "type": "string", "minLength": 1, "maxLength": 120 }, "signals": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 40 }, "phoneHash": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, "paymentFingerprint": { "type": "string", "minLength": 1, "maxLength": 255 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ipAddress": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "candidates", "customerId" ], "additionalProperties": false }, "example": { "candidates": [], "customerId": "customer-example", "orderId": "order-example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "attribution": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "qualifiedAt": { "type": "string" }, "qualifiedOrderNumber": { "type": "number" }, "programId": { "type": "string" }, "referralCode": { "type": "string" }, "customerId": { "type": "string" }, "occurredAt": { "type": "string" }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "providerPromoCodeId": { "type": "string" }, "customerDisplayName": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "referralCode", "customerId", "occurredAt", "channel" ] } ] }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] }, "placements": { "type": "array", "items": { "type": "string" } } }, "required": [ "attribution", "referralSelection", "placements" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "attribution": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "qualifiedAt": { "type": "string" }, "qualifiedOrderNumber": { "type": "number" }, "programId": { "type": "string" }, "referralCode": { "type": "string" }, "customerId": { "type": "string" }, "occurredAt": { "type": "string" }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "providerPromoCodeId": { "type": "string" }, "customerDisplayName": { "type": "string" }, "orderId": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "referralCode", "customerId", "occurredAt", "channel" ] } ] }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] }, "placements": { "type": "array", "items": { "type": "string" } } }, "required": [ "attribution", "referralSelection", "placements" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/events": { "post": { "operationId": "sendEvent", "summary": "sendEvent", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order.completed" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerDisplayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "customerEmail": { "type": "string", "format": "email", "maxLength": 254 }, "newCustomer": { "type": "boolean" }, "customerOrderNumber": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "currency": { "type": "string", "enum": [ "CAD", "USD", "EUR", "GBP" ] }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "commissionableCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "incentiveAppliedCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "categories": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "maxItems": 20 }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "eventId", "orderId", "customerId", "currency", "commissionableCents", "occurredAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "order.refunded" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "refundedTotalCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "refundedCommissionableCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "fullRefund": { "type": "boolean" }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "eventId", "orderId", "occurredAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "order.adjusted" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "commissionableCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "eventId", "orderId", "occurredAt" ], "additionalProperties": false } ] }, "example": { "type": "order.completed", "eventId": "payment-example", "orderId": "order-example", "customerId": "customer-example", "currency": "CAD", "totalCents": 10000, "commissionableCents": 10000, "occurredAt": "2026-10-11T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "orderId": { "type": "string" }, "duplicate": { "type": "boolean" }, "customerOrderNumber": { "type": "number", "description": "Completions only. The purchase number Grizzlee gave the order." }, "incentiveFlag": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "const": "no_reservation" }, { "type": "string", "const": "reservation_expired" }, { "type": "string", "const": "reservation_released" }, { "type": "string", "const": "reservation_consumed" }, { "type": "string", "const": "reservation_locked" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "exceeds_terms" }, { "type": "string", "const": "category_not_eligible" } ] }, "rewardId": { "type": "string" }, "programId": { "type": "string", "description": "Program of the reservation or referral checked. Absent for no_referral." }, "reservationId": { "type": "string", "description": "The reservation sent with the order, when there was one." }, "maxCents": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Largest discount the terms allow on one order. Null when they set no cap or there are no terms." }, "reportedCents": { "type": "number", "description": "incentiveAppliedCents as the merchant reported it." } }, "required": [ "reason", "maxCents", "reportedCents" ], "description": "Completions only. Present when incentiveAppliedCents did not match the reservation." }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] } }, "rewardIds": { "type": "array", "items": { "type": "string" } }, "reversalCents": { "type": "number" }, "restoredCents": { "type": "number", "description": "Reward amount given back because the order's cumulative refund total went down." }, "increasedCents": { "type": "number", "description": "Adjustments only. Reward value a higher order total added. Lower totals report reversalCents." }, "stale": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "True when a refund or adjustment event was older than the latest applied one of its kind for\nthe order and changed nothing." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "eventId", "orderId", "duplicate", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "orderId": { "type": "string" }, "duplicate": { "type": "boolean" }, "customerOrderNumber": { "type": "number", "description": "Completions only. The purchase number Grizzlee gave the order." }, "incentiveFlag": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "const": "no_reservation" }, { "type": "string", "const": "reservation_expired" }, { "type": "string", "const": "reservation_released" }, { "type": "string", "const": "reservation_consumed" }, { "type": "string", "const": "reservation_locked" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "exceeds_terms" }, { "type": "string", "const": "category_not_eligible" } ] }, "rewardId": { "type": "string" }, "programId": { "type": "string", "description": "Program of the reservation or referral checked. Absent for no_referral." }, "reservationId": { "type": "string", "description": "The reservation sent with the order, when there was one." }, "maxCents": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Largest discount the terms allow on one order. Null when they set no cap or there are no terms." }, "reportedCents": { "type": "number", "description": "incentiveAppliedCents as the merchant reported it." } }, "required": [ "reason", "maxCents", "reportedCents" ], "description": "Completions only. Present when incentiveAppliedCents did not match the reservation." }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] } }, "rewardIds": { "type": "array", "items": { "type": "string" } }, "reversalCents": { "type": "number" }, "restoredCents": { "type": "number", "description": "Reward amount given back because the order's cumulative refund total went down." }, "increasedCents": { "type": "number", "description": "Adjustments only. Reward value a higher order total added. Lower totals report reversalCents." }, "stale": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "True when a refund or adjustment event was older than the latest applied one of its kind for\nthe order and changed nothing." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "eventId", "orderId", "duplicate", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/orders/complete": { "post": { "operationId": "completeOrder", "summary": "Retain qualified customer attribution or claim the newest valid candidate. Consume an optional\nfriend or earned offer reservation and record payment atomically. Report the server-priced\ndiscount in incentiveAppliedCents. An earned hold keeps its copied terms even if the earning\nreward was later reversed. Without a hold, an applied discount can use an available earned\noffer and is flagged no_reservation. With newCustomer from your own history, report referred\npurchases and purchases that use earned offers.\nOtherwise report every completed order and import earlier purchases. The result has Grizzlee's\ncustomerOrderNumber and, when the discount did not match the reservation, incentiveFlag.\nsignals are the customer's identity signals for the self-referral check.", "description": "Claiming candidates, including an order's saved selection, also requires partners:write. Your server supplies payment amounts and the authenticated customer's ID.", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "object", "properties": { "type": { "type": "string", "const": "order.completed" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerDisplayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "customerEmail": { "type": "string", "format": "email", "maxLength": 254 }, "newCustomer": { "type": "boolean" }, "customerOrderNumber": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "currency": { "type": "string", "enum": [ "CAD", "USD", "EUR", "GBP" ] }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "commissionableCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "incentiveAppliedCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "categories": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "maxItems": 20 }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "eventId", "orderId", "customerId", "currency", "commissionableCents", "occurredAt" ], "additionalProperties": false }, "candidates": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "receipt" }, "receipt": { "type": "string", "maxLength": 4096 } }, "required": [ "type", "receipt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "referralCode": { "type": "string", "maxLength": 120 }, "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "providerPromoCodeId": { "type": "string", "minLength": 1, "maxLength": 120 }, "enteredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "referralCode" ], "additionalProperties": false } ] }, "maxItems": 50 }, "reservationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "signals": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254 }, "phone": { "type": "string", "maxLength": 40 }, "phoneHash": { "type": "string", "pattern": "^[0-9a-fA-F]{64}$" }, "paymentFingerprint": { "type": "string", "minLength": 1, "maxLength": 255 }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 255 }, "ipAddress": { "type": "string", "maxLength": 64 } }, "additionalProperties": false } }, "required": [ "event" ], "additionalProperties": false }, "example": { "event": { "type": "order.completed", "eventId": "payment-example", "orderId": "order-example", "customerId": "customer-example", "currency": "CAD", "totalCents": 10000, "commissionableCents": 10000, "occurredAt": "2026-10-11T12:00:00.000Z" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "orderId": { "type": "string" }, "duplicate": { "type": "boolean" }, "customerOrderNumber": { "type": "number", "description": "Completions only. The purchase number Grizzlee gave the order." }, "incentiveFlag": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "const": "no_reservation" }, { "type": "string", "const": "reservation_expired" }, { "type": "string", "const": "reservation_released" }, { "type": "string", "const": "reservation_consumed" }, { "type": "string", "const": "reservation_locked" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "exceeds_terms" }, { "type": "string", "const": "category_not_eligible" } ] }, "rewardId": { "type": "string" }, "programId": { "type": "string", "description": "Program of the reservation or referral checked. Absent for no_referral." }, "reservationId": { "type": "string", "description": "The reservation sent with the order, when there was one." }, "maxCents": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Largest discount the terms allow on one order. Null when they set no cap or there are no terms." }, "reportedCents": { "type": "number", "description": "incentiveAppliedCents as the merchant reported it." } }, "required": [ "reason", "maxCents", "reportedCents" ], "description": "Completions only. Present when incentiveAppliedCents did not match the reservation." }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] } }, "rewardIds": { "type": "array", "items": { "type": "string" } }, "reversalCents": { "type": "number" }, "restoredCents": { "type": "number", "description": "Reward amount given back because the order's cumulative refund total went down." }, "increasedCents": { "type": "number", "description": "Adjustments only. Reward value a higher order total added. Lower totals report reversalCents." }, "stale": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "True when a refund or adjustment event was older than the latest applied one of its kind for\nthe order and changed nothing." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "eventId", "orderId", "duplicate", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "orderId": { "type": "string" }, "duplicate": { "type": "boolean" }, "customerOrderNumber": { "type": "number", "description": "Completions only. The purchase number Grizzlee gave the order." }, "incentiveFlag": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "const": "no_reservation" }, { "type": "string", "const": "reservation_expired" }, { "type": "string", "const": "reservation_released" }, { "type": "string", "const": "reservation_consumed" }, { "type": "string", "const": "reservation_locked" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "exceeds_terms" }, { "type": "string", "const": "category_not_eligible" } ] }, "rewardId": { "type": "string" }, "programId": { "type": "string", "description": "Program of the reservation or referral checked. Absent for no_referral." }, "reservationId": { "type": "string", "description": "The reservation sent with the order, when there was one." }, "maxCents": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Largest discount the terms allow on one order. Null when they set no cap or there are no terms." }, "reportedCents": { "type": "number", "description": "incentiveAppliedCents as the merchant reported it." } }, "required": [ "reason", "maxCents", "reportedCents" ], "description": "Completions only. Present when incentiveAppliedCents did not match the reservation." }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] } }, "rewardIds": { "type": "array", "items": { "type": "string" } }, "reversalCents": { "type": "number" }, "restoredCents": { "type": "number", "description": "Reward amount given back because the order's cumulative refund total went down." }, "increasedCents": { "type": "number", "description": "Adjustments only. Reward value a higher order total added. Lower totals report reversalCents." }, "stale": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "True when a refund or adjustment event was older than the latest applied one of its kind for\nthe order and changed nothing." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "eventId", "orderId", "duplicate", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/milestones": { "post": { "operationId": "reportMilestone", "summary": "Reports one occurrence of a milestone for a referred person, such as one completed task. Each\nactive program can pay on each report and once at a count. Percentage report rewards require\nvalueCents in the program currency. Send a new eventId for each occurrence and reuse it\nfor retries. While the milestone is revoked for this person, a report counts but\nreturns status revoked and earns nothing.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestone": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,79}$" }, "valueCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "eventId", "customerId", "milestone", "occurredAt" ], "additionalProperties": false }, "example": { "eventId": "payment-example", "customerId": "customer-example", "milestone": "first_booking", "occurredAt": "2026-10-11T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "customerId": { "type": "string" }, "milestone": { "type": "string" }, "duplicate": { "type": "boolean", "description": "True when this event ID was already processed with the same data." }, "status": { "anyOf": [ { "type": "string", "const": "recorded" }, { "type": "string", "const": "revoked" }, { "type": "string", "const": "reinstated" }, { "type": "string", "const": "reversed" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] }, "description": "Reports: one entry per evaluated reward rule in each active program. Empty otherwise." }, "rewardIds": { "type": "array", "items": { "type": "string" }, "description": "Reports: rewards this report created. Revocations, reinstatements and reversals: every reward\nfor this person and milestone." }, "reversalCents": { "type": "number", "description": "Revocations and reversals: reward value this event reversed. 0 for reports and\nreinstatements." }, "restoredCents": { "type": "number", "description": "Reinstatements and reports: reward value this event gave back. A report gives value back when\nit brings the count up to a reward's threshold again. Absent on revocations, reversals and\nreports saved before milestones were counted." }, "count": { "type": "number", "description": "The person's reports of this milestone that are not reversed, from any time and including\nthis event's. Each decision's milestoneCount is the part that counts for its program. Absent\non results saved before milestones were counted." }, "reportEventId": { "type": "string", "description": "Reversals: the eventId of the report this event took back." } }, "required": [ "eventId", "customerId", "milestone", "duplicate", "status", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "customerId": { "type": "string" }, "milestone": { "type": "string" }, "duplicate": { "type": "boolean", "description": "True when this event ID was already processed with the same data." }, "status": { "anyOf": [ { "type": "string", "const": "recorded" }, { "type": "string", "const": "revoked" }, { "type": "string", "const": "reinstated" }, { "type": "string", "const": "reversed" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] }, "description": "Reports: one entry per evaluated reward rule in each active program. Empty otherwise." }, "rewardIds": { "type": "array", "items": { "type": "string" }, "description": "Reports: rewards this report created. Revocations, reinstatements and reversals: every reward\nfor this person and milestone." }, "reversalCents": { "type": "number", "description": "Revocations and reversals: reward value this event reversed. 0 for reports and\nreinstatements." }, "restoredCents": { "type": "number", "description": "Reinstatements and reports: reward value this event gave back. A report gives value back when\nit brings the count up to a reward's threshold again. Absent on revocations, reversals and\nreports saved before milestones were counted." }, "count": { "type": "number", "description": "The person's reports of this milestone that are not reversed, from any time and including\nthis event's. Each decision's milestoneCount is the part that counts for its program. Absent\non results saved before milestones were counted." }, "reportEventId": { "type": "string", "description": "Reversals: the eventId of the report this event took back." } }, "required": [ "eventId", "customerId", "milestone", "duplicate", "status", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/milestones/revoke": { "post": { "operationId": "revokeMilestone", "summary": "Reverses every reward the person earned for the milestone. A reward you already delivered\nbecomes partner debt. The milestone earns nothing for this person until you reinstate it.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestone": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,79}$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "eventId", "customerId", "milestone", "reason" ], "additionalProperties": false }, "example": { "eventId": "payment-example", "customerId": "customer-example", "milestone": "first_booking", "reason": "Merchant review" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "customerId": { "type": "string" }, "milestone": { "type": "string" }, "duplicate": { "type": "boolean", "description": "True when this event ID was already processed with the same data." }, "status": { "anyOf": [ { "type": "string", "const": "recorded" }, { "type": "string", "const": "revoked" }, { "type": "string", "const": "reinstated" }, { "type": "string", "const": "reversed" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] }, "description": "Reports: one entry per evaluated reward rule in each active program. Empty otherwise." }, "rewardIds": { "type": "array", "items": { "type": "string" }, "description": "Reports: rewards this report created. Revocations, reinstatements and reversals: every reward\nfor this person and milestone." }, "reversalCents": { "type": "number", "description": "Revocations and reversals: reward value this event reversed. 0 for reports and\nreinstatements." }, "restoredCents": { "type": "number", "description": "Reinstatements and reports: reward value this event gave back. A report gives value back when\nit brings the count up to a reward's threshold again. Absent on revocations, reversals and\nreports saved before milestones were counted." }, "count": { "type": "number", "description": "The person's reports of this milestone that are not reversed, from any time and including\nthis event's. Each decision's milestoneCount is the part that counts for its program. Absent\non results saved before milestones were counted." }, "reportEventId": { "type": "string", "description": "Reversals: the eventId of the report this event took back." } }, "required": [ "eventId", "customerId", "milestone", "duplicate", "status", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "customerId": { "type": "string" }, "milestone": { "type": "string" }, "duplicate": { "type": "boolean", "description": "True when this event ID was already processed with the same data." }, "status": { "anyOf": [ { "type": "string", "const": "recorded" }, { "type": "string", "const": "revoked" }, { "type": "string", "const": "reinstated" }, { "type": "string", "const": "reversed" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] }, "description": "Reports: one entry per evaluated reward rule in each active program. Empty otherwise." }, "rewardIds": { "type": "array", "items": { "type": "string" }, "description": "Reports: rewards this report created. Revocations, reinstatements and reversals: every reward\nfor this person and milestone." }, "reversalCents": { "type": "number", "description": "Revocations and reversals: reward value this event reversed. 0 for reports and\nreinstatements." }, "restoredCents": { "type": "number", "description": "Reinstatements and reports: reward value this event gave back. A report gives value back when\nit brings the count up to a reward's threshold again. Absent on revocations, reversals and\nreports saved before milestones were counted." }, "count": { "type": "number", "description": "The person's reports of this milestone that are not reversed, from any time and including\nthis event's. Each decision's milestoneCount is the part that counts for its program. Absent\non results saved before milestones were counted." }, "reportEventId": { "type": "string", "description": "Reversals: the eventId of the report this event took back." } }, "required": [ "eventId", "customerId", "milestone", "duplicate", "status", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/milestones/reinstate": { "post": { "operationId": "reinstateMilestone", "summary": "Undoes a revocation. Eligible rewards return and reduce outstanding delivery debt. Rejected\nrewards and rewards from reversed reports stay reversed. Bonuses wait for their saved count.\nRewards the revocation prevented need a new report under a new eventId. Use a new eventId for each\nrevocation and reinstatement. Returns status reinstated and restoredCents.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "milestone": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,79}$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "eventId", "customerId", "milestone" ], "additionalProperties": false }, "example": { "eventId": "payment-example", "customerId": "customer-example", "milestone": "first_booking" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "customerId": { "type": "string" }, "milestone": { "type": "string" }, "duplicate": { "type": "boolean", "description": "True when this event ID was already processed with the same data." }, "status": { "anyOf": [ { "type": "string", "const": "recorded" }, { "type": "string", "const": "revoked" }, { "type": "string", "const": "reinstated" }, { "type": "string", "const": "reversed" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] }, "description": "Reports: one entry per evaluated reward rule in each active program. Empty otherwise." }, "rewardIds": { "type": "array", "items": { "type": "string" }, "description": "Reports: rewards this report created. Revocations, reinstatements and reversals: every reward\nfor this person and milestone." }, "reversalCents": { "type": "number", "description": "Revocations and reversals: reward value this event reversed. 0 for reports and\nreinstatements." }, "restoredCents": { "type": "number", "description": "Reinstatements and reports: reward value this event gave back. A report gives value back when\nit brings the count up to a reward's threshold again. Absent on revocations, reversals and\nreports saved before milestones were counted." }, "count": { "type": "number", "description": "The person's reports of this milestone that are not reversed, from any time and including\nthis event's. Each decision's milestoneCount is the part that counts for its program. Absent\non results saved before milestones were counted." }, "reportEventId": { "type": "string", "description": "Reversals: the eventId of the report this event took back." } }, "required": [ "eventId", "customerId", "milestone", "duplicate", "status", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "customerId": { "type": "string" }, "milestone": { "type": "string" }, "duplicate": { "type": "boolean", "description": "True when this event ID was already processed with the same data." }, "status": { "anyOf": [ { "type": "string", "const": "recorded" }, { "type": "string", "const": "revoked" }, { "type": "string", "const": "reinstated" }, { "type": "string", "const": "reversed" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] }, "description": "Reports: one entry per evaluated reward rule in each active program. Empty otherwise." }, "rewardIds": { "type": "array", "items": { "type": "string" }, "description": "Reports: rewards this report created. Revocations, reinstatements and reversals: every reward\nfor this person and milestone." }, "reversalCents": { "type": "number", "description": "Revocations and reversals: reward value this event reversed. 0 for reports and\nreinstatements." }, "restoredCents": { "type": "number", "description": "Reinstatements and reports: reward value this event gave back. A report gives value back when\nit brings the count up to a reward's threshold again. Absent on revocations, reversals and\nreports saved before milestones were counted." }, "count": { "type": "number", "description": "The person's reports of this milestone that are not reversed, from any time and including\nthis event's. Each decision's milestoneCount is the part that counts for its program. Absent\non results saved before milestones were counted." }, "reportEventId": { "type": "string", "description": "Reversals: the eventId of the report this event took back." } }, "required": [ "eventId", "customerId", "milestone", "duplicate", "status", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/milestones/reverse": { "post": { "operationId": "reverseMilestoneReport", "summary": "Takes back one earlier report, named by its eventId, so it no longer counts. Its each-report\nrewards reverse, along with bonuses below their saved count. Delivered rewards become debt.\nBonuses return when later reports bring the count back. Returns status reversed and reversalCents.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "reportEventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "eventId", "reportEventId" ], "additionalProperties": false }, "example": { "eventId": "payment-example", "reportEventId": "reportEventId-example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "customerId": { "type": "string" }, "milestone": { "type": "string" }, "duplicate": { "type": "boolean", "description": "True when this event ID was already processed with the same data." }, "status": { "anyOf": [ { "type": "string", "const": "recorded" }, { "type": "string", "const": "revoked" }, { "type": "string", "const": "reinstated" }, { "type": "string", "const": "reversed" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] }, "description": "Reports: one entry per evaluated reward rule in each active program. Empty otherwise." }, "rewardIds": { "type": "array", "items": { "type": "string" }, "description": "Reports: rewards this report created. Revocations, reinstatements and reversals: every reward\nfor this person and milestone." }, "reversalCents": { "type": "number", "description": "Revocations and reversals: reward value this event reversed. 0 for reports and\nreinstatements." }, "restoredCents": { "type": "number", "description": "Reinstatements and reports: reward value this event gave back. A report gives value back when\nit brings the count up to a reward's threshold again. Absent on revocations, reversals and\nreports saved before milestones were counted." }, "count": { "type": "number", "description": "The person's reports of this milestone that are not reversed, from any time and including\nthis event's. Each decision's milestoneCount is the part that counts for its program. Absent\non results saved before milestones were counted." }, "reportEventId": { "type": "string", "description": "Reversals: the eventId of the report this event took back." } }, "required": [ "eventId", "customerId", "milestone", "duplicate", "status", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "eventId": { "type": "string" }, "customerId": { "type": "string" }, "milestone": { "type": "string" }, "duplicate": { "type": "boolean", "description": "True when this event ID was already processed with the same data." }, "status": { "anyOf": [ { "type": "string", "const": "recorded" }, { "type": "string", "const": "revoked" }, { "type": "string", "const": "reinstated" }, { "type": "string", "const": "reversed" } ] }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] }, "description": "Reports: one entry per evaluated reward rule in each active program. Empty otherwise." }, "rewardIds": { "type": "array", "items": { "type": "string" }, "description": "Reports: rewards this report created. Revocations, reinstatements and reversals: every reward\nfor this person and milestone." }, "reversalCents": { "type": "number", "description": "Revocations and reversals: reward value this event reversed. 0 for reports and\nreinstatements." }, "restoredCents": { "type": "number", "description": "Reinstatements and reports: reward value this event gave back. A report gives value back when\nit brings the count up to a reward's threshold again. Absent on revocations, reversals and\nreports saved before milestones were counted." }, "count": { "type": "number", "description": "The person's reports of this milestone that are not reversed, from any time and including\nthis event's. Each decision's milestoneCount is the part that counts for its program. Absent\non results saved before milestones were counted." }, "reportEventId": { "type": "string", "description": "Reversals: the eventId of the report this event took back." } }, "required": [ "eventId", "customerId", "milestone", "duplicate", "status", "decisions", "rewardIds", "reversalCents" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/simulate": { "post": { "operationId": "simulate", "summary": "simulate", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "events:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order.completed" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerDisplayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "customerEmail": { "type": "string", "format": "email", "maxLength": 254 }, "newCustomer": { "type": "boolean" }, "customerOrderNumber": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "currency": { "type": "string", "enum": [ "CAD", "USD", "EUR", "GBP" ] }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "commissionableCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "incentiveAppliedCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "categories": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,39}$" } ] }, "maxItems": 20 }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "eventId", "orderId", "customerId", "currency", "commissionableCents", "occurredAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "order.refunded" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "refundedTotalCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "refundedCommissionableCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "fullRefund": { "type": "boolean" }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "eventId", "orderId", "occurredAt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "order.adjusted" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "totalCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "commissionableCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "type", "eventId", "orderId", "occurredAt" ], "additionalProperties": false } ] }, "attribution": { "type": "object", "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "customerDisplayName": { "type": "string", "minLength": 1, "maxLength": 80 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "referralCode": { "type": "string", "minLength": 1, "maxLength": 120 }, "providerPromoCodeId": { "type": "string", "minLength": 1, "maxLength": 120 }, "channel": { "type": "string", "enum": [ "link", "qr", "coupon", "in_app" ] }, "occurredAt": { "type": "string", "format": "date-time" } }, "required": [ "programId", "customerId", "referralCode", "channel", "occurredAt" ], "additionalProperties": false } }, "required": [ "event" ], "additionalProperties": false }, "example": { "event": { "type": "order.completed", "eventId": "payment-example", "orderId": "order-example", "customerId": "customer-example", "currency": "CAD", "totalCents": 10000, "commissionableCents": 10000, "occurredAt": "2026-10-11T12:00:00.000Z" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "result": { "type": "object", "properties": { "eventId": { "type": "string" }, "orderId": { "type": "string" }, "duplicate": { "type": "boolean" }, "customerOrderNumber": { "type": "number", "description": "Completions only. The purchase number Grizzlee gave the order." }, "incentiveFlag": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "const": "no_reservation" }, { "type": "string", "const": "reservation_expired" }, { "type": "string", "const": "reservation_released" }, { "type": "string", "const": "reservation_consumed" }, { "type": "string", "const": "reservation_locked" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "exceeds_terms" }, { "type": "string", "const": "category_not_eligible" } ] }, "rewardId": { "type": "string" }, "programId": { "type": "string", "description": "Program of the reservation or referral checked. Absent for no_referral." }, "reservationId": { "type": "string", "description": "The reservation sent with the order, when there was one." }, "maxCents": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Largest discount the terms allow on one order. Null when they set no cap or there are no terms." }, "reportedCents": { "type": "number", "description": "incentiveAppliedCents as the merchant reported it." } }, "required": [ "reason", "maxCents", "reportedCents" ], "description": "Completions only. Present when incentiveAppliedCents did not match the reservation." }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] } }, "rewardIds": { "type": "array", "items": { "type": "string" } }, "reversalCents": { "type": "number" }, "restoredCents": { "type": "number", "description": "Reward amount given back because the order's cumulative refund total went down." }, "increasedCents": { "type": "number", "description": "Adjustments only. Reward value a higher order total added. Lower totals report reversalCents." }, "stale": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "True when a refund or adjustment event was older than the latest applied one of its kind for\nthe order and changed nothing." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "eventId", "orderId", "duplicate", "decisions", "rewardIds", "reversalCents" ] }, "rewards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The order that earned the reward. Absent on milestone rewards." }, "milestone": { "type": "string", "description": "The milestone that earned the reward. Absent on order rewards. Exactly one of the two is set." }, "reportEventId": { "type": "string", "description": "Each-report rewards name their source. Absent on at-count bonuses." }, "milestoneReportReversed": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "valueCents": { "type": "number" }, "milestoneCount": { "type": "number", "description": "Milestone rewards: the person's reports of the milestone that count for this program now,\nthose at or after the referral minus reversed ones. Grizzlee updates it with every report,\nreversal, revocation and reinstatement for the person and milestone. Absent on rewards no\nmilestone event has touched since milestones were counted." }, "milestoneRevoked": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "Milestone rewards: true while the milestone is revoked for the person. Updated with\nmilestoneCount. Absent when not revoked, and on rewards no milestone event has touched since\nmilestones were counted." }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "customerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ] }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "expiresAt" ], "description": "Offer rewards only. Terms copied when earned. Later program edits leave them alone." }, "originalCents": { "type": "number", "description": "What the reward earned when it was created. Never changes." }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added to or removed from originalCents. Absent until the\norder is adjusted. The reward is worth originalCents + adjustedCents - reversedCents." }, "reversedCents": { "type": "number", "description": "Reversed by refunds, a rejection or a milestone revocation." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. With action review the\nreward started pending and waits for someone to approve or reject it, and automatic approval\nskips it. With action flagged it follows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. rules lists each rule ID with its signal types, never values.\nWith action review the reward started pending, waits for someone to approve or reject it, and\nautomatic approval skips it. With action flagged it follows the program's usual approval." }, "rejectedAt": { "type": "string", "description": "When someone rejected the pending reward. A rejected reward is reversed for good." }, "rejectionReason": { "type": "string", "description": "Why it was rejected, as entered." }, "statusBeforeReversal": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "approved" } ], "description": "Status the reward had when a refund fully reversed it. A later restoration returns it to this status." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Delivery mode when earned. Absent on older money rewards, which use the Grizzlee wallet. Absent on offer rewards. Readers ignore delivery for offers." }, "createdAt": { "type": "string" }, "availableAt": { "type": "string", "description": "Rewards no longer have a hold, so new rewards use createdAt. Older rewards keep their original date." }, "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" ] }, "programVersion": { "type": "number", "description": "The program version the reward was earned under. Absent on rewards earned before programs had\nversions. programSnapshot holds their rules either way." }, "historicalBasis": { "type": "string", "const": "total", "description": "Historical subtotal rewards keep their reporting-total basis for refunds and adjustments." }, "basisCents": { "type": "number" }, "explanation": { "type": "string" }, "explanationParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "explanation as codes. Absent on rewards earned before codes existed." }, "calculation": { "type": "object", "properties": { "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" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "Saved for fixed reward refunds. Older rewards default to prorate." }, "phaseAfterMonths": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "minValue": { "type": "number" }, "bonusBps": { "type": "number" }, "value": { "type": "number" } }, "required": [ "name", "minValue", "bonusBps", "value" ] }, "customTerms": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "string", "const": "partner" }, { "type": "string", "const": "customer" } ] }, "targetId": { "type": "string" } }, "required": [ "target", "targetId" ] }, "uncappedCents": { "type": "number" }, "customerCapCents": { "type": "number" }, "partnerCapCents": { "type": "number" } }, "required": [ "compensation", "uncappedCents" ] } }, "required": [ "id", "companyId", "programId", "partnerId", "customerId", "currency", "rewardType", "originalCents", "reversedCents", "status", "createdAt", "availableAt", "programSnapshot", "explanation" ] } } }, "required": [ "result", "rewards" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "result": { "type": "object", "properties": { "eventId": { "type": "string" }, "orderId": { "type": "string" }, "duplicate": { "type": "boolean" }, "customerOrderNumber": { "type": "number", "description": "Completions only. The purchase number Grizzlee gave the order." }, "incentiveFlag": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "const": "no_reservation" }, { "type": "string", "const": "reservation_expired" }, { "type": "string", "const": "reservation_released" }, { "type": "string", "const": "reservation_consumed" }, { "type": "string", "const": "reservation_locked" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "exceeds_terms" }, { "type": "string", "const": "category_not_eligible" } ] }, "rewardId": { "type": "string" }, "programId": { "type": "string", "description": "Program of the reservation or referral checked. Absent for no_referral." }, "reservationId": { "type": "string", "description": "The reservation sent with the order, when there was one." }, "maxCents": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Largest discount the terms allow on one order. Null when they set no cap or there are no terms." }, "reportedCents": { "type": "number", "description": "incentiveAppliedCents as the merchant reported it." } }, "required": [ "reason", "maxCents", "reportedCents" ], "description": "Completions only. Present when incentiveAppliedCents did not match the reservation." }, "decisions": { "type": "array", "items": { "type": "object", "properties": { "programId": { "type": "string" }, "programName": { "type": "string" }, "partnerId": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string", "const": "skipped" }, { "type": "string", "const": "rewarded" } ] }, "reason": { "type": "string" }, "reasonParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "no_referral" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" }, { "type": "string", "const": "no_order_referral" }, { "type": "string", "const": "no_customer_referral" }, { "type": "string", "const": "partner_not_in_program" }, { "type": "string", "const": "self_referral_blocked" }, { "type": "string", "const": "fraud_blocked" }, { "type": "string", "const": "milestone_before_referral" }, { "type": "string", "const": "order_before_referral" }, { "type": "string", "const": "report_value_missing" }, { "type": "string", "const": "milestone_window_expired" }, { "type": "string", "const": "order_window_expired" }, { "type": "string", "const": "milestone_progress" }, { "type": "string", "const": "report_limit_reached" }, { "type": "string", "const": "milestone_already_rewarded" }, { "type": "string", "const": "report_value_no_reward" }, { "type": "string", "const": "customer_cap_reached" }, { "type": "string", "const": "partner_cap_reached" }, { "type": "string", "const": "category_excluded" }, { "type": "string", "const": "categories_missing" }, { "type": "string", "const": "categories_required" }, { "type": "string", "const": "first_order_only" }, { "type": "string", "const": "first_order_after_referral_only" }, { "type": "string", "const": "first_orders_only" }, { "type": "string", "const": "first_orders_after_referral_only" }, { "type": "string", "const": "duration_ended" }, { "type": "string", "const": "rate_no_reward" }, { "type": "string", "const": "order_no_reward" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "reason as codes. Absent on decisions made before codes existed." }, "amountCents": { "type": "number" }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. blocked comes with a\nskipped outcome. review comes with a reward held as pending. flagged comes with a reward that\nfollows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. blocked comes with a skipped outcome. review comes with a\nreward held as pending. flagged comes with a reward that follows the program's usual approval." }, "milestoneCount": { "type": "number", "description": "Milestone decisions that reached the count check: the person's reports that count for this\nprogram, at or after the referral and not reversed, this report included." }, "milestoneThreshold": { "type": "number", "description": "The effective bonus count, or 1 for each-report-only programs." } }, "required": [ "programId", "programName", "outcome", "reason", "amountCents" ] } }, "rewardIds": { "type": "array", "items": { "type": "string" } }, "reversalCents": { "type": "number" }, "restoredCents": { "type": "number", "description": "Reward amount given back because the order's cumulative refund total went down." }, "increasedCents": { "type": "number", "description": "Adjustments only. Reward value a higher order total added. Lower totals report reversalCents." }, "stale": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "True when a refund or adjustment event was older than the latest applied one of its kind for\nthe order and changed nothing." }, "referralSelection": { "type": "object", "properties": { "winner": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "programId": { "type": "string" }, "partnerId": { "type": "string" }, "occurredAt": { "type": "string" }, "type": { "anyOf": [ { "type": "string", "const": "code" }, { "type": "string", "const": "receipt" } ] }, "providerPromoCodeId": { "type": "string" }, "index": { "type": "number", "description": "Absent when the customer's recorded attribution is retained." } }, "required": [ "programId", "partnerId", "occurredAt" ] } ] }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "number" }, "reason": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "invalid" }, { "type": "string", "const": "self_referral" }, { "type": "string", "const": "wrong_program" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "fraud" }, { "type": "string", "const": "customer_already_referred" }, { "type": "string", "const": "older" } ] } }, "required": [ "index", "reason" ] } } }, "required": [ "winner", "skipped" ] } }, "required": [ "eventId", "orderId", "duplicate", "decisions", "rewardIds", "reversalCents" ] }, "rewards": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The order that earned the reward. Absent on milestone rewards." }, "milestone": { "type": "string", "description": "The milestone that earned the reward. Absent on order rewards. Exactly one of the two is set." }, "reportEventId": { "type": "string", "description": "Each-report rewards name their source. Absent on at-count bonuses." }, "milestoneReportReversed": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "valueCents": { "type": "number" }, "milestoneCount": { "type": "number", "description": "Milestone rewards: the person's reports of the milestone that count for this program now,\nthose at or after the referral minus reversed ones. Grizzlee updates it with every report,\nreversal, revocation and reinstatement for the person and milestone. Absent on rewards no\nmilestone event has touched since milestones were counted." }, "milestoneRevoked": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "Milestone rewards: true while the milestone is revoked for the person. Updated with\nmilestoneCount. Absent when not revoked, and on rewards no milestone event has touched since\nmilestones were counted." }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "customerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ] }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "expiresAt" ], "description": "Offer rewards only. Terms copied when earned. Later program edits leave them alone." }, "originalCents": { "type": "number", "description": "What the reward earned when it was created. Never changes." }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added to or removed from originalCents. Absent until the\norder is adjusted. The reward is worth originalCents + adjustedCents - reversedCents." }, "reversedCents": { "type": "number", "description": "Reversed by refunds, a rejection or a milestone revocation." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. With action review the\nreward started pending and waits for someone to approve or reject it, and automatic approval\nskips it. With action flagged it follows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. rules lists each rule ID with its signal types, never values.\nWith action review the reward started pending, waits for someone to approve or reject it, and\nautomatic approval skips it. With action flagged it follows the program's usual approval." }, "rejectedAt": { "type": "string", "description": "When someone rejected the pending reward. A rejected reward is reversed for good." }, "rejectionReason": { "type": "string", "description": "Why it was rejected, as entered." }, "statusBeforeReversal": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "approved" } ], "description": "Status the reward had when a refund fully reversed it. A later restoration returns it to this status." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Delivery mode when earned. Absent on older money rewards, which use the Grizzlee wallet. Absent on offer rewards. Readers ignore delivery for offers." }, "createdAt": { "type": "string" }, "availableAt": { "type": "string", "description": "Rewards no longer have a hold, so new rewards use createdAt. Older rewards keep their original date." }, "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" ] }, "programVersion": { "type": "number", "description": "The program version the reward was earned under. Absent on rewards earned before programs had\nversions. programSnapshot holds their rules either way." }, "historicalBasis": { "type": "string", "const": "total", "description": "Historical subtotal rewards keep their reporting-total basis for refunds and adjustments." }, "basisCents": { "type": "number" }, "explanation": { "type": "string" }, "explanationParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "explanation as codes. Absent on rewards earned before codes existed." }, "calculation": { "type": "object", "properties": { "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" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "Saved for fixed reward refunds. Older rewards default to prorate." }, "phaseAfterMonths": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "minValue": { "type": "number" }, "bonusBps": { "type": "number" }, "value": { "type": "number" } }, "required": [ "name", "minValue", "bonusBps", "value" ] }, "customTerms": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "string", "const": "partner" }, { "type": "string", "const": "customer" } ] }, "targetId": { "type": "string" } }, "required": [ "target", "targetId" ] }, "uncappedCents": { "type": "number" }, "customerCapCents": { "type": "number" }, "partnerCapCents": { "type": "number" } }, "required": [ "compensation", "uncappedCents" ] } }, "required": [ "id", "companyId", "programId", "partnerId", "customerId", "currency", "rewardType", "originalCents", "reversedCents", "status", "createdAt", "availableAt", "programSnapshot", "explanation" ] } } }, "required": [ "result", "rewards" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/rewards/{id}/approve": { "post": { "operationId": "approveReward", "summary": "approveReward", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "rewards:approve" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The order that earned the reward. Absent on milestone rewards." }, "milestone": { "type": "string", "description": "The milestone that earned the reward. Absent on order rewards. Exactly one of the two is set." }, "reportEventId": { "type": "string", "description": "Each-report rewards name their source. Absent on at-count bonuses." }, "milestoneReportReversed": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "valueCents": { "type": "number" }, "milestoneCount": { "type": "number", "description": "Milestone rewards: the person's reports of the milestone that count for this program now,\nthose at or after the referral minus reversed ones. Grizzlee updates it with every report,\nreversal, revocation and reinstatement for the person and milestone. Absent on rewards no\nmilestone event has touched since milestones were counted." }, "milestoneRevoked": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "Milestone rewards: true while the milestone is revoked for the person. Updated with\nmilestoneCount. Absent when not revoked, and on rewards no milestone event has touched since\nmilestones were counted." }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "customerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ] }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "expiresAt" ], "description": "Offer rewards only. Terms copied when earned. Later program edits leave them alone." }, "originalCents": { "type": "number", "description": "What the reward earned when it was created. Never changes." }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added to or removed from originalCents. Absent until the\norder is adjusted. The reward is worth originalCents + adjustedCents - reversedCents." }, "reversedCents": { "type": "number", "description": "Reversed by refunds, a rejection or a milestone revocation." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. With action review the\nreward started pending and waits for someone to approve or reject it, and automatic approval\nskips it. With action flagged it follows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. rules lists each rule ID with its signal types, never values.\nWith action review the reward started pending, waits for someone to approve or reject it, and\nautomatic approval skips it. With action flagged it follows the program's usual approval." }, "rejectedAt": { "type": "string", "description": "When someone rejected the pending reward. A rejected reward is reversed for good." }, "rejectionReason": { "type": "string", "description": "Why it was rejected, as entered." }, "statusBeforeReversal": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "approved" } ], "description": "Status the reward had when a refund fully reversed it. A later restoration returns it to this status." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Delivery mode when earned. Absent on older money rewards, which use the Grizzlee wallet. Absent on offer rewards. Readers ignore delivery for offers." }, "createdAt": { "type": "string" }, "availableAt": { "type": "string", "description": "Rewards no longer have a hold, so new rewards use createdAt. Older rewards keep their original date." }, "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" ] }, "programVersion": { "type": "number", "description": "The program version the reward was earned under. Absent on rewards earned before programs had\nversions. programSnapshot holds their rules either way." }, "historicalBasis": { "type": "string", "const": "total", "description": "Historical subtotal rewards keep their reporting-total basis for refunds and adjustments." }, "basisCents": { "type": "number" }, "explanation": { "type": "string" }, "explanationParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "explanation as codes. Absent on rewards earned before codes existed." }, "calculation": { "type": "object", "properties": { "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" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "Saved for fixed reward refunds. Older rewards default to prorate." }, "phaseAfterMonths": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "minValue": { "type": "number" }, "bonusBps": { "type": "number" }, "value": { "type": "number" } }, "required": [ "name", "minValue", "bonusBps", "value" ] }, "customTerms": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "string", "const": "partner" }, { "type": "string", "const": "customer" } ] }, "targetId": { "type": "string" } }, "required": [ "target", "targetId" ] }, "uncappedCents": { "type": "number" }, "customerCapCents": { "type": "number" }, "partnerCapCents": { "type": "number" } }, "required": [ "compensation", "uncappedCents" ] } }, "required": [ "id", "companyId", "programId", "partnerId", "customerId", "currency", "rewardType", "originalCents", "reversedCents", "status", "createdAt", "availableAt", "programSnapshot", "explanation" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The order that earned the reward. Absent on milestone rewards." }, "milestone": { "type": "string", "description": "The milestone that earned the reward. Absent on order rewards. Exactly one of the two is set." }, "reportEventId": { "type": "string", "description": "Each-report rewards name their source. Absent on at-count bonuses." }, "milestoneReportReversed": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "valueCents": { "type": "number" }, "milestoneCount": { "type": "number", "description": "Milestone rewards: the person's reports of the milestone that count for this program now,\nthose at or after the referral minus reversed ones. Grizzlee updates it with every report,\nreversal, revocation and reinstatement for the person and milestone. Absent on rewards no\nmilestone event has touched since milestones were counted." }, "milestoneRevoked": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "Milestone rewards: true while the milestone is revoked for the person. Updated with\nmilestoneCount. Absent when not revoked, and on rewards no milestone event has touched since\nmilestones were counted." }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "customerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ] }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "expiresAt" ], "description": "Offer rewards only. Terms copied when earned. Later program edits leave them alone." }, "originalCents": { "type": "number", "description": "What the reward earned when it was created. Never changes." }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added to or removed from originalCents. Absent until the\norder is adjusted. The reward is worth originalCents + adjustedCents - reversedCents." }, "reversedCents": { "type": "number", "description": "Reversed by refunds, a rejection or a milestone revocation." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. With action review the\nreward started pending and waits for someone to approve or reject it, and automatic approval\nskips it. With action flagged it follows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. rules lists each rule ID with its signal types, never values.\nWith action review the reward started pending, waits for someone to approve or reject it, and\nautomatic approval skips it. With action flagged it follows the program's usual approval." }, "rejectedAt": { "type": "string", "description": "When someone rejected the pending reward. A rejected reward is reversed for good." }, "rejectionReason": { "type": "string", "description": "Why it was rejected, as entered." }, "statusBeforeReversal": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "approved" } ], "description": "Status the reward had when a refund fully reversed it. A later restoration returns it to this status." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Delivery mode when earned. Absent on older money rewards, which use the Grizzlee wallet. Absent on offer rewards. Readers ignore delivery for offers." }, "createdAt": { "type": "string" }, "availableAt": { "type": "string", "description": "Rewards no longer have a hold, so new rewards use createdAt. Older rewards keep their original date." }, "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" ] }, "programVersion": { "type": "number", "description": "The program version the reward was earned under. Absent on rewards earned before programs had\nversions. programSnapshot holds their rules either way." }, "historicalBasis": { "type": "string", "const": "total", "description": "Historical subtotal rewards keep their reporting-total basis for refunds and adjustments." }, "basisCents": { "type": "number" }, "explanation": { "type": "string" }, "explanationParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "explanation as codes. Absent on rewards earned before codes existed." }, "calculation": { "type": "object", "properties": { "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" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "Saved for fixed reward refunds. Older rewards default to prorate." }, "phaseAfterMonths": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "minValue": { "type": "number" }, "bonusBps": { "type": "number" }, "value": { "type": "number" } }, "required": [ "name", "minValue", "bonusBps", "value" ] }, "customTerms": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "string", "const": "partner" }, { "type": "string", "const": "customer" } ] }, "targetId": { "type": "string" } }, "required": [ "target", "targetId" ] }, "uncappedCents": { "type": "number" }, "customerCapCents": { "type": "number" }, "partnerCapCents": { "type": "number" } }, "required": [ "compensation", "uncappedCents" ] } }, "required": [ "id", "companyId", "programId", "partnerId", "customerId", "currency", "rewardType", "originalCents", "reversedCents", "status", "createdAt", "availableAt", "programSnapshot", "explanation" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/rewards/{id}/reject": { "post": { "operationId": "rejectReward", "summary": "Rejects a pending reward, such as one held for a self-referral review. The reward is reversed\nfor good and sends reward.reversed. Repeating it returns the same reward.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "rewards:approve" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "additionalProperties": false }, "example": { "reason": "Merchant review" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The order that earned the reward. Absent on milestone rewards." }, "milestone": { "type": "string", "description": "The milestone that earned the reward. Absent on order rewards. Exactly one of the two is set." }, "reportEventId": { "type": "string", "description": "Each-report rewards name their source. Absent on at-count bonuses." }, "milestoneReportReversed": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "valueCents": { "type": "number" }, "milestoneCount": { "type": "number", "description": "Milestone rewards: the person's reports of the milestone that count for this program now,\nthose at or after the referral minus reversed ones. Grizzlee updates it with every report,\nreversal, revocation and reinstatement for the person and milestone. Absent on rewards no\nmilestone event has touched since milestones were counted." }, "milestoneRevoked": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "Milestone rewards: true while the milestone is revoked for the person. Updated with\nmilestoneCount. Absent when not revoked, and on rewards no milestone event has touched since\nmilestones were counted." }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "customerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ] }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "expiresAt" ], "description": "Offer rewards only. Terms copied when earned. Later program edits leave them alone." }, "originalCents": { "type": "number", "description": "What the reward earned when it was created. Never changes." }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added to or removed from originalCents. Absent until the\norder is adjusted. The reward is worth originalCents + adjustedCents - reversedCents." }, "reversedCents": { "type": "number", "description": "Reversed by refunds, a rejection or a milestone revocation." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. With action review the\nreward started pending and waits for someone to approve or reject it, and automatic approval\nskips it. With action flagged it follows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. rules lists each rule ID with its signal types, never values.\nWith action review the reward started pending, waits for someone to approve or reject it, and\nautomatic approval skips it. With action flagged it follows the program's usual approval." }, "rejectedAt": { "type": "string", "description": "When someone rejected the pending reward. A rejected reward is reversed for good." }, "rejectionReason": { "type": "string", "description": "Why it was rejected, as entered." }, "statusBeforeReversal": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "approved" } ], "description": "Status the reward had when a refund fully reversed it. A later restoration returns it to this status." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Delivery mode when earned. Absent on older money rewards, which use the Grizzlee wallet. Absent on offer rewards. Readers ignore delivery for offers." }, "createdAt": { "type": "string" }, "availableAt": { "type": "string", "description": "Rewards no longer have a hold, so new rewards use createdAt. Older rewards keep their original date." }, "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" ] }, "programVersion": { "type": "number", "description": "The program version the reward was earned under. Absent on rewards earned before programs had\nversions. programSnapshot holds their rules either way." }, "historicalBasis": { "type": "string", "const": "total", "description": "Historical subtotal rewards keep their reporting-total basis for refunds and adjustments." }, "basisCents": { "type": "number" }, "explanation": { "type": "string" }, "explanationParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "explanation as codes. Absent on rewards earned before codes existed." }, "calculation": { "type": "object", "properties": { "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" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "Saved for fixed reward refunds. Older rewards default to prorate." }, "phaseAfterMonths": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "minValue": { "type": "number" }, "bonusBps": { "type": "number" }, "value": { "type": "number" } }, "required": [ "name", "minValue", "bonusBps", "value" ] }, "customTerms": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "string", "const": "partner" }, { "type": "string", "const": "customer" } ] }, "targetId": { "type": "string" } }, "required": [ "target", "targetId" ] }, "uncappedCents": { "type": "number" }, "customerCapCents": { "type": "number" }, "partnerCapCents": { "type": "number" } }, "required": [ "compensation", "uncappedCents" ] } }, "required": [ "id", "companyId", "programId", "partnerId", "customerId", "currency", "rewardType", "originalCents", "reversedCents", "status", "createdAt", "availableAt", "programSnapshot", "explanation" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "orderId": { "type": "string", "description": "The order that earned the reward. Absent on milestone rewards." }, "milestone": { "type": "string", "description": "The milestone that earned the reward. Absent on order rewards. Exactly one of the two is set." }, "reportEventId": { "type": "string", "description": "Each-report rewards name their source. Absent on at-count bonuses." }, "milestoneReportReversed": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ] }, "valueCents": { "type": "number" }, "milestoneCount": { "type": "number", "description": "Milestone rewards: the person's reports of the milestone that count for this program now,\nthose at or after the referral minus reversed ones. Grizzlee updates it with every report,\nreversal, revocation and reinstatement for the person and milestone. Absent on rewards no\nmilestone event has touched since milestones were counted." }, "milestoneRevoked": { "anyOf": [ { "type": "boolean", "const": false }, { "type": "boolean", "const": true } ], "description": "Milestone rewards: true while the milestone is revoked for the person. Updated with\nmilestoneCount. Absent when not revoked, and on rewards no milestone event has touched since\nmilestones were counted." }, "programId": { "type": "string" }, "partnerId": { "type": "string" }, "customerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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." } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund" ] }, { "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." } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents" ] } ] }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "expiresAt" ], "description": "Offer rewards only. Terms copied when earned. Later program edits leave them alone." }, "originalCents": { "type": "number", "description": "What the reward earned when it was created. Never changes." }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added to or removed from originalCents. Absent until the\norder is adjusted. The reward is worth originalCents + adjustedCents - reversedCents." }, "reversedCents": { "type": "number", "description": "Reversed by refunds, a rejection or a milestone revocation." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "selfReferral": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" }, { "type": "string", "const": "customer_id" } ] } } }, "required": [ "action", "signals" ], "description": "Present when the customer's identity signals matched the partner's. With action review the\nreward started pending and waits for someone to approve or reject it, and automatic approval\nskips it. With action flagged it follows the program's usual approval." }, "fraud": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rules": { "type": "array", "items": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "const": "blocked" }, { "type": "string", "const": "review" }, { "type": "string", "const": "flagged" } ] }, "rule": { "anyOf": [ { "type": "string", "const": "duplicate_accounts" }, { "type": "string", "const": "rapid_repeats" }, { "type": "string", "const": "repeat_customer" }, { "type": "string", "const": "disposable_email" } ] }, "signals": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "email" }, { "type": "string", "const": "phone" }, { "type": "string", "const": "card" }, { "type": "string", "const": "device" }, { "type": "string", "const": "ip" } ] }, "description": "Matching signal types, never values. Empty for disposable_email." }, "count": { "type": "number", "description": "Customers counted, this one included when referred inside the window. Velocity rules only." } }, "required": [ "action", "rule", "signals" ] } } }, "required": [ "action", "rules" ], "description": "Present when fraud rules fired. rules lists each rule ID with its signal types, never values.\nWith action review the reward started pending, waits for someone to approve or reject it, and\nautomatic approval skips it. With action flagged it follows the program's usual approval." }, "rejectedAt": { "type": "string", "description": "When someone rejected the pending reward. A rejected reward is reversed for good." }, "rejectionReason": { "type": "string", "description": "Why it was rejected, as entered." }, "statusBeforeReversal": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "approved" } ], "description": "Status the reward had when a refund fully reversed it. A later restoration returns it to this status." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Delivery mode when earned. Absent on older money rewards, which use the Grizzlee wallet. Absent on offer rewards. Readers ignore delivery for offers." }, "createdAt": { "type": "string" }, "availableAt": { "type": "string", "description": "Rewards no longer have a hold, so new rewards use createdAt. Older rewards keep their original date." }, "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" ] }, "programVersion": { "type": "number", "description": "The program version the reward was earned under. Absent on rewards earned before programs had\nversions. programSnapshot holds their rules either way." }, "historicalBasis": { "type": "string", "const": "total", "description": "Historical subtotal rewards keep their reporting-total basis for refunds and adjustments." }, "basisCents": { "type": "number" }, "explanation": { "type": "string" }, "explanationParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "fixed" }, { "type": "string", "const": "percentage" }, { "type": "string", "const": "offer" }, { "type": "string", "const": "report" }, { "type": "string", "const": "report_percentage" }, { "type": "string", "const": "milestone_bonus" }, { "type": "string", "const": "schedule_month" }, { "type": "string", "const": "tier_bonus" }, { "type": "string", "const": "custom_partner_terms" }, { "type": "string", "const": "custom_customer_terms" }, { "type": "string", "const": "capped" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "explanation as codes. Absent on rewards earned before codes existed." }, "calculation": { "type": "object", "properties": { "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" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "Saved for fixed reward refunds. Older rewards default to prorate." }, "phaseAfterMonths": { "type": "number" }, "tier": { "type": "object", "properties": { "name": { "type": "string" }, "minValue": { "type": "number" }, "bonusBps": { "type": "number" }, "value": { "type": "number" } }, "required": [ "name", "minValue", "bonusBps", "value" ] }, "customTerms": { "type": "object", "properties": { "target": { "anyOf": [ { "type": "string", "const": "partner" }, { "type": "string", "const": "customer" } ] }, "targetId": { "type": "string" } }, "required": [ "target", "targetId" ] }, "uncappedCents": { "type": "number" }, "customerCapCents": { "type": "number" }, "partnerCapCents": { "type": "number" } }, "required": [ "compensation", "uncappedCents" ] } }, "required": [ "id", "companyId", "programId", "partnerId", "customerId", "currency", "rewardType", "originalCents", "reversedCents", "status", "createdAt", "availableAt", "programSnapshot", "explanation" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/rewards/{rewardId}/deliveries": { "post": { "operationId": "deliverReward", "summary": "Confirm that you delivered a merchant-mode reward. Needs the rewards:deliver scope.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "rewards:deliver" ], "parameters": [ { "name": "rewardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "delivered" }, "externalReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "deliveredAt": { "type": "string", "format": "date-time" }, "nettedDebtCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "status", "externalReference" ], "additionalProperties": false }, { "type": "object", "properties": { "status": { "type": "string", "const": "failed" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 }, "externalReference": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "status", "reason", "externalReference" ], "additionalProperties": false } ] }, "example": { "status": "delivered", "externalReference": "externalReference-example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "type": "string", "description": "New attempts require a reference. Older failures may have none." }, "amountCents": { "type": "number", "description": "Gross amount delivered, amount owed for a failure, or cash returned by a transfer reversal." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "deliveredAt": { "type": "string", "description": "Present when delivered." }, "failureReason": { "type": "string", "description": "Present when failed." }, "nettedDebtCents": { "type": "number", "description": "Present when a delivery settled part of the partner's earlier delivery debt." }, "payoutId": { "type": "string", "description": "Present when a paid merchant payout recorded this delivery." }, "reversalOfId": { "type": "string", "description": "Original delivery this append-only transfer reversal reduces." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "partnerId", "status", "amountCents", "currency", "rewardType", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "type": "string", "description": "New attempts require a reference. Older failures may have none." }, "amountCents": { "type": "number", "description": "Gross amount delivered, amount owed for a failure, or cash returned by a transfer reversal." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "deliveredAt": { "type": "string", "description": "Present when delivered." }, "failureReason": { "type": "string", "description": "Present when failed." }, "nettedDebtCents": { "type": "number", "description": "Present when a delivery settled part of the partner's earlier delivery debt." }, "payoutId": { "type": "string", "description": "Present when a paid merchant payout recorded this delivery." }, "reversalOfId": { "type": "string", "description": "Original delivery this append-only transfer reversal reduces." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "partnerId", "status", "amountCents", "currency", "rewardType", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "get": { "operationId": "listRewardDeliveries", "summary": "Delivery attempts and delivery debts for one reward.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "rewards:deliver" ], "parameters": [ { "name": "rewardId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "rewardId": { "type": "string" }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "type": "string", "description": "New attempts require a reference. Older failures may have none." }, "amountCents": { "type": "number", "description": "Gross amount delivered, amount owed for a failure, or cash returned by a transfer reversal." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "deliveredAt": { "type": "string", "description": "Present when delivered." }, "failureReason": { "type": "string", "description": "Present when failed." }, "nettedDebtCents": { "type": "number", "description": "Present when a delivery settled part of the partner's earlier delivery debt." }, "payoutId": { "type": "string", "description": "Present when a paid merchant payout recorded this delivery." }, "reversalOfId": { "type": "string", "description": "Original delivery this append-only transfer reversal reduces." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "partnerId", "status", "amountCents", "currency", "rewardType", "createdAt" ] }, "description": "Oldest first." }, "debts": { "type": "array", "items": { "type": "object", "properties": { "outstandingCents": { "type": "number", "description": "amountCents minus every settlement." }, "settlements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "debtId": { "type": "string" }, "partnerId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "restored" }, { "type": "string", "const": "netted" }, { "type": "string", "const": "recovered" } ] }, "amountCents": { "type": "number" }, "externalReference": { "type": "string", "description": "Present on recovered settlements." }, "deliveryId": { "type": "string", "description": "Present on netted settlements." }, "eventId": { "type": "string", "description": "Reward restoration or transfer reversal event. Present on restored settlements." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "debtId", "partnerId", "kind", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "deliveryId": { "type": "string", "description": "The delivered record the reversal applies to." }, "eventId": { "type": "string", "description": "Refund event that reversed the delivered amount." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "outstandingCents", "settlements", "id", "companyId", "partnerId", "rewardId", "deliveryId", "eventId", "currency", "rewardType", "amountCents", "createdAt" ] }, "description": "Debts from reversals after delivery, oldest first." } }, "required": [ "rewardId", "deliveryMode", "deliveries", "debts" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "rewardId": { "type": "string" }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "type": "string", "description": "New attempts require a reference. Older failures may have none." }, "amountCents": { "type": "number", "description": "Gross amount delivered, amount owed for a failure, or cash returned by a transfer reversal." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "deliveredAt": { "type": "string", "description": "Present when delivered." }, "failureReason": { "type": "string", "description": "Present when failed." }, "nettedDebtCents": { "type": "number", "description": "Present when a delivery settled part of the partner's earlier delivery debt." }, "payoutId": { "type": "string", "description": "Present when a paid merchant payout recorded this delivery." }, "reversalOfId": { "type": "string", "description": "Original delivery this append-only transfer reversal reduces." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "partnerId", "status", "amountCents", "currency", "rewardType", "createdAt" ] }, "description": "Oldest first." }, "debts": { "type": "array", "items": { "type": "object", "properties": { "outstandingCents": { "type": "number", "description": "amountCents minus every settlement." }, "settlements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "debtId": { "type": "string" }, "partnerId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "restored" }, { "type": "string", "const": "netted" }, { "type": "string", "const": "recovered" } ] }, "amountCents": { "type": "number" }, "externalReference": { "type": "string", "description": "Present on recovered settlements." }, "deliveryId": { "type": "string", "description": "Present on netted settlements." }, "eventId": { "type": "string", "description": "Reward restoration or transfer reversal event. Present on restored settlements." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "debtId", "partnerId", "kind", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "deliveryId": { "type": "string", "description": "The delivered record the reversal applies to." }, "eventId": { "type": "string", "description": "Refund event that reversed the delivered amount." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "outstandingCents", "settlements", "id", "companyId", "partnerId", "rewardId", "deliveryId", "eventId", "currency", "rewardType", "amountCents", "createdAt" ] }, "description": "Debts from reversals after delivery, oldest first." } }, "required": [ "rewardId", "deliveryMode", "deliveries", "debts" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/debts/{debtId}/recover": { "post": { "operationId": "recoverPartnerDebt", "summary": "Mark a partner's delivery debt as recovered outside a delivery.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "rewards:deliver" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "debtId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "externalReference" ], "additionalProperties": false }, "example": { "externalReference": "externalReference-example", "amountCents": 10000 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "outstandingCents": { "type": "number", "description": "amountCents minus every settlement." }, "settlements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "debtId": { "type": "string" }, "partnerId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "restored" }, { "type": "string", "const": "netted" }, { "type": "string", "const": "recovered" } ] }, "amountCents": { "type": "number" }, "externalReference": { "type": "string", "description": "Present on recovered settlements." }, "deliveryId": { "type": "string", "description": "Present on netted settlements." }, "eventId": { "type": "string", "description": "Reward restoration or transfer reversal event. Present on restored settlements." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "debtId", "partnerId", "kind", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "deliveryId": { "type": "string", "description": "The delivered record the reversal applies to." }, "eventId": { "type": "string", "description": "Refund event that reversed the delivered amount." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "outstandingCents", "settlements", "id", "companyId", "partnerId", "rewardId", "deliveryId", "eventId", "currency", "rewardType", "amountCents", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "outstandingCents": { "type": "number", "description": "amountCents minus every settlement." }, "settlements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "debtId": { "type": "string" }, "partnerId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "restored" }, { "type": "string", "const": "netted" }, { "type": "string", "const": "recovered" } ] }, "amountCents": { "type": "number" }, "externalReference": { "type": "string", "description": "Present on recovered settlements." }, "deliveryId": { "type": "string", "description": "Present on netted settlements." }, "eventId": { "type": "string", "description": "Reward restoration or transfer reversal event. Present on restored settlements." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "debtId", "partnerId", "kind", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "deliveryId": { "type": "string", "description": "The delivered record the reversal applies to." }, "eventId": { "type": "string", "description": "Refund event that reversed the delivered amount." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "outstandingCents", "settlements", "id", "companyId", "partnerId", "rewardId", "deliveryId", "eventId", "currency", "rewardType", "amountCents", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/credit/deliveries": { "post": { "operationId": "deliverPartnerCredit", "summary": "Confirm credit added to merchant billing. Allocates oldest approval first. Needs rewards:deliver.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "rewards:deliver" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "currency": { "type": "string", "enum": [ "CAD", "USD", "EUR", "GBP" ] } }, "required": [ "externalReference", "amountCents", "currency" ], "additionalProperties": false }, "example": { "externalReference": "externalReference-example", "amountCents": 10000, "currency": "CAD" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "partnerId": { "type": "string" }, "externalReference": { "type": "string" }, "amountCents": { "type": "number" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "type": "string", "description": "New attempts require a reference. Older failures may have none." }, "amountCents": { "type": "number", "description": "Gross amount delivered, amount owed for a failure, or cash returned by a transfer reversal." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "deliveredAt": { "type": "string", "description": "Present when delivered." }, "failureReason": { "type": "string", "description": "Present when failed." }, "nettedDebtCents": { "type": "number", "description": "Present when a delivery settled part of the partner's earlier delivery debt." }, "payoutId": { "type": "string", "description": "Present when a paid merchant payout recorded this delivery." }, "reversalOfId": { "type": "string", "description": "Original delivery this append-only transfer reversal reduces." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "partnerId", "status", "amountCents", "currency", "rewardType", "createdAt" ] }, "description": "One delivery per allocated reward, oldest approval first." } }, "required": [ "partnerId", "externalReference", "amountCents", "currency", "deliveries" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "partnerId": { "type": "string" }, "externalReference": { "type": "string" }, "amountCents": { "type": "number" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "rewardId": { "type": "string" }, "partnerId": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "type": "string", "description": "New attempts require a reference. Older failures may have none." }, "amountCents": { "type": "number", "description": "Gross amount delivered, amount owed for a failure, or cash returned by a transfer reversal." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "deliveredAt": { "type": "string", "description": "Present when delivered." }, "failureReason": { "type": "string", "description": "Present when failed." }, "nettedDebtCents": { "type": "number", "description": "Present when a delivery settled part of the partner's earlier delivery debt." }, "payoutId": { "type": "string", "description": "Present when a paid merchant payout recorded this delivery." }, "reversalOfId": { "type": "string", "description": "Original delivery this append-only transfer reversal reduces." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "rewardId", "partnerId", "status", "amountCents", "currency", "rewardType", "createdAt" ] }, "description": "One delivery per allocated reward, oldest approval first." } }, "required": [ "partnerId", "externalReference", "amountCents", "currency", "deliveries" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/debts/recover": { "post": { "operationId": "recoverPartnerDebts", "summary": "Recover delivery debts of one type, oldest first. Needs rewards:deliver.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "rewards:deliver" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalReference": { "type": "string", "minLength": 1, "maxLength": 200 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "currency": { "type": "string", "enum": [ "CAD", "USD", "EUR", "GBP" ] }, "rewardType": { "type": "string", "enum": [ "cash", "credit" ] } }, "required": [ "externalReference", "amountCents", "currency", "rewardType" ], "additionalProperties": false }, "example": { "externalReference": "externalReference-example", "amountCents": 10000, "currency": "CAD", "rewardType": "cash" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "partnerId": { "type": "string" }, "externalReference": { "type": "string" }, "amountCents": { "type": "number" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "settlements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "debtId": { "type": "string" }, "partnerId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "restored" }, { "type": "string", "const": "netted" }, { "type": "string", "const": "recovered" } ] }, "amountCents": { "type": "number" }, "externalReference": { "type": "string", "description": "Present on recovered settlements." }, "deliveryId": { "type": "string", "description": "Present on netted settlements." }, "eventId": { "type": "string", "description": "Reward restoration or transfer reversal event. Present on restored settlements." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "debtId", "partnerId", "kind", "amountCents", "createdAt" ] }, "description": "One settlement per allocated debt, oldest debt first." } }, "required": [ "partnerId", "externalReference", "amountCents", "currency", "rewardType", "settlements" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "partnerId": { "type": "string" }, "externalReference": { "type": "string" }, "amountCents": { "type": "number" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "settlements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "debtId": { "type": "string" }, "partnerId": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "const": "restored" }, { "type": "string", "const": "netted" }, { "type": "string", "const": "recovered" } ] }, "amountCents": { "type": "number" }, "externalReference": { "type": "string", "description": "Present on recovered settlements." }, "deliveryId": { "type": "string", "description": "Present on netted settlements." }, "eventId": { "type": "string", "description": "Reward restoration or transfer reversal event. Present on restored settlements." }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "debtId", "partnerId", "kind", "amountCents", "createdAt" ] }, "description": "One settlement per allocated debt, oldest debt first." } }, "required": [ "partnerId", "externalReference", "amountCents", "currency", "rewardType", "settlements" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/{id}/payouts": { "post": { "operationId": "createPartnerPayout", "summary": "Create a payout. Retrying with the same eventId returns the original payout. Needs payouts:write.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "payouts:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "grizzlee_wallet" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "provider": { "type": "string", "enum": [ "manual", "stripe" ] }, "integrationId": { "type": "string", "format": "uuid" }, "destination": { "type": "string", "maxLength": 255, "pattern": "^acct_[A-Za-z0-9]+$" } }, "required": [ "mode", "eventId", "amountCents", "provider" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "merchant" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "rewardId": { "type": "string", "minLength": 1, "maxLength": 120 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "rewardId", "amountCents" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "nettedDebtCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "provider": { "type": "string", "enum": [ "manual", "stripe" ] }, "integrationId": { "type": "string", "format": "uuid" }, "destination": { "type": "string", "maxLength": 255, "pattern": "^acct_[A-Za-z0-9]+$" } }, "required": [ "mode", "eventId", "allocations" ], "additionalProperties": false } ] }, "example": { "mode": "grizzlee_wallet", "eventId": "payment-example", "amountCents": 10000, "provider": "manual" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "get": { "operationId": "listPartnerPayouts", "summary": "A partner's payouts, newest first. Pass nextCursor to read the next page. Needs read or\npayouts:write. Keys without payouts:write get payouts without the Stripe destination.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read", "payouts:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 400 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "payouts": { "type": "array", "items": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] }, "description": "Newest first." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "payouts", "nextCursor" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "payouts": { "type": "array", "items": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] }, "description": "Newest first." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "payouts", "nextCursor" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/payouts": { "post": { "operationId": "createPartnerPayoutByExternalId", "summary": "Create a payout. Retrying with the same eventId returns the original payout. Needs payouts:write.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "payouts:write" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "grizzlee_wallet" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "provider": { "type": "string", "enum": [ "manual", "stripe" ] }, "integrationId": { "type": "string", "format": "uuid" }, "destination": { "type": "string", "maxLength": 255, "pattern": "^acct_[A-Za-z0-9]+$" } }, "required": [ "mode", "eventId", "amountCents", "provider" ], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "type": "string", "const": "merchant" }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "rewardId": { "type": "string", "minLength": 1, "maxLength": 120 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "rewardId", "amountCents" ], "additionalProperties": false }, "minItems": 1, "maxItems": 500 }, "amountCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "nettedDebtCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 }, "provider": { "type": "string", "enum": [ "manual", "stripe" ] }, "integrationId": { "type": "string", "format": "uuid" }, "destination": { "type": "string", "maxLength": 255, "pattern": "^acct_[A-Za-z0-9]+$" } }, "required": [ "mode", "eventId", "allocations" ], "additionalProperties": false } ] }, "example": { "mode": "grizzlee_wallet", "eventId": "payment-example", "amountCents": 10000, "provider": "manual" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "get": { "operationId": "listPartnerPayoutsByExternalId", "summary": "A partner's payouts, newest first. Pass nextCursor to read the next page. Needs read or\npayouts:write. Keys without payouts:write get payouts without the Stripe destination.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read", "payouts:write" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 400 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "payouts": { "type": "array", "items": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] }, "description": "Newest first." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "payouts", "nextCursor" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "payouts": { "type": "array", "items": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] }, "description": "Newest first." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "payouts", "nextCursor" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/payouts/{payoutId}/paid": { "post": { "operationId": "markPayoutPaid", "summary": "Record that the money reached the partner. Merchant payouts also mark their rewards delivered.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "payouts:write" ], "parameters": [ { "name": "payoutId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalReference": { "type": "string", "minLength": 1, "maxLength": 120 }, "paidAt": { "type": "string", "format": "date-time" } }, "required": [ "externalReference" ], "additionalProperties": false }, "example": { "externalReference": "externalReference-example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/payouts/{payoutId}/cancel": { "post": { "operationId": "cancelPayout", "summary": "Cancel an unpaid payout and free its wallet reservation or rewards.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "payouts:write" ], "parameters": [ { "name": "payoutId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmNoTransfer": { "type": "boolean" } }, "additionalProperties": false }, "example": { "confirmNoTransfer": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/payout-schedule": { "get": { "operationId": "getPayoutSchedule", "summary": "The company's payout terms and next run date. Needs read or payouts:write.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read", "payouts:write" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "frequency": { "type": "string", "const": "weekly" }, "weekday": { "anyOf": [ { "type": "string", "const": "monday" }, { "type": "string", "const": "tuesday" }, { "type": "string", "const": "wednesday" }, { "type": "string", "const": "thursday" }, { "type": "string", "const": "friday" }, { "type": "string", "const": "saturday" }, { "type": "string", "const": "sunday" } ], "description": "Day of the week the run is due, in UTC." }, "enabled": { "type": "boolean", "description": "false keeps the terms saved but creates no payouts." }, "minimumCents": { "type": "number", "description": "Smallest net transfer. A smaller balance rolls over to the next run." }, "holdPeriodDays": { "type": "number", "description": "Days a reward must have been approved before a run can pay it. A refund inside this window\nreverses the reward before it is paid. Program review holds are separate and come first.\nWallet cash rewards count as available for withdrawal only once they are this many days old,\nwhether or not the schedule is enabled. Terms saved before the default became 30 keep theirs." }, "stripeIntegrationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Stripe connection (integration ID) that sends scheduled payouts. When set, partners with a\nstripeAccountId are paid by a Stripe transfer from the merchant's Stripe balance, and other\npartners get a manual payout or wait, as missingStripeAccount says. Null keeps every scheduled\npayout manual." }, "missingStripeAccount": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "wait" } ], "description": "What a run does for a partner without a stripeAccountId while stripeIntegrationId is set.\nmanual, the default, creates a manual payout for the merchant to send. wait creates no payout:\nthe partner's rewards stay payable and roll over, and the first due date after the partner\ngets a stripeAccountId pays them by Stripe transfer. Hold period and minimum apply as usual.\nwait needs stripeIntegrationId." }, "activeSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the current terms took effect. Null while disabled." }, "lastRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the latest finished run." }, "nextRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the next run. Null while disabled." }, "updatedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until the terms are first saved." } }, "required": [ "frequency", "weekday", "enabled", "minimumCents", "holdPeriodDays", "stripeIntegrationId", "missingStripeAccount", "activeSince", "lastRunOn", "nextRunOn", "updatedAt" ] }, { "type": "object", "properties": { "frequency": { "type": "string", "const": "monthly" }, "enabled": { "type": "boolean", "description": "false keeps the terms saved but creates no payouts." }, "minimumCents": { "type": "number", "description": "Smallest net transfer. A smaller balance rolls over to the next run." }, "holdPeriodDays": { "type": "number", "description": "Days a reward must have been approved before a run can pay it. A refund inside this window\nreverses the reward before it is paid. Program review holds are separate and come first.\nWallet cash rewards count as available for withdrawal only once they are this many days old,\nwhether or not the schedule is enabled. Terms saved before the default became 30 keep theirs." }, "stripeIntegrationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Stripe connection (integration ID) that sends scheduled payouts. When set, partners with a\nstripeAccountId are paid by a Stripe transfer from the merchant's Stripe balance, and other\npartners get a manual payout or wait, as missingStripeAccount says. Null keeps every scheduled\npayout manual." }, "missingStripeAccount": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "wait" } ], "description": "What a run does for a partner without a stripeAccountId while stripeIntegrationId is set.\nmanual, the default, creates a manual payout for the merchant to send. wait creates no payout:\nthe partner's rewards stay payable and roll over, and the first due date after the partner\ngets a stripeAccountId pays them by Stripe transfer. Hold period and minimum apply as usual.\nwait needs stripeIntegrationId." }, "dayOfMonth": { "type": "number", "description": "Day of the month the run is due, in UTC. 1 to 28, so every month has it." }, "activeSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the current terms took effect. Null while disabled." }, "lastRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the latest finished run." }, "nextRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the next run. Null while disabled." }, "updatedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until the terms are first saved." } }, "required": [ "frequency", "enabled", "minimumCents", "holdPeriodDays", "stripeIntegrationId", "missingStripeAccount", "dayOfMonth", "activeSince", "lastRunOn", "nextRunOn", "updatedAt" ] } ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "frequency": { "type": "string", "const": "weekly" }, "weekday": { "anyOf": [ { "type": "string", "const": "monday" }, { "type": "string", "const": "tuesday" }, { "type": "string", "const": "wednesday" }, { "type": "string", "const": "thursday" }, { "type": "string", "const": "friday" }, { "type": "string", "const": "saturday" }, { "type": "string", "const": "sunday" } ], "description": "Day of the week the run is due, in UTC." }, "enabled": { "type": "boolean", "description": "false keeps the terms saved but creates no payouts." }, "minimumCents": { "type": "number", "description": "Smallest net transfer. A smaller balance rolls over to the next run." }, "holdPeriodDays": { "type": "number", "description": "Days a reward must have been approved before a run can pay it. A refund inside this window\nreverses the reward before it is paid. Program review holds are separate and come first.\nWallet cash rewards count as available for withdrawal only once they are this many days old,\nwhether or not the schedule is enabled. Terms saved before the default became 30 keep theirs." }, "stripeIntegrationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Stripe connection (integration ID) that sends scheduled payouts. When set, partners with a\nstripeAccountId are paid by a Stripe transfer from the merchant's Stripe balance, and other\npartners get a manual payout or wait, as missingStripeAccount says. Null keeps every scheduled\npayout manual." }, "missingStripeAccount": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "wait" } ], "description": "What a run does for a partner without a stripeAccountId while stripeIntegrationId is set.\nmanual, the default, creates a manual payout for the merchant to send. wait creates no payout:\nthe partner's rewards stay payable and roll over, and the first due date after the partner\ngets a stripeAccountId pays them by Stripe transfer. Hold period and minimum apply as usual.\nwait needs stripeIntegrationId." }, "activeSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the current terms took effect. Null while disabled." }, "lastRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the latest finished run." }, "nextRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the next run. Null while disabled." }, "updatedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until the terms are first saved." } }, "required": [ "frequency", "weekday", "enabled", "minimumCents", "holdPeriodDays", "stripeIntegrationId", "missingStripeAccount", "activeSince", "lastRunOn", "nextRunOn", "updatedAt" ] }, { "type": "object", "properties": { "frequency": { "type": "string", "const": "monthly" }, "enabled": { "type": "boolean", "description": "false keeps the terms saved but creates no payouts." }, "minimumCents": { "type": "number", "description": "Smallest net transfer. A smaller balance rolls over to the next run." }, "holdPeriodDays": { "type": "number", "description": "Days a reward must have been approved before a run can pay it. A refund inside this window\nreverses the reward before it is paid. Program review holds are separate and come first.\nWallet cash rewards count as available for withdrawal only once they are this many days old,\nwhether or not the schedule is enabled. Terms saved before the default became 30 keep theirs." }, "stripeIntegrationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Stripe connection (integration ID) that sends scheduled payouts. When set, partners with a\nstripeAccountId are paid by a Stripe transfer from the merchant's Stripe balance, and other\npartners get a manual payout or wait, as missingStripeAccount says. Null keeps every scheduled\npayout manual." }, "missingStripeAccount": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "wait" } ], "description": "What a run does for a partner without a stripeAccountId while stripeIntegrationId is set.\nmanual, the default, creates a manual payout for the merchant to send. wait creates no payout:\nthe partner's rewards stay payable and roll over, and the first due date after the partner\ngets a stripeAccountId pays them by Stripe transfer. Hold period and minimum apply as usual.\nwait needs stripeIntegrationId." }, "dayOfMonth": { "type": "number", "description": "Day of the month the run is due, in UTC. 1 to 28, so every month has it." }, "activeSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the current terms took effect. Null while disabled." }, "lastRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the latest finished run." }, "nextRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the next run. Null while disabled." }, "updatedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until the terms are first saved." } }, "required": [ "frequency", "enabled", "minimumCents", "holdPeriodDays", "stripeIntegrationId", "missingStripeAccount", "dayOfMonth", "activeSince", "lastRunOn", "nextRunOn", "updatedAt" ] } ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "put": { "operationId": "updatePayoutSchedule", "summary": "Replace the payout terms. On each due date Grizzlee creates merchant payouts and sends\npayout.created. With stripeIntegrationId set, partners with a stripeAccountId are paid by\nStripe transfer and get payout.paid or payout.failed. Changed terms first run on the next due\ndate on or after today. Needs payouts:write.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "payouts:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "frequency": { "type": "string", "const": "weekly" }, "weekday": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "enabled": { "type": "boolean" }, "minimumCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "default": 0 }, "holdPeriodDays": { "type": "integer", "minimum": 0, "maximum": 365, "default": 30 }, "stripeIntegrationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "default": null }, "missingStripeAccount": { "type": "string", "enum": [ "manual", "wait" ], "default": "manual" } }, "required": [ "frequency", "weekday", "enabled" ], "additionalProperties": false }, { "type": "object", "properties": { "frequency": { "type": "string", "const": "monthly" }, "dayOfMonth": { "type": "integer", "minimum": 1, "maximum": 28 }, "enabled": { "type": "boolean" }, "minimumCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000, "default": 0 }, "holdPeriodDays": { "type": "integer", "minimum": 0, "maximum": 365, "default": 30 }, "stripeIntegrationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "default": null }, "missingStripeAccount": { "type": "string", "enum": [ "manual", "wait" ], "default": "manual" } }, "required": [ "frequency", "dayOfMonth", "enabled" ], "additionalProperties": false } ] }, "example": { "frequency": "weekly", "weekday": "monday", "enabled": true } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "frequency": { "type": "string", "const": "weekly" }, "weekday": { "anyOf": [ { "type": "string", "const": "monday" }, { "type": "string", "const": "tuesday" }, { "type": "string", "const": "wednesday" }, { "type": "string", "const": "thursday" }, { "type": "string", "const": "friday" }, { "type": "string", "const": "saturday" }, { "type": "string", "const": "sunday" } ], "description": "Day of the week the run is due, in UTC." }, "enabled": { "type": "boolean", "description": "false keeps the terms saved but creates no payouts." }, "minimumCents": { "type": "number", "description": "Smallest net transfer. A smaller balance rolls over to the next run." }, "holdPeriodDays": { "type": "number", "description": "Days a reward must have been approved before a run can pay it. A refund inside this window\nreverses the reward before it is paid. Program review holds are separate and come first.\nWallet cash rewards count as available for withdrawal only once they are this many days old,\nwhether or not the schedule is enabled. Terms saved before the default became 30 keep theirs." }, "stripeIntegrationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Stripe connection (integration ID) that sends scheduled payouts. When set, partners with a\nstripeAccountId are paid by a Stripe transfer from the merchant's Stripe balance, and other\npartners get a manual payout or wait, as missingStripeAccount says. Null keeps every scheduled\npayout manual." }, "missingStripeAccount": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "wait" } ], "description": "What a run does for a partner without a stripeAccountId while stripeIntegrationId is set.\nmanual, the default, creates a manual payout for the merchant to send. wait creates no payout:\nthe partner's rewards stay payable and roll over, and the first due date after the partner\ngets a stripeAccountId pays them by Stripe transfer. Hold period and minimum apply as usual.\nwait needs stripeIntegrationId." }, "activeSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the current terms took effect. Null while disabled." }, "lastRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the latest finished run." }, "nextRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the next run. Null while disabled." }, "updatedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until the terms are first saved." } }, "required": [ "frequency", "weekday", "enabled", "minimumCents", "holdPeriodDays", "stripeIntegrationId", "missingStripeAccount", "activeSince", "lastRunOn", "nextRunOn", "updatedAt" ] }, { "type": "object", "properties": { "frequency": { "type": "string", "const": "monthly" }, "enabled": { "type": "boolean", "description": "false keeps the terms saved but creates no payouts." }, "minimumCents": { "type": "number", "description": "Smallest net transfer. A smaller balance rolls over to the next run." }, "holdPeriodDays": { "type": "number", "description": "Days a reward must have been approved before a run can pay it. A refund inside this window\nreverses the reward before it is paid. Program review holds are separate and come first.\nWallet cash rewards count as available for withdrawal only once they are this many days old,\nwhether or not the schedule is enabled. Terms saved before the default became 30 keep theirs." }, "stripeIntegrationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Stripe connection (integration ID) that sends scheduled payouts. When set, partners with a\nstripeAccountId are paid by a Stripe transfer from the merchant's Stripe balance, and other\npartners get a manual payout or wait, as missingStripeAccount says. Null keeps every scheduled\npayout manual." }, "missingStripeAccount": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "wait" } ], "description": "What a run does for a partner without a stripeAccountId while stripeIntegrationId is set.\nmanual, the default, creates a manual payout for the merchant to send. wait creates no payout:\nthe partner's rewards stay payable and roll over, and the first due date after the partner\ngets a stripeAccountId pays them by Stripe transfer. Hold period and minimum apply as usual.\nwait needs stripeIntegrationId." }, "dayOfMonth": { "type": "number", "description": "Day of the month the run is due, in UTC. 1 to 28, so every month has it." }, "activeSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the current terms took effect. Null while disabled." }, "lastRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the latest finished run." }, "nextRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the next run. Null while disabled." }, "updatedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until the terms are first saved." } }, "required": [ "frequency", "enabled", "minimumCents", "holdPeriodDays", "stripeIntegrationId", "missingStripeAccount", "dayOfMonth", "activeSince", "lastRunOn", "nextRunOn", "updatedAt" ] } ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "anyOf": [ { "type": "object", "properties": { "frequency": { "type": "string", "const": "weekly" }, "weekday": { "anyOf": [ { "type": "string", "const": "monday" }, { "type": "string", "const": "tuesday" }, { "type": "string", "const": "wednesday" }, { "type": "string", "const": "thursday" }, { "type": "string", "const": "friday" }, { "type": "string", "const": "saturday" }, { "type": "string", "const": "sunday" } ], "description": "Day of the week the run is due, in UTC." }, "enabled": { "type": "boolean", "description": "false keeps the terms saved but creates no payouts." }, "minimumCents": { "type": "number", "description": "Smallest net transfer. A smaller balance rolls over to the next run." }, "holdPeriodDays": { "type": "number", "description": "Days a reward must have been approved before a run can pay it. A refund inside this window\nreverses the reward before it is paid. Program review holds are separate and come first.\nWallet cash rewards count as available for withdrawal only once they are this many days old,\nwhether or not the schedule is enabled. Terms saved before the default became 30 keep theirs." }, "stripeIntegrationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Stripe connection (integration ID) that sends scheduled payouts. When set, partners with a\nstripeAccountId are paid by a Stripe transfer from the merchant's Stripe balance, and other\npartners get a manual payout or wait, as missingStripeAccount says. Null keeps every scheduled\npayout manual." }, "missingStripeAccount": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "wait" } ], "description": "What a run does for a partner without a stripeAccountId while stripeIntegrationId is set.\nmanual, the default, creates a manual payout for the merchant to send. wait creates no payout:\nthe partner's rewards stay payable and roll over, and the first due date after the partner\ngets a stripeAccountId pays them by Stripe transfer. Hold period and minimum apply as usual.\nwait needs stripeIntegrationId." }, "activeSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the current terms took effect. Null while disabled." }, "lastRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the latest finished run." }, "nextRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the next run. Null while disabled." }, "updatedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until the terms are first saved." } }, "required": [ "frequency", "weekday", "enabled", "minimumCents", "holdPeriodDays", "stripeIntegrationId", "missingStripeAccount", "activeSince", "lastRunOn", "nextRunOn", "updatedAt" ] }, { "type": "object", "properties": { "frequency": { "type": "string", "const": "monthly" }, "enabled": { "type": "boolean", "description": "false keeps the terms saved but creates no payouts." }, "minimumCents": { "type": "number", "description": "Smallest net transfer. A smaller balance rolls over to the next run." }, "holdPeriodDays": { "type": "number", "description": "Days a reward must have been approved before a run can pay it. A refund inside this window\nreverses the reward before it is paid. Program review holds are separate and come first.\nWallet cash rewards count as available for withdrawal only once they are this many days old,\nwhether or not the schedule is enabled. Terms saved before the default became 30 keep theirs." }, "stripeIntegrationId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Stripe connection (integration ID) that sends scheduled payouts. When set, partners with a\nstripeAccountId are paid by a Stripe transfer from the merchant's Stripe balance, and other\npartners get a manual payout or wait, as missingStripeAccount says. Null keeps every scheduled\npayout manual." }, "missingStripeAccount": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "wait" } ], "description": "What a run does for a partner without a stripeAccountId while stripeIntegrationId is set.\nmanual, the default, creates a manual payout for the merchant to send. wait creates no payout:\nthe partner's rewards stay payable and roll over, and the first due date after the partner\ngets a stripeAccountId pays them by Stripe transfer. Hold period and minimum apply as usual.\nwait needs stripeIntegrationId." }, "dayOfMonth": { "type": "number", "description": "Day of the month the run is due, in UTC. 1 to 28, so every month has it." }, "activeSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the current terms took effect. Null while disabled." }, "lastRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the latest finished run." }, "nextRunOn": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the next run. Null while disabled." }, "updatedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until the terms are first saved." } }, "required": [ "frequency", "enabled", "minimumCents", "holdPeriodDays", "stripeIntegrationId", "missingStripeAccount", "dayOfMonth", "activeSince", "lastRunOn", "nextRunOn", "updatedAt" ] } ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/{id}/promo-codes": { "get": { "operationId": "listPartnerPromoCodes", "summary": "Profile, programs with referral links, click counts, and wallet and merchant balances. Needs read.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "post": { "operationId": "createPartnerPromoCode", "summary": "createPartnerPromoCode", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "integrationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "code": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[A-Za-z0-9-]+$" } }, "required": [ "programId", "integrationId", "code" ], "additionalProperties": false }, "example": { "programId": "program-example", "integrationId": "integrationId-example", "code": "2026-10-11" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/promo-codes": { "get": { "operationId": "listPartnerPromoCodesByExternalId", "summary": "Profile, programs with referral links, click counts, and wallet and merchant balances. Needs read.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "post": { "operationId": "createPartnerPromoCodeByExternalId", "summary": "createPartnerPromoCode", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "integrationId": { "type": "string", "minLength": 1, "maxLength": 120 }, "code": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[A-Za-z0-9-]+$" } }, "required": [ "programId", "integrationId", "code" ], "additionalProperties": false }, "example": { "programId": "program-example", "integrationId": "integrationId-example", "code": "2026-10-11" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/{id}/promo-codes/{codeId}": { "put": { "operationId": "renamePartnerPromoCode", "summary": "renamePartnerPromoCode", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "codeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[A-Za-z0-9-]+$" } }, "required": [ "code" ], "additionalProperties": false }, "example": { "code": "2026-10-11" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "delete": { "operationId": "deactivatePartnerPromoCode", "summary": "deactivatePartnerPromoCode", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "codeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/promo-codes/{codeId}": { "put": { "operationId": "renamePartnerPromoCodeByExternalId", "summary": "renamePartnerPromoCode", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "codeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 2, "maxLength": 80, "pattern": "^[A-Za-z0-9-]+$" } }, "required": [ "code" ], "additionalProperties": false }, "example": { "code": "2026-10-11" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "delete": { "operationId": "deactivatePartnerPromoCodeByExternalId", "summary": "deactivatePartnerPromoCode", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "codeId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/{id}/summary": { "get": { "operationId": "getPartnerSummary", "summary": "getPartnerSummary", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "referralCode": { "type": "string" }, "clicks": { "type": "object", "properties": { "total": { "type": "number", "description": "All recorded activity, including repeat visits and unclaimed or voided receipts." }, "last30Days": { "type": "number", "description": "Activity in the rolling 30 days ending at the summary's read time." } }, "required": [ "total", "last30Days" ], "description": "Link and QR activity across all programs, including former memberships." }, "programs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "member": { "type": "boolean", "description": "Whether the partner currently belongs to this program. Former memberships keep their totals." }, "tracking": { "type": "object", "properties": { "links": { "type": "boolean" }, "qrCodes": { "type": "boolean" }, "attributionCodes": { "type": "boolean" }, "providerPromoCodes": { "type": "boolean" } }, "required": [ "links", "qrCodes", "attributionCodes", "providerPromoCodes" ] }, "attributionCode": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "alias": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's short code, such as KARL7Q, when attributionCode is set. Customers can type either." }, "promoCodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } }, "qrLink": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string" } }, "required": [ "type", "milestone" ] } ], "description": "What earns a reward in this program." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Who delivers this program's rewards: the Grizzlee wallet or the merchant." }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" }, "phases": { "type": "array", "items": { "type": "object", "properties": { "rateBps": { "type": "number" }, "afterMonths": { "type": "number" } }, "required": [ "rateBps", "afterMonths" ] } } }, "required": [ "type", "rateBps" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] } ], "description": "Order compensation, with this partner's custom terms when present. Absent for milestones." }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" } }, "required": [ "type", "rateBps" ] } ] }, "limit": { "type": "number", "description": "Absent means every counted report. Reversed reports do not count toward the limit." } }, "required": [ "compensation" ] }, "atCount": { "type": "object", "properties": { "amountCents": { "type": "number" }, "count": { "type": "number" } }, "required": [ "amountCents", "count" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "How this program refunds fixed rewards. Percentage rewards keep their commission base." }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "What a referred customer gets in this program. Null without an offer or a current membership." }, "terms": { "type": "object", "properties": { "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string" } }, "required": [ "type", "milestone" ] } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "compensation": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number", "description": "Base rate, before any performance tier bonus." }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "number" }, "rateBps": { "type": "number" } }, "required": [ "afterMonths", "rateBps" ] }, "description": "Later rates by months after the customer's first rewarded order. Empty when the rate never changes." } }, "required": [ "type", "rateBps", "phases" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] } ], "description": "What the partner earns. This partner's custom terms replace the program's when it has them." }, "partnerOffer": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The partner's earned discount with currency. Null for money rewards." }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" } }, "required": [ "type", "rateBps" ] } ] }, "limit": { "type": "number", "description": "Absent means every counted report. Reversed reports do not count toward the limit." } }, "required": [ "compensation" ] }, "atCount": { "type": "object", "properties": { "amountCents": { "type": "number" }, "count": { "type": "number" } }, "required": [ "amountCents", "count" ] } } }, "duration": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "only_order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_n_orders" }, "count": { "type": "number" } }, "required": [ "type", "count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "days" }, "days": { "type": "number" } }, "required": [ "type", "days" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "months" }, "months": { "type": "number" } }, "required": [ "type", "months" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime" } }, "required": [ "type" ] } ], "description": "Which orders of a referred customer earn a reward. Null for milestone programs." }, "fixedRefundMode": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "How a partial refund changes a fixed order reward. Null for percentage and milestone rewards." }, "referralWindowDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days a referral stays open until an order or milestone qualifies it. Null when it never expires." }, "text": { "type": "object", "properties": { "reward": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ], "description": "What the partner earns, such as \"$10 credit when your friend completes their first order after your referral\"." }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } ], "description": "What the referred friend gets, such as \"20% off your first order\". Null without a friend incentive." }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ], "description": "Both sides in a few words, such as \"Give 20%, get $10\", or \"Get $10\" without a friend incentive." } }, "required": [ "reward", "incentive", "headline" ] } }, "required": [ "trigger", "rewardType", "currency", "compensation", "partnerOffer", "duration", "fixedRefundMode", "referralWindowDays", "text" ], "description": "Readable reward terms. Former memberships omit the friend incentive from the text." }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "Public name, headline and milestone label. The headline falls back to terms.text.headline." }, "link": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Referral link to the program's published destination. Null when unavailable or membership ended." }, "linkUnavailableReason": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "tracking_disabled" }, { "type": "string", "const": "no_published_page" }, { "type": "string", "const": "invalid_destination" } ], "description": "Set when link is null, otherwise null." }, "clicks": { "type": "object", "properties": { "total": { "type": "number", "description": "All recorded activity, including repeat visits and unclaimed or voided receipts." }, "last30Days": { "type": "number", "description": "Activity in the rolling 30 days ending at the summary's read time." } }, "required": [ "total", "last30Days" ], "description": "Link and QR activity in this program. Coupon and in-app channels are excluded." }, "earnedCents": { "type": "number", "description": "Reward value after reversals, across saved reward types and delivery modes." }, "reversedCents": { "type": "number", "description": "Reward value currently reversed. Restorations reduce this total." }, "referrals": { "type": "object", "properties": { "referred": { "type": "number" }, "qualified": { "type": "number" } }, "required": [ "referred", "qualified" ], "description": "Each attribution counts once, including displaced referrals and separate order-scoped referrals." }, "orderCount": { "type": "number", "description": "Sum of referral orderCount values in this program. Reversed rewards still count; milestones do not." }, "payouts": { "type": "object", "properties": { "paidOutCents": { "type": "number" } }, "required": [ "paidOutCents" ], "description": "Paid merchant allocations less returned transfers. Wallet payouts have no program allocations." }, "balances": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." } }, "required": [ "currency", "rewardType", "pendingApprovalCents", "approvedCents" ] }, "credit": { "type": "object", "properties": { "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." } }, "required": [ "currency", "rewardType", "pendingApprovalCents", "approvedCents" ] } }, "required": [ "cash", "credit" ], "description": "Wallet spending, reservations and debt cannot be attributed to a program." }, "merchant": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] } }, "required": [ "cash", "credit" ] } }, "required": [ "wallet", "merchant" ] } }, "required": [ "id", "name", "active", "member", "tracking", "attributionCode", "alias", "promoCodes", "qrLink", "currency", "rewardType", "trigger", "deliveryMode", "fixedRefundMode", "incentive", "terms", "display", "link", "linkUnavailableReason", "clicks", "earnedCents", "reversedCents", "referrals", "orderCount", "payouts", "balances" ] }, "description": "Current memberships in programIds order, then former programs with rewards, referrals, payout allocations or debt, sorted by ID." }, "balances": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." }, "reservedCents": { "type": "number", "description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit." }, "paidOrRedeemedCents": { "type": "number", "description": "Cash paid by finished wallet payouts, or credit redeemed less restorations." }, "availableToSpendCents": { "type": "number", "description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0." }, "debtCents": { "type": "number", "description": "Reversals after money left the wallet that later earnings must cover first." } }, "required": [ "rewardType", "currency", "pendingApprovalCents", "approvedCents", "reservedCents", "paidOrRedeemedCents", "availableToSpendCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." }, "reservedCents": { "type": "number", "description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit." }, "paidOrRedeemedCents": { "type": "number", "description": "Cash paid by finished wallet payouts, or credit redeemed less restorations." }, "availableToSpendCents": { "type": "number", "description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0." }, "debtCents": { "type": "number", "description": "Reversals after money left the wallet that later earnings must cover first." } }, "required": [ "rewardType", "currency", "pendingApprovalCents", "approvedCents", "reservedCents", "paidOrRedeemedCents", "availableToSpendCents", "debtCents" ] } }, "required": [ "cash", "credit" ] }, "merchant": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] } }, "required": [ "cash", "credit" ] } }, "required": [ "wallet", "merchant" ] }, "payoutAccountRequired": { "type": "boolean", "description": "True when the payout schedule waits for a Stripe account (missingStripeAccount \"wait\"), the\npartner has no stripeAccountId, and the partner earns merchant-delivered cash: it belongs to\nsuch a program or has such cash pending or approved. Scheduled runs pay this partner nothing\nuntil it gets a stripeAccountId." }, "awaitingPayoutAccount": { "type": "boolean", "description": "True when payoutAccountRequired and a scheduled run already held a payout for it." }, "awaitingPayoutAccountSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the first run that held a payout. Null unless awaitingPayoutAccount." } }, "required": [ "id", "externalId", "name", "active", "referralCode", "clicks", "programs", "balances", "payoutAccountRequired", "awaitingPayoutAccount", "awaitingPayoutAccountSince" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "referralCode": { "type": "string" }, "clicks": { "type": "object", "properties": { "total": { "type": "number", "description": "All recorded activity, including repeat visits and unclaimed or voided receipts." }, "last30Days": { "type": "number", "description": "Activity in the rolling 30 days ending at the summary's read time." } }, "required": [ "total", "last30Days" ], "description": "Link and QR activity across all programs, including former memberships." }, "programs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "member": { "type": "boolean", "description": "Whether the partner currently belongs to this program. Former memberships keep their totals." }, "tracking": { "type": "object", "properties": { "links": { "type": "boolean" }, "qrCodes": { "type": "boolean" }, "attributionCodes": { "type": "boolean" }, "providerPromoCodes": { "type": "boolean" } }, "required": [ "links", "qrCodes", "attributionCodes", "providerPromoCodes" ] }, "attributionCode": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "alias": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's short code, such as KARL7Q, when attributionCode is set. Customers can type either." }, "promoCodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } }, "qrLink": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string" } }, "required": [ "type", "milestone" ] } ], "description": "What earns a reward in this program." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Who delivers this program's rewards: the Grizzlee wallet or the merchant." }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" }, "phases": { "type": "array", "items": { "type": "object", "properties": { "rateBps": { "type": "number" }, "afterMonths": { "type": "number" } }, "required": [ "rateBps", "afterMonths" ] } } }, "required": [ "type", "rateBps" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] } ], "description": "Order compensation, with this partner's custom terms when present. Absent for milestones." }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" } }, "required": [ "type", "rateBps" ] } ] }, "limit": { "type": "number", "description": "Absent means every counted report. Reversed reports do not count toward the limit." } }, "required": [ "compensation" ] }, "atCount": { "type": "object", "properties": { "amountCents": { "type": "number" }, "count": { "type": "number" } }, "required": [ "amountCents", "count" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "How this program refunds fixed rewards. Percentage rewards keep their commission base." }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "What a referred customer gets in this program. Null without an offer or a current membership." }, "terms": { "type": "object", "properties": { "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string" } }, "required": [ "type", "milestone" ] } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "compensation": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number", "description": "Base rate, before any performance tier bonus." }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "number" }, "rateBps": { "type": "number" } }, "required": [ "afterMonths", "rateBps" ] }, "description": "Later rates by months after the customer's first rewarded order. Empty when the rate never changes." } }, "required": [ "type", "rateBps", "phases" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] } ], "description": "What the partner earns. This partner's custom terms replace the program's when it has them." }, "partnerOffer": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The partner's earned discount with currency. Null for money rewards." }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" } }, "required": [ "type", "rateBps" ] } ] }, "limit": { "type": "number", "description": "Absent means every counted report. Reversed reports do not count toward the limit." } }, "required": [ "compensation" ] }, "atCount": { "type": "object", "properties": { "amountCents": { "type": "number" }, "count": { "type": "number" } }, "required": [ "amountCents", "count" ] } } }, "duration": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "only_order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_n_orders" }, "count": { "type": "number" } }, "required": [ "type", "count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "days" }, "days": { "type": "number" } }, "required": [ "type", "days" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "months" }, "months": { "type": "number" } }, "required": [ "type", "months" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime" } }, "required": [ "type" ] } ], "description": "Which orders of a referred customer earn a reward. Null for milestone programs." }, "fixedRefundMode": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "How a partial refund changes a fixed order reward. Null for percentage and milestone rewards." }, "referralWindowDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days a referral stays open until an order or milestone qualifies it. Null when it never expires." }, "text": { "type": "object", "properties": { "reward": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ], "description": "What the partner earns, such as \"$10 credit when your friend completes their first order after your referral\"." }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } ], "description": "What the referred friend gets, such as \"20% off your first order\". Null without a friend incentive." }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ], "description": "Both sides in a few words, such as \"Give 20%, get $10\", or \"Get $10\" without a friend incentive." } }, "required": [ "reward", "incentive", "headline" ] } }, "required": [ "trigger", "rewardType", "currency", "compensation", "partnerOffer", "duration", "fixedRefundMode", "referralWindowDays", "text" ], "description": "Readable reward terms. Former memberships omit the friend incentive from the text." }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "Public name, headline and milestone label. The headline falls back to terms.text.headline." }, "link": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Referral link to the program's published destination. Null when unavailable or membership ended." }, "linkUnavailableReason": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "tracking_disabled" }, { "type": "string", "const": "no_published_page" }, { "type": "string", "const": "invalid_destination" } ], "description": "Set when link is null, otherwise null." }, "clicks": { "type": "object", "properties": { "total": { "type": "number", "description": "All recorded activity, including repeat visits and unclaimed or voided receipts." }, "last30Days": { "type": "number", "description": "Activity in the rolling 30 days ending at the summary's read time." } }, "required": [ "total", "last30Days" ], "description": "Link and QR activity in this program. Coupon and in-app channels are excluded." }, "earnedCents": { "type": "number", "description": "Reward value after reversals, across saved reward types and delivery modes." }, "reversedCents": { "type": "number", "description": "Reward value currently reversed. Restorations reduce this total." }, "referrals": { "type": "object", "properties": { "referred": { "type": "number" }, "qualified": { "type": "number" } }, "required": [ "referred", "qualified" ], "description": "Each attribution counts once, including displaced referrals and separate order-scoped referrals." }, "orderCount": { "type": "number", "description": "Sum of referral orderCount values in this program. Reversed rewards still count; milestones do not." }, "payouts": { "type": "object", "properties": { "paidOutCents": { "type": "number" } }, "required": [ "paidOutCents" ], "description": "Paid merchant allocations less returned transfers. Wallet payouts have no program allocations." }, "balances": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." } }, "required": [ "currency", "rewardType", "pendingApprovalCents", "approvedCents" ] }, "credit": { "type": "object", "properties": { "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." } }, "required": [ "currency", "rewardType", "pendingApprovalCents", "approvedCents" ] } }, "required": [ "cash", "credit" ], "description": "Wallet spending, reservations and debt cannot be attributed to a program." }, "merchant": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] } }, "required": [ "cash", "credit" ] } }, "required": [ "wallet", "merchant" ] } }, "required": [ "id", "name", "active", "member", "tracking", "attributionCode", "alias", "promoCodes", "qrLink", "currency", "rewardType", "trigger", "deliveryMode", "fixedRefundMode", "incentive", "terms", "display", "link", "linkUnavailableReason", "clicks", "earnedCents", "reversedCents", "referrals", "orderCount", "payouts", "balances" ] }, "description": "Current memberships in programIds order, then former programs with rewards, referrals, payout allocations or debt, sorted by ID." }, "balances": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." }, "reservedCents": { "type": "number", "description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit." }, "paidOrRedeemedCents": { "type": "number", "description": "Cash paid by finished wallet payouts, or credit redeemed less restorations." }, "availableToSpendCents": { "type": "number", "description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0." }, "debtCents": { "type": "number", "description": "Reversals after money left the wallet that later earnings must cover first." } }, "required": [ "rewardType", "currency", "pendingApprovalCents", "approvedCents", "reservedCents", "paidOrRedeemedCents", "availableToSpendCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." }, "reservedCents": { "type": "number", "description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit." }, "paidOrRedeemedCents": { "type": "number", "description": "Cash paid by finished wallet payouts, or credit redeemed less restorations." }, "availableToSpendCents": { "type": "number", "description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0." }, "debtCents": { "type": "number", "description": "Reversals after money left the wallet that later earnings must cover first." } }, "required": [ "rewardType", "currency", "pendingApprovalCents", "approvedCents", "reservedCents", "paidOrRedeemedCents", "availableToSpendCents", "debtCents" ] } }, "required": [ "cash", "credit" ] }, "merchant": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] } }, "required": [ "cash", "credit" ] } }, "required": [ "wallet", "merchant" ] }, "payoutAccountRequired": { "type": "boolean", "description": "True when the payout schedule waits for a Stripe account (missingStripeAccount \"wait\"), the\npartner has no stripeAccountId, and the partner earns merchant-delivered cash: it belongs to\nsuch a program or has such cash pending or approved. Scheduled runs pay this partner nothing\nuntil it gets a stripeAccountId." }, "awaitingPayoutAccount": { "type": "boolean", "description": "True when payoutAccountRequired and a scheduled run already held a payout for it." }, "awaitingPayoutAccountSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the first run that held a payout. Null unless awaitingPayoutAccount." } }, "required": [ "id", "externalId", "name", "active", "referralCode", "clicks", "programs", "balances", "payoutAccountRequired", "awaitingPayoutAccount", "awaitingPayoutAccountSince" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/summary": { "get": { "operationId": "getPartnerSummaryByExternalId", "summary": "getPartnerSummary", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "referralCode": { "type": "string" }, "clicks": { "type": "object", "properties": { "total": { "type": "number", "description": "All recorded activity, including repeat visits and unclaimed or voided receipts." }, "last30Days": { "type": "number", "description": "Activity in the rolling 30 days ending at the summary's read time." } }, "required": [ "total", "last30Days" ], "description": "Link and QR activity across all programs, including former memberships." }, "programs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "member": { "type": "boolean", "description": "Whether the partner currently belongs to this program. Former memberships keep their totals." }, "tracking": { "type": "object", "properties": { "links": { "type": "boolean" }, "qrCodes": { "type": "boolean" }, "attributionCodes": { "type": "boolean" }, "providerPromoCodes": { "type": "boolean" } }, "required": [ "links", "qrCodes", "attributionCodes", "providerPromoCodes" ] }, "attributionCode": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "alias": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's short code, such as KARL7Q, when attributionCode is set. Customers can type either." }, "promoCodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } }, "qrLink": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string" } }, "required": [ "type", "milestone" ] } ], "description": "What earns a reward in this program." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Who delivers this program's rewards: the Grizzlee wallet or the merchant." }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" }, "phases": { "type": "array", "items": { "type": "object", "properties": { "rateBps": { "type": "number" }, "afterMonths": { "type": "number" } }, "required": [ "rateBps", "afterMonths" ] } } }, "required": [ "type", "rateBps" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] } ], "description": "Order compensation, with this partner's custom terms when present. Absent for milestones." }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" } }, "required": [ "type", "rateBps" ] } ] }, "limit": { "type": "number", "description": "Absent means every counted report. Reversed reports do not count toward the limit." } }, "required": [ "compensation" ] }, "atCount": { "type": "object", "properties": { "amountCents": { "type": "number" }, "count": { "type": "number" } }, "required": [ "amountCents", "count" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "How this program refunds fixed rewards. Percentage rewards keep their commission base." }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "What a referred customer gets in this program. Null without an offer or a current membership." }, "terms": { "type": "object", "properties": { "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string" } }, "required": [ "type", "milestone" ] } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "compensation": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number", "description": "Base rate, before any performance tier bonus." }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "number" }, "rateBps": { "type": "number" } }, "required": [ "afterMonths", "rateBps" ] }, "description": "Later rates by months after the customer's first rewarded order. Empty when the rate never changes." } }, "required": [ "type", "rateBps", "phases" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] } ], "description": "What the partner earns. This partner's custom terms replace the program's when it has them." }, "partnerOffer": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The partner's earned discount with currency. Null for money rewards." }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" } }, "required": [ "type", "rateBps" ] } ] }, "limit": { "type": "number", "description": "Absent means every counted report. Reversed reports do not count toward the limit." } }, "required": [ "compensation" ] }, "atCount": { "type": "object", "properties": { "amountCents": { "type": "number" }, "count": { "type": "number" } }, "required": [ "amountCents", "count" ] } } }, "duration": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "only_order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_n_orders" }, "count": { "type": "number" } }, "required": [ "type", "count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "days" }, "days": { "type": "number" } }, "required": [ "type", "days" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "months" }, "months": { "type": "number" } }, "required": [ "type", "months" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime" } }, "required": [ "type" ] } ], "description": "Which orders of a referred customer earn a reward. Null for milestone programs." }, "fixedRefundMode": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "How a partial refund changes a fixed order reward. Null for percentage and milestone rewards." }, "referralWindowDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days a referral stays open until an order or milestone qualifies it. Null when it never expires." }, "text": { "type": "object", "properties": { "reward": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ], "description": "What the partner earns, such as \"$10 credit when your friend completes their first order after your referral\"." }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } ], "description": "What the referred friend gets, such as \"20% off your first order\". Null without a friend incentive." }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ], "description": "Both sides in a few words, such as \"Give 20%, get $10\", or \"Get $10\" without a friend incentive." } }, "required": [ "reward", "incentive", "headline" ] } }, "required": [ "trigger", "rewardType", "currency", "compensation", "partnerOffer", "duration", "fixedRefundMode", "referralWindowDays", "text" ], "description": "Readable reward terms. Former memberships omit the friend incentive from the text." }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "Public name, headline and milestone label. The headline falls back to terms.text.headline." }, "link": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Referral link to the program's published destination. Null when unavailable or membership ended." }, "linkUnavailableReason": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "tracking_disabled" }, { "type": "string", "const": "no_published_page" }, { "type": "string", "const": "invalid_destination" } ], "description": "Set when link is null, otherwise null." }, "clicks": { "type": "object", "properties": { "total": { "type": "number", "description": "All recorded activity, including repeat visits and unclaimed or voided receipts." }, "last30Days": { "type": "number", "description": "Activity in the rolling 30 days ending at the summary's read time." } }, "required": [ "total", "last30Days" ], "description": "Link and QR activity in this program. Coupon and in-app channels are excluded." }, "earnedCents": { "type": "number", "description": "Reward value after reversals, across saved reward types and delivery modes." }, "reversedCents": { "type": "number", "description": "Reward value currently reversed. Restorations reduce this total." }, "referrals": { "type": "object", "properties": { "referred": { "type": "number" }, "qualified": { "type": "number" } }, "required": [ "referred", "qualified" ], "description": "Each attribution counts once, including displaced referrals and separate order-scoped referrals." }, "orderCount": { "type": "number", "description": "Sum of referral orderCount values in this program. Reversed rewards still count; milestones do not." }, "payouts": { "type": "object", "properties": { "paidOutCents": { "type": "number" } }, "required": [ "paidOutCents" ], "description": "Paid merchant allocations less returned transfers. Wallet payouts have no program allocations." }, "balances": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." } }, "required": [ "currency", "rewardType", "pendingApprovalCents", "approvedCents" ] }, "credit": { "type": "object", "properties": { "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." } }, "required": [ "currency", "rewardType", "pendingApprovalCents", "approvedCents" ] } }, "required": [ "cash", "credit" ], "description": "Wallet spending, reservations and debt cannot be attributed to a program." }, "merchant": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] } }, "required": [ "cash", "credit" ] } }, "required": [ "wallet", "merchant" ] } }, "required": [ "id", "name", "active", "member", "tracking", "attributionCode", "alias", "promoCodes", "qrLink", "currency", "rewardType", "trigger", "deliveryMode", "fixedRefundMode", "incentive", "terms", "display", "link", "linkUnavailableReason", "clicks", "earnedCents", "reversedCents", "referrals", "orderCount", "payouts", "balances" ] }, "description": "Current memberships in programIds order, then former programs with rewards, referrals, payout allocations or debt, sorted by ID." }, "balances": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." }, "reservedCents": { "type": "number", "description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit." }, "paidOrRedeemedCents": { "type": "number", "description": "Cash paid by finished wallet payouts, or credit redeemed less restorations." }, "availableToSpendCents": { "type": "number", "description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0." }, "debtCents": { "type": "number", "description": "Reversals after money left the wallet that later earnings must cover first." } }, "required": [ "rewardType", "currency", "pendingApprovalCents", "approvedCents", "reservedCents", "paidOrRedeemedCents", "availableToSpendCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." }, "reservedCents": { "type": "number", "description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit." }, "paidOrRedeemedCents": { "type": "number", "description": "Cash paid by finished wallet payouts, or credit redeemed less restorations." }, "availableToSpendCents": { "type": "number", "description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0." }, "debtCents": { "type": "number", "description": "Reversals after money left the wallet that later earnings must cover first." } }, "required": [ "rewardType", "currency", "pendingApprovalCents", "approvedCents", "reservedCents", "paidOrRedeemedCents", "availableToSpendCents", "debtCents" ] } }, "required": [ "cash", "credit" ] }, "merchant": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] } }, "required": [ "cash", "credit" ] } }, "required": [ "wallet", "merchant" ] }, "payoutAccountRequired": { "type": "boolean", "description": "True when the payout schedule waits for a Stripe account (missingStripeAccount \"wait\"), the\npartner has no stripeAccountId, and the partner earns merchant-delivered cash: it belongs to\nsuch a program or has such cash pending or approved. Scheduled runs pay this partner nothing\nuntil it gets a stripeAccountId." }, "awaitingPayoutAccount": { "type": "boolean", "description": "True when payoutAccountRequired and a scheduled run already held a payout for it." }, "awaitingPayoutAccountSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the first run that held a payout. Null unless awaitingPayoutAccount." } }, "required": [ "id", "externalId", "name", "active", "referralCode", "clicks", "programs", "balances", "payoutAccountRequired", "awaitingPayoutAccount", "awaitingPayoutAccountSince" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "referralCode": { "type": "string" }, "clicks": { "type": "object", "properties": { "total": { "type": "number", "description": "All recorded activity, including repeat visits and unclaimed or voided receipts." }, "last30Days": { "type": "number", "description": "Activity in the rolling 30 days ending at the summary's read time." } }, "required": [ "total", "last30Days" ], "description": "Link and QR activity across all programs, including former memberships." }, "programs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "member": { "type": "boolean", "description": "Whether the partner currently belongs to this program. Former memberships keep their totals." }, "tracking": { "type": "object", "properties": { "links": { "type": "boolean" }, "qrCodes": { "type": "boolean" }, "attributionCodes": { "type": "boolean" }, "providerPromoCodes": { "type": "boolean" } }, "required": [ "links", "qrCodes", "attributionCodes", "providerPromoCodes" ] }, "attributionCode": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "alias": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The partner's short code, such as KARL7Q, when attributionCode is set. Customers can type either." }, "promoCodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "programId": { "type": "string" }, "integrationId": { "type": "string" }, "provider": { "anyOf": [ { "type": "string", "const": "stripe" }, { "type": "string", "const": "shopify" } ] }, "code": { "type": "string" }, "providerCodeId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Null until Grizzlee has saved the provider discount ID." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "active" }, { "type": "string", "const": "inactive" } ] }, "replacesId": { "type": "string" }, "couponId": { "type": "string" }, "incentive": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ] }, "programVersion": { "type": "number" }, "active": { "type": "boolean" }, "createdAt": { "type": "string" }, "deactivatedAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "programId", "integrationId", "provider", "code", "providerCodeId", "status", "incentive", "programVersion", "active", "createdAt" ] } }, "qrLink": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string" } }, "required": [ "type", "milestone" ] } ], "description": "What earns a reward in this program." }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "Who delivers this program's rewards: the Grizzlee wallet or the merchant." }, "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" }, "phases": { "type": "array", "items": { "type": "object", "properties": { "rateBps": { "type": "number" }, "afterMonths": { "type": "number" } }, "required": [ "rateBps", "afterMonths" ] } } }, "required": [ "type", "rateBps" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] } ], "description": "Order compensation, with this partner's custom terms when present. Absent for milestones." }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" } }, "required": [ "type", "rateBps" ] } ] }, "limit": { "type": "number", "description": "Absent means every counted report. Reversed reports do not count toward the limit." } }, "required": [ "compensation" ] }, "atCount": { "type": "object", "properties": { "amountCents": { "type": "number" }, "count": { "type": "number" } }, "required": [ "amountCents", "count" ] } } }, "fixedRefundMode": { "anyOf": [ { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "How this program refunds fixed rewards. Percentage rewards keep their commission base." }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "What a referred customer gets in this program. Null without an offer or a current membership." }, "terms": { "type": "object", "properties": { "trigger": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "milestone" }, "milestone": { "type": "string" } }, "required": [ "type", "milestone" ] } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "compensation": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number", "description": "Base rate, before any performance tier bonus." }, "phases": { "type": "array", "items": { "type": "object", "properties": { "afterMonths": { "type": "number" }, "rateBps": { "type": "number" } }, "required": [ "afterMonths", "rateBps" ] }, "description": "Later rates by months after the customer's first rewarded order. Empty when the rate never changes." } }, "required": [ "type", "rateBps", "phases" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] } ], "description": "What the partner earns. This partner's custom terms replace the program's when it has them." }, "partnerOffer": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The partner's earned discount with currency. Null for money rewards." }, "milestoneRewards": { "type": "object", "properties": { "eachReport": { "type": "object", "properties": { "compensation": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "amountCents": { "type": "number" } }, "required": [ "type", "amountCents" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "percentage" }, "rateBps": { "type": "number" } }, "required": [ "type", "rateBps" ] } ] }, "limit": { "type": "number", "description": "Absent means every counted report. Reversed reports do not count toward the limit." } }, "required": [ "compensation" ] }, "atCount": { "type": "object", "properties": { "amountCents": { "type": "number" }, "count": { "type": "number" } }, "required": [ "amountCents", "count" ] } } }, "duration": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "only_order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_order" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "first_n_orders" }, "count": { "type": "number" } }, "required": [ "type", "count" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "days" }, "days": { "type": "number" } }, "required": [ "type", "days" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "months" }, "months": { "type": "number" } }, "required": [ "type", "months" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "lifetime" } }, "required": [ "type" ] } ], "description": "Which orders of a referred customer earn a reward. Null for milestone programs." }, "fixedRefundMode": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "prorate" }, { "type": "string", "const": "full_refund_only" } ], "description": "How a partial refund changes a fixed order reward. Null for percentage and milestone rewards." }, "referralWindowDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days a referral stays open until an order or milestone qualifies it. Null when it never expires." }, "text": { "type": "object", "properties": { "reward": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ], "description": "What the partner earns, such as \"$10 credit when your friend completes their first order after your referral\"." }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } ], "description": "What the referred friend gets, such as \"20% off your first order\". Null without a friend incentive." }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ], "description": "Both sides in a few words, such as \"Give 20%, get $10\", or \"Get $10\" without a friend incentive." } }, "required": [ "reward", "incentive", "headline" ] } }, "required": [ "trigger", "rewardType", "currency", "compensation", "partnerOffer", "duration", "fixedRefundMode", "referralWindowDays", "text" ], "description": "Readable reward terms. Former memberships omit the friend incentive from the text." }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "Public name, headline and milestone label. The headline falls back to terms.text.headline." }, "link": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Referral link to the program's published destination. Null when unavailable or membership ended." }, "linkUnavailableReason": { "anyOf": [ { "type": "null" }, { "type": "string", "const": "program_inactive" }, { "type": "string", "const": "partner_inactive" }, { "type": "string", "const": "tracking_disabled" }, { "type": "string", "const": "no_published_page" }, { "type": "string", "const": "invalid_destination" } ], "description": "Set when link is null, otherwise null." }, "clicks": { "type": "object", "properties": { "total": { "type": "number", "description": "All recorded activity, including repeat visits and unclaimed or voided receipts." }, "last30Days": { "type": "number", "description": "Activity in the rolling 30 days ending at the summary's read time." } }, "required": [ "total", "last30Days" ], "description": "Link and QR activity in this program. Coupon and in-app channels are excluded." }, "earnedCents": { "type": "number", "description": "Reward value after reversals, across saved reward types and delivery modes." }, "reversedCents": { "type": "number", "description": "Reward value currently reversed. Restorations reduce this total." }, "referrals": { "type": "object", "properties": { "referred": { "type": "number" }, "qualified": { "type": "number" } }, "required": [ "referred", "qualified" ], "description": "Each attribution counts once, including displaced referrals and separate order-scoped referrals." }, "orderCount": { "type": "number", "description": "Sum of referral orderCount values in this program. Reversed rewards still count; milestones do not." }, "payouts": { "type": "object", "properties": { "paidOutCents": { "type": "number" } }, "required": [ "paidOutCents" ], "description": "Paid merchant allocations less returned transfers. Wallet payouts have no program allocations." }, "balances": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." } }, "required": [ "currency", "rewardType", "pendingApprovalCents", "approvedCents" ] }, "credit": { "type": "object", "properties": { "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." } }, "required": [ "currency", "rewardType", "pendingApprovalCents", "approvedCents" ] } }, "required": [ "cash", "credit" ], "description": "Wallet spending, reservations and debt cannot be attributed to a program." }, "merchant": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] } }, "required": [ "cash", "credit" ] } }, "required": [ "wallet", "merchant" ] } }, "required": [ "id", "name", "active", "member", "tracking", "attributionCode", "alias", "promoCodes", "qrLink", "currency", "rewardType", "trigger", "deliveryMode", "fixedRefundMode", "incentive", "terms", "display", "link", "linkUnavailableReason", "clicks", "earnedCents", "reversedCents", "referrals", "orderCount", "payouts", "balances" ] }, "description": "Current memberships in programIds order, then former programs with rewards, referrals, payout allocations or debt, sorted by ID." }, "balances": { "type": "object", "properties": { "wallet": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." }, "reservedCents": { "type": "number", "description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit." }, "paidOrRedeemedCents": { "type": "number", "description": "Cash paid by finished wallet payouts, or credit redeemed less restorations." }, "availableToSpendCents": { "type": "number", "description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0." }, "debtCents": { "type": "number", "description": "Reversals after money left the wallet that later earnings must cover first." } }, "required": [ "rewardType", "currency", "pendingApprovalCents", "approvedCents", "reservedCents", "paidOrRedeemedCents", "availableToSpendCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards after reversals." }, "approvedCents": { "type": "number", "description": "Every approved reward after reversals, including amounts already reserved, paid or redeemed." }, "reservedCents": { "type": "number", "description": "Cash held by wallet payouts that are queued, processing or need action. Always 0 for credit." }, "paidOrRedeemedCents": { "type": "number", "description": "Cash paid by finished wallet payouts, or credit redeemed less restorations." }, "availableToSpendCents": { "type": "number", "description": "What a new wallet payout (cash) or redemption (credit) can use now: approved value minus\nreserved, paid, redeemed and reversed-after-payout amounts. Never below 0." }, "debtCents": { "type": "number", "description": "Reversals after money left the wallet that later earnings must cover first." } }, "required": [ "rewardType", "currency", "pendingApprovalCents", "approvedCents", "reservedCents", "paidOrRedeemedCents", "availableToSpendCents", "debtCents" ] } }, "required": [ "cash", "credit" ] }, "merchant": { "type": "object", "properties": { "cash": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] }, "credit": { "type": "object", "properties": { "version": { "type": "number", "description": "Partner-wide accounting history count shared by cash, credit and program merchant balances." }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "pendingApprovalCents": { "type": "number", "description": "Pending rewards the partner is still owed." }, "approvedUndeliveredCents": { "type": "number", "description": "Approved and owed, not delivered yet and not in an open merchant payout." }, "inOpenPayoutsCents": { "type": "number", "description": "Approved and owed, allocated to a merchant payout that is queued, processing or needs action." }, "deliveredGrossCents": { "type": "number", "description": "Delivered gross amounts less returned transfers, before reward refunds or debt settlements." }, "debtCents": { "type": "number", "description": "Delivered amounts that later refunds reversed and the partner has not repaid." } }, "required": [ "version", "rewardType", "currency", "pendingApprovalCents", "approvedUndeliveredCents", "inOpenPayoutsCents", "deliveredGrossCents", "debtCents" ] } }, "required": [ "cash", "credit" ] } }, "required": [ "wallet", "merchant" ] }, "payoutAccountRequired": { "type": "boolean", "description": "True when the payout schedule waits for a Stripe account (missingStripeAccount \"wait\"), the\npartner has no stripeAccountId, and the partner earns merchant-delivered cash: it belongs to\nsuch a program or has such cash pending or approved. Scheduled runs pay this partner nothing\nuntil it gets a stripeAccountId." }, "awaitingPayoutAccount": { "type": "boolean", "description": "True when payoutAccountRequired and a scheduled run already held a payout for it." }, "awaitingPayoutAccountSince": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Due date (YYYY-MM-DD) of the first run that held a payout. Null unless awaitingPayoutAccount." } }, "required": [ "id", "externalId", "name", "active", "referralCode", "clicks", "programs", "balances", "payoutAccountRequired", "awaitingPayoutAccount", "awaitingPayoutAccountSince" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/{id}/referrals": { "get": { "operationId": "listPartnerReferrals", "summary": "Customers the partner referred, including displaced and not-yet-purchased referrals. Needs read.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 400 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "referrals": { "type": "array", "items": { "type": "object", "properties": { "milestone": { "type": "string", "description": "Milestone reports since this referral. Earned bonuses retain their original threshold." }, "milestoneCount": { "type": "number" }, "milestoneThreshold": { "type": "number", "description": "Effective at-count bonus count. Absent for each-report-only rules." }, "attributionId": { "type": "string" }, "customerId": { "type": "string", "description": "The merchant's customer ID." }, "customerDisplayName": { "type": "string" }, "programId": { "type": "string" }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The referred order for order-scoped referrals, otherwise null." }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "referredAt": { "type": "string", "description": "This partner's latest referral of the customer in this program." }, "status": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "claimed" }, { "type": "string", "const": "qualified" }, { "type": "string", "const": "displaced" } ] }, "qualifiedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Set when status is qualified." }, "firstOrderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Earliest order from this referral that earned this partner a reward." }, "orderCount": { "type": "number", "description": "Orders from this referral that earned this partner a reward. Milestone rewards are not orders." }, "milestones": { "type": "array", "items": { "type": "string" }, "description": "Milestones from this referral that earned this partner a reward, oldest first." }, "rewardedCents": { "type": "number", "description": "Those rewards after reversals." }, "incentiveAppliedCents": { "type": "number", "description": "Friend incentive discounts the merchant applied to this customer's orders through this partner's referral." } }, "required": [ "attributionId", "customerId", "programId", "orderId", "channel", "referredAt", "status", "qualifiedAt", "firstOrderId", "orderCount", "milestones", "rewardedCents", "incentiveAppliedCents" ] }, "description": "Newest first, by when Grizzlee first recorded this partner's referral." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "referrals", "nextCursor" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "referrals": { "type": "array", "items": { "type": "object", "properties": { "milestone": { "type": "string", "description": "Milestone reports since this referral. Earned bonuses retain their original threshold." }, "milestoneCount": { "type": "number" }, "milestoneThreshold": { "type": "number", "description": "Effective at-count bonus count. Absent for each-report-only rules." }, "attributionId": { "type": "string" }, "customerId": { "type": "string", "description": "The merchant's customer ID." }, "customerDisplayName": { "type": "string" }, "programId": { "type": "string" }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The referred order for order-scoped referrals, otherwise null." }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "referredAt": { "type": "string", "description": "This partner's latest referral of the customer in this program." }, "status": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "claimed" }, { "type": "string", "const": "qualified" }, { "type": "string", "const": "displaced" } ] }, "qualifiedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Set when status is qualified." }, "firstOrderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Earliest order from this referral that earned this partner a reward." }, "orderCount": { "type": "number", "description": "Orders from this referral that earned this partner a reward. Milestone rewards are not orders." }, "milestones": { "type": "array", "items": { "type": "string" }, "description": "Milestones from this referral that earned this partner a reward, oldest first." }, "rewardedCents": { "type": "number", "description": "Those rewards after reversals." }, "incentiveAppliedCents": { "type": "number", "description": "Friend incentive discounts the merchant applied to this customer's orders through this partner's referral." } }, "required": [ "attributionId", "customerId", "programId", "orderId", "channel", "referredAt", "status", "qualifiedAt", "firstOrderId", "orderCount", "milestones", "rewardedCents", "incentiveAppliedCents" ] }, "description": "Newest first, by when Grizzlee first recorded this partner's referral." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "referrals", "nextCursor" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/referrals": { "get": { "operationId": "listPartnerReferralsByExternalId", "summary": "Customers the partner referred, including displaced and not-yet-purchased referrals. Needs read.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 400 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "referrals": { "type": "array", "items": { "type": "object", "properties": { "milestone": { "type": "string", "description": "Milestone reports since this referral. Earned bonuses retain their original threshold." }, "milestoneCount": { "type": "number" }, "milestoneThreshold": { "type": "number", "description": "Effective at-count bonus count. Absent for each-report-only rules." }, "attributionId": { "type": "string" }, "customerId": { "type": "string", "description": "The merchant's customer ID." }, "customerDisplayName": { "type": "string" }, "programId": { "type": "string" }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The referred order for order-scoped referrals, otherwise null." }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "referredAt": { "type": "string", "description": "This partner's latest referral of the customer in this program." }, "status": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "claimed" }, { "type": "string", "const": "qualified" }, { "type": "string", "const": "displaced" } ] }, "qualifiedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Set when status is qualified." }, "firstOrderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Earliest order from this referral that earned this partner a reward." }, "orderCount": { "type": "number", "description": "Orders from this referral that earned this partner a reward. Milestone rewards are not orders." }, "milestones": { "type": "array", "items": { "type": "string" }, "description": "Milestones from this referral that earned this partner a reward, oldest first." }, "rewardedCents": { "type": "number", "description": "Those rewards after reversals." }, "incentiveAppliedCents": { "type": "number", "description": "Friend incentive discounts the merchant applied to this customer's orders through this partner's referral." } }, "required": [ "attributionId", "customerId", "programId", "orderId", "channel", "referredAt", "status", "qualifiedAt", "firstOrderId", "orderCount", "milestones", "rewardedCents", "incentiveAppliedCents" ] }, "description": "Newest first, by when Grizzlee first recorded this partner's referral." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "referrals", "nextCursor" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "referrals": { "type": "array", "items": { "type": "object", "properties": { "milestone": { "type": "string", "description": "Milestone reports since this referral. Earned bonuses retain their original threshold." }, "milestoneCount": { "type": "number" }, "milestoneThreshold": { "type": "number", "description": "Effective at-count bonus count. Absent for each-report-only rules." }, "attributionId": { "type": "string" }, "customerId": { "type": "string", "description": "The merchant's customer ID." }, "customerDisplayName": { "type": "string" }, "programId": { "type": "string" }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The referred order for order-scoped referrals, otherwise null." }, "channel": { "anyOf": [ { "type": "string", "const": "link" }, { "type": "string", "const": "qr" }, { "type": "string", "const": "coupon" }, { "type": "string", "const": "in_app" } ] }, "referredAt": { "type": "string", "description": "This partner's latest referral of the customer in this program." }, "status": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "claimed" }, { "type": "string", "const": "qualified" }, { "type": "string", "const": "displaced" } ] }, "qualifiedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Set when status is qualified." }, "firstOrderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Earliest order from this referral that earned this partner a reward." }, "orderCount": { "type": "number", "description": "Orders from this referral that earned this partner a reward. Milestone rewards are not orders." }, "milestones": { "type": "array", "items": { "type": "string" }, "description": "Milestones from this referral that earned this partner a reward, oldest first." }, "rewardedCents": { "type": "number", "description": "Those rewards after reversals." }, "incentiveAppliedCents": { "type": "number", "description": "Friend incentive discounts the merchant applied to this customer's orders through this partner's referral." } }, "required": [ "attributionId", "customerId", "programId", "orderId", "channel", "referredAt", "status", "qualifiedAt", "firstOrderId", "orderCount", "milestones", "rewardedCents", "incentiveAppliedCents" ] }, "description": "Newest first, by when Grizzlee first recorded this partner's referral." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "referrals", "nextCursor" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/{id}/rewards": { "get": { "operationId": "listPartnerRewards", "summary": "The partner's rewards, newest first, with delivery state. Needs read.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 400 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "reversed" ] } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "rewardType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cash", "credit", "offer" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "rewards": { "type": "array", "items": { "type": "object", "properties": { "milestoneCount": { "type": "number", "description": "Current milestone reports." }, "milestoneThreshold": { "type": "number", "description": "Saved at-count bonus count. Absent for each-report rewards." }, "id": { "type": "string" }, "trigger": { "anyOf": [ { "type": "string", "const": "order" }, { "type": "string", "const": "milestone" } ], "description": "What earned the reward." }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The order that earned it. Null for milestone rewards." }, "milestone": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The milestone that earned it. Null for order rewards." }, "reportEventId": { "type": "string" }, "valueCents": { "type": "number" }, "programId": { "type": "string" }, "programVersion": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "The program version the reward was earned under. Null for rewards earned before programs had versions." }, "customerId": { "type": "string", "description": "The merchant's customer ID." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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" ] } ] }, "status": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "pending" }, { "type": "string", "const": "available" }, { "type": "string", "const": "used" }, { "type": "string", "const": "voided" } ] }, "usesRemaining": { "type": "number" }, "usedCount": { "type": "number" }, "heldCount": { "type": "number" }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "status", "usesRemaining", "usedCount", "heldCount", "expiresAt" ], "description": "Offer rewards only." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "amountCents": { "type": "number", "description": "Current value: originalCents + adjustedCents - reversedCents." }, "originalCents": { "type": "number" }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added or removed. 0 when the order was never adjusted." }, "reversedCents": { "type": "number" }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ] }, "delivery": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "const": "not_applicable" }, { "type": "string", "const": "undelivered" }, { "type": "string", "const": "in_payout" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Reference of the latest delivered record, or of the failed attempt when status is failed. Null if none." }, "deliveredAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the latest delivered record says the partner received it." }, "payoutId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The open payout when status is in_payout. Otherwise the payout that recorded the latest delivery, if any." } }, "required": [ "status", "externalReference", "deliveredAt", "payoutId" ] }, "createdAt": { "type": "string" }, "approvedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "First recorded approval. Rewards that started approved use createdAt. Null if never approved." }, "availableAt": { "type": "string" } }, "required": [ "id", "trigger", "orderId", "milestone", "programId", "programVersion", "customerId", "currency", "rewardType", "status", "amountCents", "originalCents", "adjustedCents", "reversedCents", "deliveryMode", "delivery", "createdAt", "approvedAt", "availableAt" ] }, "description": "Newest first, ordered by creation time and then ID." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "rewards", "nextCursor" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "rewards": { "type": "array", "items": { "type": "object", "properties": { "milestoneCount": { "type": "number", "description": "Current milestone reports." }, "milestoneThreshold": { "type": "number", "description": "Saved at-count bonus count. Absent for each-report rewards." }, "id": { "type": "string" }, "trigger": { "anyOf": [ { "type": "string", "const": "order" }, { "type": "string", "const": "milestone" } ], "description": "What earned the reward." }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The order that earned it. Null for milestone rewards." }, "milestone": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The milestone that earned it. Null for order rewards." }, "reportEventId": { "type": "string" }, "valueCents": { "type": "number" }, "programId": { "type": "string" }, "programVersion": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "The program version the reward was earned under. Null for rewards earned before programs had versions." }, "customerId": { "type": "string", "description": "The merchant's customer ID." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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" ] } ] }, "status": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "pending" }, { "type": "string", "const": "available" }, { "type": "string", "const": "used" }, { "type": "string", "const": "voided" } ] }, "usesRemaining": { "type": "number" }, "usedCount": { "type": "number" }, "heldCount": { "type": "number" }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "status", "usesRemaining", "usedCount", "heldCount", "expiresAt" ], "description": "Offer rewards only." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "amountCents": { "type": "number", "description": "Current value: originalCents + adjustedCents - reversedCents." }, "originalCents": { "type": "number" }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added or removed. 0 when the order was never adjusted." }, "reversedCents": { "type": "number" }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ] }, "delivery": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "const": "not_applicable" }, { "type": "string", "const": "undelivered" }, { "type": "string", "const": "in_payout" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Reference of the latest delivered record, or of the failed attempt when status is failed. Null if none." }, "deliveredAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the latest delivered record says the partner received it." }, "payoutId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The open payout when status is in_payout. Otherwise the payout that recorded the latest delivery, if any." } }, "required": [ "status", "externalReference", "deliveredAt", "payoutId" ] }, "createdAt": { "type": "string" }, "approvedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "First recorded approval. Rewards that started approved use createdAt. Null if never approved." }, "availableAt": { "type": "string" } }, "required": [ "id", "trigger", "orderId", "milestone", "programId", "programVersion", "customerId", "currency", "rewardType", "status", "amountCents", "originalCents", "adjustedCents", "reversedCents", "deliveryMode", "delivery", "createdAt", "approvedAt", "availableAt" ] }, "description": "Newest first, ordered by creation time and then ID." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "rewards", "nextCursor" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/rewards": { "get": { "operationId": "listPartnerRewardsByExternalId", "summary": "The partner's rewards, newest first, with delivery state. Needs read.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 400 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "approved", "reversed" ] } }, { "name": "programId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 120 } }, { "name": "rewardType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "cash", "credit", "offer" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "rewards": { "type": "array", "items": { "type": "object", "properties": { "milestoneCount": { "type": "number", "description": "Current milestone reports." }, "milestoneThreshold": { "type": "number", "description": "Saved at-count bonus count. Absent for each-report rewards." }, "id": { "type": "string" }, "trigger": { "anyOf": [ { "type": "string", "const": "order" }, { "type": "string", "const": "milestone" } ], "description": "What earned the reward." }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The order that earned it. Null for milestone rewards." }, "milestone": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The milestone that earned it. Null for order rewards." }, "reportEventId": { "type": "string" }, "valueCents": { "type": "number" }, "programId": { "type": "string" }, "programVersion": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "The program version the reward was earned under. Null for rewards earned before programs had versions." }, "customerId": { "type": "string", "description": "The merchant's customer ID." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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" ] } ] }, "status": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "pending" }, { "type": "string", "const": "available" }, { "type": "string", "const": "used" }, { "type": "string", "const": "voided" } ] }, "usesRemaining": { "type": "number" }, "usedCount": { "type": "number" }, "heldCount": { "type": "number" }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "status", "usesRemaining", "usedCount", "heldCount", "expiresAt" ], "description": "Offer rewards only." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "amountCents": { "type": "number", "description": "Current value: originalCents + adjustedCents - reversedCents." }, "originalCents": { "type": "number" }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added or removed. 0 when the order was never adjusted." }, "reversedCents": { "type": "number" }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ] }, "delivery": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "const": "not_applicable" }, { "type": "string", "const": "undelivered" }, { "type": "string", "const": "in_payout" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Reference of the latest delivered record, or of the failed attempt when status is failed. Null if none." }, "deliveredAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the latest delivered record says the partner received it." }, "payoutId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The open payout when status is in_payout. Otherwise the payout that recorded the latest delivery, if any." } }, "required": [ "status", "externalReference", "deliveredAt", "payoutId" ] }, "createdAt": { "type": "string" }, "approvedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "First recorded approval. Rewards that started approved use createdAt. Null if never approved." }, "availableAt": { "type": "string" } }, "required": [ "id", "trigger", "orderId", "milestone", "programId", "programVersion", "customerId", "currency", "rewardType", "status", "amountCents", "originalCents", "adjustedCents", "reversedCents", "deliveryMode", "delivery", "createdAt", "approvedAt", "availableAt" ] }, "description": "Newest first, ordered by creation time and then ID." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "rewards", "nextCursor" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "rewards": { "type": "array", "items": { "type": "object", "properties": { "milestoneCount": { "type": "number", "description": "Current milestone reports." }, "milestoneThreshold": { "type": "number", "description": "Saved at-count bonus count. Absent for each-report rewards." }, "id": { "type": "string" }, "trigger": { "anyOf": [ { "type": "string", "const": "order" }, { "type": "string", "const": "milestone" } ], "description": "What earned the reward." }, "orderId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The order that earned it. Null for milestone rewards." }, "milestone": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The milestone that earned it. Null for order rewards." }, "reportEventId": { "type": "string" }, "valueCents": { "type": "number" }, "programId": { "type": "string" }, "programVersion": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "The program version the reward was earned under. Null for rewards earned before programs had versions." }, "customerId": { "type": "string", "description": "The merchant's customer ID." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "offer" }, { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "offer": { "type": "object", "properties": { "terms": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "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" ] } ] }, "status": { "anyOf": [ { "type": "string", "const": "expired" }, { "type": "string", "const": "pending" }, { "type": "string", "const": "available" }, { "type": "string", "const": "used" }, { "type": "string", "const": "voided" } ] }, "usesRemaining": { "type": "number" }, "usedCount": { "type": "number" }, "heldCount": { "type": "number" }, "expiresAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "terms", "status", "usesRemaining", "usedCount", "heldCount", "expiresAt" ], "description": "Offer rewards only." }, "status": { "anyOf": [ { "type": "string", "const": "pending" }, { "type": "string", "const": "reversed" }, { "type": "string", "const": "approved" } ] }, "amountCents": { "type": "number", "description": "Current value: originalCents + adjustedCents - reversedCents." }, "originalCents": { "type": "number" }, "adjustedCents": { "type": "number", "description": "Signed total that order adjustments added or removed. 0 when the order was never adjusted." }, "reversedCents": { "type": "number" }, "deliveryMode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ] }, "delivery": { "type": "object", "properties": { "status": { "anyOf": [ { "type": "string", "const": "not_applicable" }, { "type": "string", "const": "undelivered" }, { "type": "string", "const": "in_payout" }, { "type": "string", "const": "delivered" }, { "type": "string", "const": "failed" } ] }, "externalReference": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Reference of the latest delivered record, or of the failed attempt when status is failed. Null if none." }, "deliveredAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the latest delivered record says the partner received it." }, "payoutId": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The open payout when status is in_payout. Otherwise the payout that recorded the latest delivery, if any." } }, "required": [ "status", "externalReference", "deliveredAt", "payoutId" ] }, "createdAt": { "type": "string" }, "approvedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "First recorded approval. Rewards that started approved use createdAt. Null if never approved." }, "availableAt": { "type": "string" } }, "required": [ "id", "trigger", "orderId", "milestone", "programId", "programVersion", "customerId", "currency", "rewardType", "status", "amountCents", "originalCents", "adjustedCents", "reversedCents", "deliveryMode", "delivery", "createdAt", "approvedAt", "availableAt" ] }, "description": "Newest first, ordered by creation time and then ID." }, "nextCursor": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "Pass as cursor to read the next page. Null on the last page." } }, "required": [ "rewards", "nextCursor" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/{id}/erase": { "post": { "operationId": "erasePartner", "summary": "Erase a partner's personal data when the person deletes their account with you. Grizzlee keeps\namounts, dates, statuses, IDs and the ledger, and the partner can never earn again. Safe to\nrepeat. Needs partners:write.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "erasedAt": { "type": "string", "description": "When the partner was first erased." }, "alreadyErased": { "type": "boolean", "description": "True when an earlier call already erased the partner. This call still removed anything new." }, "erased": { "type": "object", "properties": { "identitySignals": { "type": "number", "description": "Hashed identity signals deleted." }, "orderEmails": { "type": "number", "description": "Orders whose customerEmail was removed. Customers only." }, "customerDisplayNames": { "type": "number", "description": "Saved display names removed from referrals, orders and cached claims. Customers only." }, "events": { "type": "number", "description": "Saved copies of processed events that lost an email or a revocation, reinstatement or order\nadjustment reason.\nCustomers only." }, "notes": { "type": "number", "description": "Free-text reasons replaced with ERASED_TEXT: reward rejection reasons, milestone revocation\nand reinstatement reasons, failed delivery reasons and, for customers, the reasons on their\norders' adjustments. Also counts provider promo code names erased for a partner.\nEach order counts once." }, "auditEntries": { "type": "number", "description": "Activity log entries rewritten without the name or reasons." }, "webhookEvents": { "type": "number", "description": "Webhook payloads rewritten, delivered or not." }, "providerEvents": { "type": "number", "description": "Raw payment provider webhook bodies deleted. Customers only." }, "embedSessions": { "type": "number", "description": "Embed sessions deleted. Partners only." }, "partnerAccess": { "type": "number", "description": "Partner dashboard memberships and invitations removed, plus stored logins no company uses\nany more. Partners only." }, "partnerEmails": { "type": "number", "description": "Partner email log rows whose recipient address was removed, plus queued emails that will not\nbe sent. Partners only." } }, "required": [ "identitySignals", "orderEmails", "customerDisplayNames", "events", "notes", "auditEntries", "webhookEvents", "providerEvents", "embedSessions", "partnerAccess", "partnerEmails" ] }, "outstanding": { "type": "object", "properties": { "pendingRewards": { "type": "number", "description": "Rewards waiting for approval." }, "openPayouts": { "type": "number", "description": "Payouts queued, processing or needing action." } }, "required": [ "pendingRewards", "openPayouts" ], "description": "Money the partner may still be owed. Erasure keeps every amount, so you can still approve,\ndeliver and pay these." }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" } }, "required": [ "erasedAt", "alreadyErased", "erased", "outstanding", "partnerId", "partnerExternalId" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "erasedAt": { "type": "string", "description": "When the partner was first erased." }, "alreadyErased": { "type": "boolean", "description": "True when an earlier call already erased the partner. This call still removed anything new." }, "erased": { "type": "object", "properties": { "identitySignals": { "type": "number", "description": "Hashed identity signals deleted." }, "orderEmails": { "type": "number", "description": "Orders whose customerEmail was removed. Customers only." }, "customerDisplayNames": { "type": "number", "description": "Saved display names removed from referrals, orders and cached claims. Customers only." }, "events": { "type": "number", "description": "Saved copies of processed events that lost an email or a revocation, reinstatement or order\nadjustment reason.\nCustomers only." }, "notes": { "type": "number", "description": "Free-text reasons replaced with ERASED_TEXT: reward rejection reasons, milestone revocation\nand reinstatement reasons, failed delivery reasons and, for customers, the reasons on their\norders' adjustments. Also counts provider promo code names erased for a partner.\nEach order counts once." }, "auditEntries": { "type": "number", "description": "Activity log entries rewritten without the name or reasons." }, "webhookEvents": { "type": "number", "description": "Webhook payloads rewritten, delivered or not." }, "providerEvents": { "type": "number", "description": "Raw payment provider webhook bodies deleted. Customers only." }, "embedSessions": { "type": "number", "description": "Embed sessions deleted. Partners only." }, "partnerAccess": { "type": "number", "description": "Partner dashboard memberships and invitations removed, plus stored logins no company uses\nany more. Partners only." }, "partnerEmails": { "type": "number", "description": "Partner email log rows whose recipient address was removed, plus queued emails that will not\nbe sent. Partners only." } }, "required": [ "identitySignals", "orderEmails", "customerDisplayNames", "events", "notes", "auditEntries", "webhookEvents", "providerEvents", "embedSessions", "partnerAccess", "partnerEmails" ] }, "outstanding": { "type": "object", "properties": { "pendingRewards": { "type": "number", "description": "Rewards waiting for approval." }, "openPayouts": { "type": "number", "description": "Payouts queued, processing or needing action." } }, "required": [ "pendingRewards", "openPayouts" ], "description": "Money the partner may still be owed. Erasure keeps every amount, so you can still approve,\ndeliver and pay these." }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" } }, "required": [ "erasedAt", "alreadyErased", "erased", "outstanding", "partnerId", "partnerExternalId" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/by-external-id/{externalId}/erase": { "post": { "operationId": "erasePartnerByExternalId", "summary": "Erase a partner's personal data when the person deletes their account with you. Grizzlee keeps\namounts, dates, statuses, IDs and the ledger, and the partner can never earn again. Safe to\nrepeat. Needs partners:write.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "erasedAt": { "type": "string", "description": "When the partner was first erased." }, "alreadyErased": { "type": "boolean", "description": "True when an earlier call already erased the partner. This call still removed anything new." }, "erased": { "type": "object", "properties": { "identitySignals": { "type": "number", "description": "Hashed identity signals deleted." }, "orderEmails": { "type": "number", "description": "Orders whose customerEmail was removed. Customers only." }, "customerDisplayNames": { "type": "number", "description": "Saved display names removed from referrals, orders and cached claims. Customers only." }, "events": { "type": "number", "description": "Saved copies of processed events that lost an email or a revocation, reinstatement or order\nadjustment reason.\nCustomers only." }, "notes": { "type": "number", "description": "Free-text reasons replaced with ERASED_TEXT: reward rejection reasons, milestone revocation\nand reinstatement reasons, failed delivery reasons and, for customers, the reasons on their\norders' adjustments. Also counts provider promo code names erased for a partner.\nEach order counts once." }, "auditEntries": { "type": "number", "description": "Activity log entries rewritten without the name or reasons." }, "webhookEvents": { "type": "number", "description": "Webhook payloads rewritten, delivered or not." }, "providerEvents": { "type": "number", "description": "Raw payment provider webhook bodies deleted. Customers only." }, "embedSessions": { "type": "number", "description": "Embed sessions deleted. Partners only." }, "partnerAccess": { "type": "number", "description": "Partner dashboard memberships and invitations removed, plus stored logins no company uses\nany more. Partners only." }, "partnerEmails": { "type": "number", "description": "Partner email log rows whose recipient address was removed, plus queued emails that will not\nbe sent. Partners only." } }, "required": [ "identitySignals", "orderEmails", "customerDisplayNames", "events", "notes", "auditEntries", "webhookEvents", "providerEvents", "embedSessions", "partnerAccess", "partnerEmails" ] }, "outstanding": { "type": "object", "properties": { "pendingRewards": { "type": "number", "description": "Rewards waiting for approval." }, "openPayouts": { "type": "number", "description": "Payouts queued, processing or needing action." } }, "required": [ "pendingRewards", "openPayouts" ], "description": "Money the partner may still be owed. Erasure keeps every amount, so you can still approve,\ndeliver and pay these." }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" } }, "required": [ "erasedAt", "alreadyErased", "erased", "outstanding", "partnerId", "partnerExternalId" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "erasedAt": { "type": "string", "description": "When the partner was first erased." }, "alreadyErased": { "type": "boolean", "description": "True when an earlier call already erased the partner. This call still removed anything new." }, "erased": { "type": "object", "properties": { "identitySignals": { "type": "number", "description": "Hashed identity signals deleted." }, "orderEmails": { "type": "number", "description": "Orders whose customerEmail was removed. Customers only." }, "customerDisplayNames": { "type": "number", "description": "Saved display names removed from referrals, orders and cached claims. Customers only." }, "events": { "type": "number", "description": "Saved copies of processed events that lost an email or a revocation, reinstatement or order\nadjustment reason.\nCustomers only." }, "notes": { "type": "number", "description": "Free-text reasons replaced with ERASED_TEXT: reward rejection reasons, milestone revocation\nand reinstatement reasons, failed delivery reasons and, for customers, the reasons on their\norders' adjustments. Also counts provider promo code names erased for a partner.\nEach order counts once." }, "auditEntries": { "type": "number", "description": "Activity log entries rewritten without the name or reasons." }, "webhookEvents": { "type": "number", "description": "Webhook payloads rewritten, delivered or not." }, "providerEvents": { "type": "number", "description": "Raw payment provider webhook bodies deleted. Customers only." }, "embedSessions": { "type": "number", "description": "Embed sessions deleted. Partners only." }, "partnerAccess": { "type": "number", "description": "Partner dashboard memberships and invitations removed, plus stored logins no company uses\nany more. Partners only." }, "partnerEmails": { "type": "number", "description": "Partner email log rows whose recipient address was removed, plus queued emails that will not\nbe sent. Partners only." } }, "required": [ "identitySignals", "orderEmails", "customerDisplayNames", "events", "notes", "auditEntries", "webhookEvents", "providerEvents", "embedSessions", "partnerAccess", "partnerEmails" ] }, "outstanding": { "type": "object", "properties": { "pendingRewards": { "type": "number", "description": "Rewards waiting for approval." }, "openPayouts": { "type": "number", "description": "Payouts queued, processing or needing action." } }, "required": [ "pendingRewards", "openPayouts" ], "description": "Money the partner may still be owed. Erasure keeps every amount, so you can still approve,\ndeliver and pay these." }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" } }, "required": [ "erasedAt", "alreadyErased", "erased", "outstanding", "partnerId", "partnerExternalId" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/customers/{customerId}/erase": { "post": { "operationId": "eraseCustomer", "summary": "Erase a referred customer's personal data: order emails, identity signals, reasons and raw\nprovider bodies. Orders and rewards keep the customer ID. Safe to repeat. Needs partners:write.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "partners:write" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "customerId": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the customer was first erased." }, "alreadyErased": { "type": "boolean", "description": "True when an earlier call already erased the customer. This call still removed anything new." }, "erased": { "type": "object", "properties": { "identitySignals": { "type": "number", "description": "Hashed identity signals deleted." }, "orderEmails": { "type": "number", "description": "Orders whose customerEmail was removed. Customers only." }, "customerDisplayNames": { "type": "number", "description": "Saved display names removed from referrals, orders and cached claims. Customers only." }, "events": { "type": "number", "description": "Saved copies of processed events that lost an email or a revocation, reinstatement or order\nadjustment reason.\nCustomers only." }, "notes": { "type": "number", "description": "Free-text reasons replaced with ERASED_TEXT: reward rejection reasons, milestone revocation\nand reinstatement reasons, failed delivery reasons and, for customers, the reasons on their\norders' adjustments. Also counts provider promo code names erased for a partner.\nEach order counts once." }, "auditEntries": { "type": "number", "description": "Activity log entries rewritten without the name or reasons." }, "webhookEvents": { "type": "number", "description": "Webhook payloads rewritten, delivered or not." }, "providerEvents": { "type": "number", "description": "Raw payment provider webhook bodies deleted. Customers only." }, "embedSessions": { "type": "number", "description": "Embed sessions deleted. Partners only." }, "partnerAccess": { "type": "number", "description": "Partner dashboard memberships and invitations removed, plus stored logins no company uses\nany more. Partners only." }, "partnerEmails": { "type": "number", "description": "Partner email log rows whose recipient address was removed, plus queued emails that will not\nbe sent. Partners only." } }, "required": [ "identitySignals", "orderEmails", "customerDisplayNames", "events", "notes", "auditEntries", "webhookEvents", "providerEvents", "embedSessions", "partnerAccess", "partnerEmails" ] } }, "required": [ "customerId", "erasedAt", "alreadyErased", "erased" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "customerId": { "type": "string" }, "erasedAt": { "type": "string", "description": "When the customer was first erased." }, "alreadyErased": { "type": "boolean", "description": "True when an earlier call already erased the customer. This call still removed anything new." }, "erased": { "type": "object", "properties": { "identitySignals": { "type": "number", "description": "Hashed identity signals deleted." }, "orderEmails": { "type": "number", "description": "Orders whose customerEmail was removed. Customers only." }, "customerDisplayNames": { "type": "number", "description": "Saved display names removed from referrals, orders and cached claims. Customers only." }, "events": { "type": "number", "description": "Saved copies of processed events that lost an email or a revocation, reinstatement or order\nadjustment reason.\nCustomers only." }, "notes": { "type": "number", "description": "Free-text reasons replaced with ERASED_TEXT: reward rejection reasons, milestone revocation\nand reinstatement reasons, failed delivery reasons and, for customers, the reasons on their\norders' adjustments. Also counts provider promo code names erased for a partner.\nEach order counts once." }, "auditEntries": { "type": "number", "description": "Activity log entries rewritten without the name or reasons." }, "webhookEvents": { "type": "number", "description": "Webhook payloads rewritten, delivered or not." }, "providerEvents": { "type": "number", "description": "Raw payment provider webhook bodies deleted. Customers only." }, "embedSessions": { "type": "number", "description": "Embed sessions deleted. Partners only." }, "partnerAccess": { "type": "number", "description": "Partner dashboard memberships and invitations removed, plus stored logins no company uses\nany more. Partners only." }, "partnerEmails": { "type": "number", "description": "Partner email log rows whose recipient address was removed, plus queued emails that will not\nbe sent. Partners only." } }, "required": [ "identitySignals", "orderEmails", "customerDisplayNames", "events", "notes", "auditEntries", "webhookEvents", "providerEvents", "embedSessions", "partnerAccess", "partnerEmails" ] } }, "required": [ "customerId", "erasedAt", "alreadyErased", "erased" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/embed/sessions": { "post": { "operationId": "createEmbedSession", "summary": "Start an embedded partner dashboard session. Load the returned url in an iframe once. Its\nstart token works one time and expires with the session. ttlSeconds accepts 60 to 600 and\ndefaults to 600. Needs embed:write.", "description": "Send placement or programIds, or omit both for an unrestricted session. layout defaults to full whether or not you send a placement. New placement enrollments require an active program and share the session transaction.", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "embed:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partner": { "anyOf": [ { "type": "object", "properties": { "externalId": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "externalId" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "id" ], "additionalProperties": false } ] }, "locale": { "type": "string", "enum": [ "en", "fr-CA", "hy", "ru" ] }, "layout": { "type": "string", "enum": [ "full", "simple" ], "default": "full" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "payout_details:write", "profile:write" ] }, "maxItems": 2, "default": [] }, "ttlSeconds": { "type": "integer", "minimum": 60, "maximum": 600, "default": 600 }, "embedOrigin": { "type": "string", "format": "uri" }, "placement": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,62}$" }, "programIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "minItems": 1 } }, "required": [ "partner" ], "additionalProperties": false }, "example": { "partner": { "externalId": "merchant-partner-001" } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "Load this URL in the iframe once. The start token is in the fragment and works one time." }, "id": { "type": "string" }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" }, "programIds": { "anyOf": [ { "type": "null" }, { "type": "array", "items": { "type": "string" } } ], "description": "Null includes all programs. Otherwise only these memberships are visible." }, "placement": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "locale": { "anyOf": [ { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ] }, "layout": { "anyOf": [ { "type": "string", "const": "full" }, { "type": "string", "const": "simple" } ] }, "actions": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "payout_details:write" }, { "type": "string", "const": "profile:write" } ] } }, "embedOrigin": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The parent page origin the merchant expects, or null when the session allows any listed origin." }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "consumedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the frame exchanged the start token." }, "revokedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "url", "id", "partnerId", "partnerExternalId", "programIds", "placement", "locale", "layout", "actions", "embedOrigin", "expiresAt", "createdAt", "consumedAt", "revokedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "url": { "type": "string", "description": "Load this URL in the iframe once. The start token is in the fragment and works one time." }, "id": { "type": "string" }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" }, "programIds": { "anyOf": [ { "type": "null" }, { "type": "array", "items": { "type": "string" } } ], "description": "Null includes all programs. Otherwise only these memberships are visible." }, "placement": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "locale": { "anyOf": [ { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ] }, "layout": { "anyOf": [ { "type": "string", "const": "full" }, { "type": "string", "const": "simple" } ] }, "actions": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "payout_details:write" }, { "type": "string", "const": "profile:write" } ] } }, "embedOrigin": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The parent page origin the merchant expects, or null when the session allows any listed origin." }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "consumedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the frame exchanged the start token." }, "revokedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "url", "id", "partnerId", "partnerExternalId", "programIds", "placement", "locale", "layout", "actions", "embedOrigin", "expiresAt", "createdAt", "consumedAt", "revokedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/embed/sessions/{sessionId}": { "delete": { "operationId": "revokeEmbedSession", "summary": "End a session before it expires. The frame's next read fails with session_expired. Needs embed:write.", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "embed:write" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" }, "programIds": { "anyOf": [ { "type": "null" }, { "type": "array", "items": { "type": "string" } } ], "description": "Null includes all programs. Otherwise only these memberships are visible." }, "placement": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "locale": { "anyOf": [ { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ] }, "layout": { "anyOf": [ { "type": "string", "const": "full" }, { "type": "string", "const": "simple" } ] }, "actions": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "payout_details:write" }, { "type": "string", "const": "profile:write" } ] } }, "embedOrigin": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The parent page origin the merchant expects, or null when the session allows any listed origin." }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "consumedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the frame exchanged the start token." }, "revokedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "partnerId", "partnerExternalId", "programIds", "placement", "locale", "layout", "actions", "embedOrigin", "expiresAt", "createdAt", "consumedAt", "revokedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "partnerId": { "type": "string" }, "partnerExternalId": { "type": "string" }, "programIds": { "anyOf": [ { "type": "null" }, { "type": "array", "items": { "type": "string" } } ], "description": "Null includes all programs. Otherwise only these memberships are visible." }, "placement": { "anyOf": [ { "type": "null" }, { "type": "string" } ] }, "locale": { "anyOf": [ { "type": "string", "const": "en" }, { "type": "string", "const": "fr-CA" }, { "type": "string", "const": "hy" }, { "type": "string", "const": "ru" } ] }, "layout": { "anyOf": [ { "type": "string", "const": "full" }, { "type": "string", "const": "simple" } ] }, "actions": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "payout_details:write" }, { "type": "string", "const": "profile:write" } ] } }, "embedOrigin": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "The parent page origin the merchant expects, or null when the session allows any listed origin." }, "expiresAt": { "type": "string" }, "createdAt": { "type": "string" }, "consumedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ], "description": "When the frame exchanged the start token." }, "revokedAt": { "anyOf": [ { "type": "null" }, { "type": "string" } ] } }, "required": [ "id", "partnerId", "partnerExternalId", "programIds", "placement", "locale", "layout", "actions", "embedOrigin", "expiresAt", "createdAt", "consumedAt", "revokedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/payouts/{payoutId}": { "get": { "operationId": "getPayout", "summary": "getPayout", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "payouts:write" ], "parameters": [ { "name": "payoutId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "allocations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "payoutId": { "type": "string" }, "partnerId": { "type": "string" }, "rewardId": { "type": "string" }, "orderId": { "type": "string", "description": "The reward's order. Absent for milestone rewards." }, "milestone": { "type": "string", "description": "The reward's milestone. Absent for order rewards." }, "programId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "payoutId", "partnerId", "rewardId", "programId", "currency", "amountCents", "createdAt" ] } }, "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number", "description": "Gross amount. Merchant allocations sum to this amount." }, "nettedDebtCents": { "type": "number", "description": "Debt kept from a merchant payout. Defaults to zero on older payouts." }, "netAmountCents": { "type": "number", "description": "Transfer amount, equal to amountCents minus nettedDebtCents." }, "status": { "anyOf": [ { "type": "string", "const": "reversed" }, { "type": "string", "const": "failed" }, { "type": "string", "const": "queued" }, { "type": "string", "const": "processing" }, { "type": "string", "const": "needs_action" }, { "type": "string", "const": "paid" }, { "type": "string", "const": "cancelled" } ] }, "reversedCents": { "type": "number", "description": "Cumulative Stripe transfer amount returned to the merchant, in minor units." }, "reversedAt": { "type": "string", "description": "When Grizzlee last recorded an increase in reversedCents." }, "provider": { "anyOf": [ { "type": "string", "const": "manual" }, { "type": "string", "const": "stripe" } ], "description": "manual: the merchant sends the money and marks the payout paid. stripe: Grizzlee sends a Stripe\ntransfer from the merchant's Stripe balance and marks the payout paid or failed itself." }, "mode": { "anyOf": [ { "type": "string", "const": "grizzlee_wallet" }, { "type": "string", "const": "merchant" } ], "description": "grizzlee_wallet reserves the partner's available wallet cash. merchant pays specific\nmerchant-delivered rewards listed in allocations. Absent on payouts created before merchant\npayouts existed, which use the wallet." }, "integrationId": { "type": "string", "description": "Stripe connection that sends the transfer. Stripe payouts only." }, "destination": { "type": "string", "description": "Stripe connected account that receives the transfer. Stripe payouts only." }, "providerReference": { "type": "string", "description": "The Stripe transfer ID or the merchant's own payment reference once paid." }, "transferGroup": { "type": "string", "description": "Stripe transfer_group Grizzlee sets on the transfer, grizzlee_payout_." }, "paidAt": { "type": "string", "description": "When the partner received the money, if the merchant reported it." }, "lastError": { "type": "string" }, "lastErrorParts": { "type": "array", "items": { "type": "object", "properties": { "code": { "anyOf": [ { "type": "string", "const": "retries_stopped" }, { "type": "string", "const": "connection_disabled" }, { "type": "string", "const": "connection_unavailable" }, { "type": "string", "const": "debt_settled" }, { "type": "string", "const": "payout_changed" }, { "type": "string", "const": "delivery_failed" }, { "type": "string", "const": "no_transfer_sent" }, { "type": "string", "const": "rewards_payable" }, { "type": "string", "const": "refund_reduced_earnings" }, { "type": "string", "const": "rewards_not_marked" }, { "type": "string", "const": "contact_support" }, { "type": "string", "const": "transfer_unmatched" }, { "type": "string", "const": "stripe_key_rejected" }, { "type": "string", "const": "stripe_key_permission" }, { "type": "string", "const": "stripe_insufficient_funds" }, { "type": "string", "const": "partner_onboarding" }, { "type": "string", "const": "partner_account_missing" }, { "type": "string", "const": "stripe_rejected" }, { "type": "string", "const": "stripe_rejected_code" }, { "type": "string", "const": "answer_kept" }, { "type": "string", "const": "search_failed" }, { "type": "string", "const": "not_confirmed" }, { "type": "string", "const": "rewards_kept" }, { "type": "string", "const": "earnings_reserved" }, { "type": "string", "const": "transfer_conflict" }, { "type": "string", "const": "transfers_conflict" }, { "type": "string", "const": "check_transfer_group" }, { "type": "string", "const": "check_transfer_metadata" }, { "type": "string", "const": "cancelled_no_transfer" } ] }, "params": { "type": "object", "properties": {}, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ] } } }, "required": [ "code" ] }, "description": "lastError as codes. Absent on errors recorded before codes existed." }, "eventId": { "type": "string" }, "schedule": { "type": "object", "properties": { "dueOn": { "type": "string", "description": "Due date of the run, YYYY-MM-DD in UTC." }, "approvedBefore": { "type": "string", "description": "The run paid rewards approved at or before this time: the due date minus the hold period." } }, "required": [ "dueOn", "approvedBefore" ], "description": "Present when Grizzlee created this merchant payout from the company's payout schedule." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "allocations", "id", "companyId", "partnerId", "currency", "amountCents", "status", "provider", "eventId", "createdAt", "updatedAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/partners/{partnerId}/wallets": { "get": { "operationId": "getWallets", "summary": "getWallets", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read" ], "parameters": [ { "name": "partnerId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingCents": { "type": "number" }, "approvedCents": { "type": "number" }, "reservedCents": { "type": "number" }, "paidCents": { "type": "number" }, "availableCents": { "type": "number" }, "debtCents": { "type": "number" } }, "required": [ "partnerId", "currency", "rewardType", "pendingCents", "approvedCents", "reservedCents", "paidCents", "availableCents", "debtCents" ] } } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "partnerId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "rewardType": { "anyOf": [ { "type": "string", "const": "cash" }, { "type": "string", "const": "credit" } ] }, "pendingCents": { "type": "number" }, "approvedCents": { "type": "number" }, "reservedCents": { "type": "number" }, "paidCents": { "type": "number" }, "availableCents": { "type": "number" }, "debtCents": { "type": "number" } }, "required": [ "partnerId", "currency", "rewardType", "pendingCents", "approvedCents", "reservedCents", "paidCents", "availableCents", "debtCents" ] } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/credits/redeem": { "post": { "operationId": "redeemCredits", "summary": "redeemCredits", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "credits:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerId": { "type": "string", "minLength": 1, "maxLength": 120 }, "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "orderId": { "type": "string", "minLength": 1, "maxLength": 120 }, "amountCents": { "type": "integer", "exclusiveMinimum": 0, "maximum": 1000000000000 } }, "required": [ "partnerId", "eventId", "orderId", "amountCents" ], "additionalProperties": false }, "example": { "partnerId": "partner-example", "eventId": "payment-example", "orderId": "order-example", "amountCents": 10000 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "eventId": { "type": "string" }, "orderId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "restoredCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "eventId", "orderId", "currency", "amountCents", "restoredCents", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "eventId": { "type": "string" }, "orderId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "restoredCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "eventId", "orderId", "currency", "amountCents", "restoredCents", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/credits/{id}/restore": { "post": { "operationId": "restoreCredits", "summary": "restoreCredits", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "credits:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1, "maxLength": 120 }, "restoredCents": { "type": "integer", "minimum": 0, "maximum": 1000000000000 } }, "required": [ "eventId", "restoredCents" ], "additionalProperties": false }, "example": { "eventId": "payment-example", "restoredCents": 500 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "eventId": { "type": "string" }, "orderId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "restoredCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "eventId", "orderId", "currency", "amountCents", "restoredCents", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "partnerId": { "type": "string" }, "eventId": { "type": "string" }, "orderId": { "type": "string" }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] }, "amountCents": { "type": "number" }, "restoredCents": { "type": "number" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "partnerId", "eventId", "orderId", "currency", "amountCents", "restoredCents", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/tracking/{key}/placements/{placementKey}": { "get": { "operationId": "resolvePlacement", "summary": "resolvePlacement", "description": "", "security": [], "x-required-scopes": [], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "placementKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "placement": { "type": "string" }, "programId": { "type": "string" }, "active": { "type": "boolean" }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "The program's public name, headline and milestone label." } }, "required": [ "placement", "programId", "active", "display" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "placement": { "type": "string" }, "programId": { "type": "string" }, "active": { "type": "boolean" }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "The program's public name, headline and milestone label." } }, "required": [ "placement", "programId", "active", "display" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/webhooks": { "get": { "operationId": "listWebhooks", "summary": "listWebhooks", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "read", "settings:write" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "order.refunded" }, { "type": "string", "const": "order.adjusted" }, { "type": "string", "const": "order.completed" }, { "type": "string", "const": "partner.created" }, { "type": "string", "const": "reward.created" }, { "type": "string", "const": "reward.approved" }, { "type": "string", "const": "reward.reversed" }, { "type": "string", "const": "reward.restored" }, { "type": "string", "const": "reward.adjusted" }, { "type": "string", "const": "reward.delivered" }, { "type": "string", "const": "reward.delivery_failed" }, { "type": "string", "const": "reward.debt_recorded" }, { "type": "string", "const": "reward.debt_settled" }, { "type": "string", "const": "payout.created" }, { "type": "string", "const": "payout.paid" }, { "type": "string", "const": "payout.reversed" }, { "type": "string", "const": "payout.failed" }, { "type": "string", "const": "payout.needs_action" }, { "type": "string", "const": "payout.cancelled" }, { "type": "string", "const": "payout.account_required" }, { "type": "string", "const": "credit.redeemed" }, { "type": "string", "const": "credit.restored" }, { "type": "string", "const": "incentive.flagged" }, { "type": "string", "const": "self_referral.detected" }, { "type": "string", "const": "fraud.flagged" }, { "type": "string", "const": "referral.displaced" }, { "type": "string", "const": "milestone.reported" }, { "type": "string", "const": "milestone.revoked" }, { "type": "string", "const": "milestone.reinstated" }, { "type": "string", "const": "milestone.reversed" }, { "type": "string", "const": "partner.erased" }, { "type": "string", "const": "customer.erased" } ] } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "name", "url", "events", "active", "createdAt" ] } } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "order.refunded" }, { "type": "string", "const": "order.adjusted" }, { "type": "string", "const": "order.completed" }, { "type": "string", "const": "partner.created" }, { "type": "string", "const": "reward.created" }, { "type": "string", "const": "reward.approved" }, { "type": "string", "const": "reward.reversed" }, { "type": "string", "const": "reward.restored" }, { "type": "string", "const": "reward.adjusted" }, { "type": "string", "const": "reward.delivered" }, { "type": "string", "const": "reward.delivery_failed" }, { "type": "string", "const": "reward.debt_recorded" }, { "type": "string", "const": "reward.debt_settled" }, { "type": "string", "const": "payout.created" }, { "type": "string", "const": "payout.paid" }, { "type": "string", "const": "payout.reversed" }, { "type": "string", "const": "payout.failed" }, { "type": "string", "const": "payout.needs_action" }, { "type": "string", "const": "payout.cancelled" }, { "type": "string", "const": "payout.account_required" }, { "type": "string", "const": "credit.redeemed" }, { "type": "string", "const": "credit.restored" }, { "type": "string", "const": "incentive.flagged" }, { "type": "string", "const": "self_referral.detected" }, { "type": "string", "const": "fraud.flagged" }, { "type": "string", "const": "referral.displaced" }, { "type": "string", "const": "milestone.reported" }, { "type": "string", "const": "milestone.revoked" }, { "type": "string", "const": "milestone.reinstated" }, { "type": "string", "const": "milestone.reversed" }, { "type": "string", "const": "partner.erased" }, { "type": "string", "const": "customer.erased" } ] } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "name", "url", "events", "active", "createdAt" ] } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "post": { "operationId": "createWebhook", "summary": "createWebhook", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "settings:write" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "partner.created", "order.completed", "order.refunded", "order.adjusted", "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" ] }, "minItems": 1, "maxItems": 32 } }, "required": [ "name", "url", "events" ], "additionalProperties": false }, "example": { "name": "Example referral program", "url": "https://shop.example.com", "events": [ "partner.created" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "order.refunded" }, { "type": "string", "const": "order.adjusted" }, { "type": "string", "const": "order.completed" }, { "type": "string", "const": "partner.created" }, { "type": "string", "const": "reward.created" }, { "type": "string", "const": "reward.approved" }, { "type": "string", "const": "reward.reversed" }, { "type": "string", "const": "reward.restored" }, { "type": "string", "const": "reward.adjusted" }, { "type": "string", "const": "reward.delivered" }, { "type": "string", "const": "reward.delivery_failed" }, { "type": "string", "const": "reward.debt_recorded" }, { "type": "string", "const": "reward.debt_settled" }, { "type": "string", "const": "payout.created" }, { "type": "string", "const": "payout.paid" }, { "type": "string", "const": "payout.reversed" }, { "type": "string", "const": "payout.failed" }, { "type": "string", "const": "payout.needs_action" }, { "type": "string", "const": "payout.cancelled" }, { "type": "string", "const": "payout.account_required" }, { "type": "string", "const": "credit.redeemed" }, { "type": "string", "const": "credit.restored" }, { "type": "string", "const": "incentive.flagged" }, { "type": "string", "const": "self_referral.detected" }, { "type": "string", "const": "fraud.flagged" }, { "type": "string", "const": "referral.displaced" }, { "type": "string", "const": "milestone.reported" }, { "type": "string", "const": "milestone.revoked" }, { "type": "string", "const": "milestone.reinstated" }, { "type": "string", "const": "milestone.reversed" }, { "type": "string", "const": "partner.erased" }, { "type": "string", "const": "customer.erased" } ] } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "name", "url", "events", "active", "createdAt" ] }, "secret": { "type": "string" } }, "required": [ "endpoint", "secret" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "endpoint": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "order.refunded" }, { "type": "string", "const": "order.adjusted" }, { "type": "string", "const": "order.completed" }, { "type": "string", "const": "partner.created" }, { "type": "string", "const": "reward.created" }, { "type": "string", "const": "reward.approved" }, { "type": "string", "const": "reward.reversed" }, { "type": "string", "const": "reward.restored" }, { "type": "string", "const": "reward.adjusted" }, { "type": "string", "const": "reward.delivered" }, { "type": "string", "const": "reward.delivery_failed" }, { "type": "string", "const": "reward.debt_recorded" }, { "type": "string", "const": "reward.debt_settled" }, { "type": "string", "const": "payout.created" }, { "type": "string", "const": "payout.paid" }, { "type": "string", "const": "payout.reversed" }, { "type": "string", "const": "payout.failed" }, { "type": "string", "const": "payout.needs_action" }, { "type": "string", "const": "payout.cancelled" }, { "type": "string", "const": "payout.account_required" }, { "type": "string", "const": "credit.redeemed" }, { "type": "string", "const": "credit.restored" }, { "type": "string", "const": "incentive.flagged" }, { "type": "string", "const": "self_referral.detected" }, { "type": "string", "const": "fraud.flagged" }, { "type": "string", "const": "referral.displaced" }, { "type": "string", "const": "milestone.reported" }, { "type": "string", "const": "milestone.revoked" }, { "type": "string", "const": "milestone.reinstated" }, { "type": "string", "const": "milestone.reversed" }, { "type": "string", "const": "partner.erased" }, { "type": "string", "const": "customer.erased" } ] } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "name", "url", "events", "active", "createdAt" ] }, "secret": { "type": "string" } }, "required": [ "endpoint", "secret" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/v1/webhooks/{id}": { "put": { "operationId": "updateWebhook", "summary": "updateWebhook", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "settings:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 80 }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "partner.created", "order.completed", "order.refunded", "order.adjusted", "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" ] }, "minItems": 1, "maxItems": 32 }, "enabled": { "type": "boolean" } }, "additionalProperties": false }, "example": { "name": "Example referral program" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "order.refunded" }, { "type": "string", "const": "order.adjusted" }, { "type": "string", "const": "order.completed" }, { "type": "string", "const": "partner.created" }, { "type": "string", "const": "reward.created" }, { "type": "string", "const": "reward.approved" }, { "type": "string", "const": "reward.reversed" }, { "type": "string", "const": "reward.restored" }, { "type": "string", "const": "reward.adjusted" }, { "type": "string", "const": "reward.delivered" }, { "type": "string", "const": "reward.delivery_failed" }, { "type": "string", "const": "reward.debt_recorded" }, { "type": "string", "const": "reward.debt_settled" }, { "type": "string", "const": "payout.created" }, { "type": "string", "const": "payout.paid" }, { "type": "string", "const": "payout.reversed" }, { "type": "string", "const": "payout.failed" }, { "type": "string", "const": "payout.needs_action" }, { "type": "string", "const": "payout.cancelled" }, { "type": "string", "const": "payout.account_required" }, { "type": "string", "const": "credit.redeemed" }, { "type": "string", "const": "credit.restored" }, { "type": "string", "const": "incentive.flagged" }, { "type": "string", "const": "self_referral.detected" }, { "type": "string", "const": "fraud.flagged" }, { "type": "string", "const": "referral.displaced" }, { "type": "string", "const": "milestone.reported" }, { "type": "string", "const": "milestone.revoked" }, { "type": "string", "const": "milestone.reinstated" }, { "type": "string", "const": "milestone.reversed" }, { "type": "string", "const": "partner.erased" }, { "type": "string", "const": "customer.erased" } ] } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "name", "url", "events", "active", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "order.refunded" }, { "type": "string", "const": "order.adjusted" }, { "type": "string", "const": "order.completed" }, { "type": "string", "const": "partner.created" }, { "type": "string", "const": "reward.created" }, { "type": "string", "const": "reward.approved" }, { "type": "string", "const": "reward.reversed" }, { "type": "string", "const": "reward.restored" }, { "type": "string", "const": "reward.adjusted" }, { "type": "string", "const": "reward.delivered" }, { "type": "string", "const": "reward.delivery_failed" }, { "type": "string", "const": "reward.debt_recorded" }, { "type": "string", "const": "reward.debt_settled" }, { "type": "string", "const": "payout.created" }, { "type": "string", "const": "payout.paid" }, { "type": "string", "const": "payout.reversed" }, { "type": "string", "const": "payout.failed" }, { "type": "string", "const": "payout.needs_action" }, { "type": "string", "const": "payout.cancelled" }, { "type": "string", "const": "payout.account_required" }, { "type": "string", "const": "credit.redeemed" }, { "type": "string", "const": "credit.restored" }, { "type": "string", "const": "incentive.flagged" }, { "type": "string", "const": "self_referral.detected" }, { "type": "string", "const": "fraud.flagged" }, { "type": "string", "const": "referral.displaced" }, { "type": "string", "const": "milestone.reported" }, { "type": "string", "const": "milestone.revoked" }, { "type": "string", "const": "milestone.reinstated" }, { "type": "string", "const": "milestone.reversed" }, { "type": "string", "const": "partner.erased" }, { "type": "string", "const": "customer.erased" } ] } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "name", "url", "events", "active", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } }, "delete": { "operationId": "disableWebhook", "summary": "disableWebhook", "description": "", "security": [ { "serverKey": [] } ], "x-required-scopes": [ "settings:write" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "order.refunded" }, { "type": "string", "const": "order.adjusted" }, { "type": "string", "const": "order.completed" }, { "type": "string", "const": "partner.created" }, { "type": "string", "const": "reward.created" }, { "type": "string", "const": "reward.approved" }, { "type": "string", "const": "reward.reversed" }, { "type": "string", "const": "reward.restored" }, { "type": "string", "const": "reward.adjusted" }, { "type": "string", "const": "reward.delivered" }, { "type": "string", "const": "reward.delivery_failed" }, { "type": "string", "const": "reward.debt_recorded" }, { "type": "string", "const": "reward.debt_settled" }, { "type": "string", "const": "payout.created" }, { "type": "string", "const": "payout.paid" }, { "type": "string", "const": "payout.reversed" }, { "type": "string", "const": "payout.failed" }, { "type": "string", "const": "payout.needs_action" }, { "type": "string", "const": "payout.cancelled" }, { "type": "string", "const": "payout.account_required" }, { "type": "string", "const": "credit.redeemed" }, { "type": "string", "const": "credit.restored" }, { "type": "string", "const": "incentive.flagged" }, { "type": "string", "const": "self_referral.detected" }, { "type": "string", "const": "fraud.flagged" }, { "type": "string", "const": "referral.displaced" }, { "type": "string", "const": "milestone.reported" }, { "type": "string", "const": "milestone.revoked" }, { "type": "string", "const": "milestone.reinstated" }, { "type": "string", "const": "milestone.reversed" }, { "type": "string", "const": "partner.erased" }, { "type": "string", "const": "customer.erased" } ] } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "name", "url", "events", "active", "createdAt" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyId": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string" }, "events": { "type": "array", "items": { "anyOf": [ { "type": "string", "const": "order.refunded" }, { "type": "string", "const": "order.adjusted" }, { "type": "string", "const": "order.completed" }, { "type": "string", "const": "partner.created" }, { "type": "string", "const": "reward.created" }, { "type": "string", "const": "reward.approved" }, { "type": "string", "const": "reward.reversed" }, { "type": "string", "const": "reward.restored" }, { "type": "string", "const": "reward.adjusted" }, { "type": "string", "const": "reward.delivered" }, { "type": "string", "const": "reward.delivery_failed" }, { "type": "string", "const": "reward.debt_recorded" }, { "type": "string", "const": "reward.debt_settled" }, { "type": "string", "const": "payout.created" }, { "type": "string", "const": "payout.paid" }, { "type": "string", "const": "payout.reversed" }, { "type": "string", "const": "payout.failed" }, { "type": "string", "const": "payout.needs_action" }, { "type": "string", "const": "payout.cancelled" }, { "type": "string", "const": "payout.account_required" }, { "type": "string", "const": "credit.redeemed" }, { "type": "string", "const": "credit.restored" }, { "type": "string", "const": "incentive.flagged" }, { "type": "string", "const": "self_referral.detected" }, { "type": "string", "const": "fraud.flagged" }, { "type": "string", "const": "referral.displaced" }, { "type": "string", "const": "milestone.reported" }, { "type": "string", "const": "milestone.revoked" }, { "type": "string", "const": "milestone.reinstated" }, { "type": "string", "const": "milestone.reversed" }, { "type": "string", "const": "partner.erased" }, { "type": "string", "const": "customer.erased" } ] } }, "active": { "type": "boolean" }, "createdAt": { "type": "string" } }, "required": [ "id", "companyId", "name", "url", "events", "active", "createdAt" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/tracking/{publishableKey}/capture": { "post": { "operationId": "captureReferral", "summary": "captureReferral", "description": "", "security": [], "x-required-scopes": [], "parameters": [ { "name": "publishableKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "programId": { "type": "string", "minLength": 1, "maxLength": 120 }, "referralCode": { "type": "string", "minLength": 1, "maxLength": 120 }, "destination": { "type": "string", "maxLength": 2048 }, "channel": { "type": "string", "enum": [ "link", "qr", "coupon", "in_app" ], "default": "link" }, "installClaim": { "type": "boolean" }, "deviceId": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "referralCode" ], "additionalProperties": false }, "example": { "referralCode": "EXAMPLE" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "receipt": { "type": "string" }, "checkoutReference": { "type": "string", "description": "A short signed reference to the same capture, 112 characters, that expires with the receipt. Put it in a Stripe\nCheckout Session's client_reference_id, or in grizzlee_receipt metadata, and a Stripe\nconnection that records invoices claims the referral for the paying customer." }, "programId": { "type": "string" }, "placements": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string" }, "duration": { "anyOf": [ { "type": "string", "const": "only_order" }, { "type": "string", "const": "first_order" }, { "type": "string", "const": "first_n_orders" }, { "type": "string", "const": "days" }, { "type": "string", "const": "months" }, { "type": "string", "const": "lifetime" } ] }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The program's current friend incentive, or null when it has none. Says nothing about eligibility." }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "The program's public name, headline and milestone label." }, "installClaim": { "type": "object", "properties": { "code": { "type": "string", "description": "Twelve characters in groups of four, such as K7Q2-M9XD-4HPA. Hyphens, spaces and case are ignored." }, "expiresAt": { "type": "string", "description": "The claim stops working at this time, at most 7 days after the capture." } }, "required": [ "code", "expiresAt" ], "description": "Present when the capture asked for an install claim." } }, "required": [ "receipt", "checkoutReference", "programId", "placements", "expiresAt", "duration", "incentive", "display" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "receipt": { "type": "string" }, "checkoutReference": { "type": "string", "description": "A short signed reference to the same capture, 112 characters, that expires with the receipt. Put it in a Stripe\nCheckout Session's client_reference_id, or in grizzlee_receipt metadata, and a Stripe\nconnection that records invoices claims the referral for the paying customer." }, "programId": { "type": "string" }, "placements": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string" }, "duration": { "anyOf": [ { "type": "string", "const": "only_order" }, { "type": "string", "const": "first_order" }, { "type": "string", "const": "first_n_orders" }, { "type": "string", "const": "days" }, { "type": "string", "const": "months" }, { "type": "string", "const": "lifetime" } ] }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The program's current friend incentive, or null when it has none. Says nothing about eligibility." }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "The program's public name, headline and milestone label." }, "installClaim": { "type": "object", "properties": { "code": { "type": "string", "description": "Twelve characters in groups of four, such as K7Q2-M9XD-4HPA. Hyphens, spaces and case are ignored." }, "expiresAt": { "type": "string", "description": "The claim stops working at this time, at most 7 days after the capture." } }, "required": [ "code", "expiresAt" ], "description": "Present when the capture asked for an install claim." } }, "required": [ "receipt", "checkoutReference", "programId", "placements", "expiresAt", "duration", "incentive", "display" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } }, "/api/tracking/{publishableKey}/install-claims/redeem": { "post": { "operationId": "redeemInstallClaim", "summary": "redeemInstallClaim", "description": "", "security": [], "x-required-scopes": [], "parameters": [ { "name": "publishableKey", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "code" ], "additionalProperties": false }, "example": { "code": "code-example" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "receipt": { "type": "string" }, "checkoutReference": { "type": "string", "description": "A short signed reference to the same capture, 112 characters, that expires with the receipt. Put it in a Stripe\nCheckout Session's client_reference_id, or in grizzlee_receipt metadata, and a Stripe\nconnection that records invoices claims the referral for the paying customer." }, "programId": { "type": "string" }, "placements": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string" }, "duration": { "anyOf": [ { "type": "string", "const": "only_order" }, { "type": "string", "const": "first_order" }, { "type": "string", "const": "first_n_orders" }, { "type": "string", "const": "days" }, { "type": "string", "const": "months" }, { "type": "string", "const": "lifetime" } ] }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The program's current friend incentive, or null when it has none. Says nothing about eligibility." }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "The program's public name, headline and milestone label." }, "installClaim": { "type": "object", "properties": { "code": { "type": "string", "description": "Twelve characters in groups of four, such as K7Q2-M9XD-4HPA. Hyphens, spaces and case are ignored." }, "expiresAt": { "type": "string", "description": "The claim stops working at this time, at most 7 days after the capture." } }, "required": [ "code", "expiresAt" ], "description": "Present when the capture asked for an install claim." } }, "required": [ "receipt", "checkoutReference", "programId", "placements", "expiresAt", "duration", "incentive", "display" ] } } } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "receipt": { "type": "string" }, "checkoutReference": { "type": "string", "description": "A short signed reference to the same capture, 112 characters, that expires with the receipt. Put it in a Stripe\nCheckout Session's client_reference_id, or in grizzlee_receipt metadata, and a Stripe\nconnection that records invoices claims the referral for the paying customer." }, "programId": { "type": "string" }, "placements": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string" }, "duration": { "anyOf": [ { "type": "string", "const": "only_order" }, { "type": "string", "const": "first_order" }, { "type": "string", "const": "first_n_orders" }, { "type": "string", "const": "days" }, { "type": "string", "const": "months" }, { "type": "string", "const": "lifetime" } ] }, "incentive": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "type": { "type": "string", "const": "percent" }, "rateBps": { "type": "number" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "maxDiscountCents": { "type": "number", "description": "Largest discount for one order." }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "rateBps", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "currency" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "fixed" }, "orders": { "type": "number", "description": "How many of the friend's orders get the incentive." }, "newCustomersOnly": { "type": "boolean", "description": "true: use the merchant's newCustomer answer, or recorded purchases when omitted. false:\nreturning customers qualify too. A supplied answer uses the order limit after the referral." }, "expiresAfterDays": { "anyOf": [ { "type": "null" }, { "type": "number" } ], "description": "Days after the referral was captured, claimed or entered. null means it never expires." }, "returnOnFullRefund": { "type": "boolean", "description": "true: a full refund gives the use back, so the customer can get the offer again." }, "amountCents": { "type": "number" }, "minOrderCents": { "type": "number", "description": "The friend's order total before the discount must reach this amount. Checked by the merchant's checkout." }, "orderCategories": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "string" } }, "exclude": { "type": "array", "items": { "type": "string" } } }, "description": "Order categories that get the discount. Checked apart from the program's own orderCategories,\nwhich decide rewards. Absent means every order qualifies." }, "currency": { "anyOf": [ { "type": "string", "const": "CAD" }, { "type": "string", "const": "USD" }, { "type": "string", "const": "EUR" }, { "type": "string", "const": "GBP" } ] } }, "required": [ "type", "orders", "newCustomersOnly", "expiresAfterDays", "returnOnFullRefund", "amountCents", "currency" ] } ], "description": "The program's current friend incentive, or null when it has none. Says nothing about eligibility." }, "display": { "type": "object", "properties": { "publicName": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "headline": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "milestoneLabel": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "one": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "few": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "many": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] }, "other": { "type": "object", "properties": { "en": { "type": "string" }, "fr-CA": { "type": "string" }, "hy": { "type": "string" }, "ru": { "type": "string" } }, "required": [ "en", "fr-CA", "hy", "ru" ] } }, "required": [ "one", "few", "many", "other" ] } ], "description": "Null for order programs. Forms by plural category, picked with Intl.PluralRules. few and\nmany matter in Russian. A merchant's label sets one and other, and few and many reuse other." } }, "required": [ "publicName", "headline", "milestoneLabel" ], "description": "The program's public name, headline and milestone label." }, "installClaim": { "type": "object", "properties": { "code": { "type": "string", "description": "Twelve characters in groups of four, such as K7Q2-M9XD-4HPA. Hyphens, spaces and case are ignored." }, "expiresAt": { "type": "string", "description": "The claim stops working at this time, at most 7 days after the capture." } }, "required": [ "code", "expiresAt" ], "description": "Present when the capture asked for an install claim." } }, "required": [ "receipt", "checkoutReference", "programId", "placements", "expiresAt", "duration", "incentive", "display" ] } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} } } } } } } } } } } } }