{ "openapi": "3.1.0", "info": { "title": "Lantern Promotions API", "description": "Published patterns use ECMAScript regular-expression syntax and compile unchanged in Python re and RE2. Each one accepts at least what the server accepts; the server is the authority. In Python, $ also matches before a final newline, which the server refuses in single-line fields.", "version": "1", "x-contract-status": "provisional", "x-contract-source": "lantern-website" }, "servers": [ { "url": "/api/promotions/v1" } ], "paths": { "/offers": { "get": { "operationId": "listOffers", "parameters": [ { "$ref": "#/components/parameters/OffersQuery_q" }, { "$ref": "#/components/parameters/OffersQuery_merchantDomain" }, { "$ref": "#/components/parameters/OffersQuery_productId" }, { "$ref": "#/components/parameters/OffersQuery_variantId" }, { "$ref": "#/components/parameters/OffersQuery_collection" }, { "$ref": "#/components/parameters/OffersQuery_promotionType" }, { "$ref": "#/components/parameters/OffersQuery_checkoutMode" }, { "$ref": "#/components/parameters/OffersQuery_cursor" }, { "$ref": "#/components/parameters/OffersQuery_limit" }, { "$ref": "#/components/parameters/OffersQuery_availability" }, { "$ref": "#/components/parameters/OffersQuery_via" }, { "$ref": "#/components/parameters/ConditionalRead" } ], "responses": { "200": { "description": "A page of public offers, those that can be claimed now first.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" }, "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OffersListResponseV1" } } } }, "304": { "description": "The cached representation is unchanged. No response body.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" } } }, "400": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "429": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "503": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } } } } }, "/offers.md": { "get": { "operationId": "listOffersMarkdown", "parameters": [ { "$ref": "#/components/parameters/OffersQuery_q" }, { "$ref": "#/components/parameters/OffersQuery_merchantDomain" }, { "$ref": "#/components/parameters/OffersQuery_productId" }, { "$ref": "#/components/parameters/OffersQuery_variantId" }, { "$ref": "#/components/parameters/OffersQuery_collection" }, { "$ref": "#/components/parameters/OffersQuery_promotionType" }, { "$ref": "#/components/parameters/OffersQuery_checkoutMode" }, { "$ref": "#/components/parameters/OffersQuery_cursor" }, { "$ref": "#/components/parameters/OffersQuery_limit" }, { "$ref": "#/components/parameters/OffersQuery_availability" }, { "$ref": "#/components/parameters/OffersQuery_via" }, { "$ref": "#/components/parameters/ConditionalRead" } ], "responses": { "200": { "description": "A page of public offers as Markdown, those that can be claimed now first.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" }, "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "text/markdown": { "schema": { "type": "string" } } } }, "304": { "description": "The cached representation is unchanged. No response body.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" } } }, "400": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "429": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "503": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } } } } }, "/offers.json": { "get": { "operationId": "listOffersJson", "parameters": [ { "$ref": "#/components/parameters/OffersQuery_q" }, { "$ref": "#/components/parameters/OffersQuery_merchantDomain" }, { "$ref": "#/components/parameters/OffersQuery_productId" }, { "$ref": "#/components/parameters/OffersQuery_variantId" }, { "$ref": "#/components/parameters/OffersQuery_collection" }, { "$ref": "#/components/parameters/OffersQuery_promotionType" }, { "$ref": "#/components/parameters/OffersQuery_checkoutMode" }, { "$ref": "#/components/parameters/OffersQuery_cursor" }, { "$ref": "#/components/parameters/OffersQuery_limit" }, { "$ref": "#/components/parameters/OffersQuery_availability" }, { "$ref": "#/components/parameters/OffersQuery_via" }, { "$ref": "#/components/parameters/ConditionalRead" } ], "responses": { "200": { "description": "A page of public offers, those that can be claimed now first.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" }, "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OffersListResponseV1" } } } }, "304": { "description": "The cached representation is unchanged. No response body.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" } } }, "400": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "429": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "503": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } } } } }, "/offers/{offerId}": { "get": { "operationId": "getOffer", "parameters": [ { "$ref": "#/components/parameters/OfferId" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "md", "json" ] } }, { "$ref": "#/components/parameters/ConditionalRead" } ], "responses": { "200": { "description": "Public offer terms and observed availability.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" }, "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferDetailResponseV1" } }, "text/markdown": { "schema": { "type": "string" } } } }, "304": { "description": "The cached representation is unchanged. No response body.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" } } }, "400": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "404": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "410": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "429": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "503": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } } } } }, "/offers/{offerId}/availability": { "get": { "operationId": "getOfferAvailability", "parameters": [ { "$ref": "#/components/parameters/OfferId" } ], "responses": { "200": { "description": "Live availability and current terms when the publication changed.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfferAvailabilityResponseV1" } } } }, "400": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "404": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "410": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "429": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "503": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } } } } }, "/offers/{offerId}/claim-links": { "post": { "operationId": "mintClaimLinks", "summary": "Create claim links", "description": "Creates a fresh claim link for this offer. The link works for 60 minutes from creation and holds no code: the shopper's code is issued when they submit the claim form. Send the terms revision the offer currently shows.", "parameters": [ { "$ref": "#/components/parameters/OfferId" } ], "requestBody": { "required": true, "x-max-body-bytes": 8192, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimLinkMintRequestV1" } } } }, "responses": { "201": { "description": "Claim link created.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "CDN-Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimLinkMintResponseV1" } } } }, "400": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "CDN-Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "404": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "CDN-Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "409": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "CDN-Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" }, "examples": { "CLAIM_LINK_UNAVAILABLE": { "value": { "error": "This offer is not taking claims now, so no claim link was created.", "code": "CLAIM_LINK_UNAVAILABLE", "requestId": "request-1" } } } } } }, "410": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "CDN-Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "413": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "CDN-Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "429": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "CDN-Cache-Control": { "$ref": "#/components/headers/NoStore" }, "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "503": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Cache-Control": { "$ref": "#/components/headers/NoStore" }, "CDN-Cache-Control": { "$ref": "#/components/headers/NoStore" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } } } } }, "/claims": { "post": { "operationId": "claimOffer", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" } }, { "$ref": "#/components/parameters/RecoveryCapability" } ], "requestBody": { "required": true, "x-max-body-bytes": 8192, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimRequestV1" } } } }, "responses": { "200": { "description": "The claim was not issued, or a replayed claim's code has expired, been used, or been withdrawn by the store. No code is returned.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponseV1" } } } }, "201": { "description": "A verified issued claim.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponseV1" } } } }, "202": { "description": "A durably accepted pending claim.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" }, "Retry-After": { "description": "Seconds to wait before polling POST /claims/status.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimResponseV1" } } } }, "400": { "description": "Typed error, request ID and recovery instructions.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "404": { "description": "Typed error, request ID and recovery instructions.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "409": { "description": "Typed error, request ID and recovery instructions.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "410": { "description": "Typed error, request ID and recovery instructions.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "413": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "422": { "description": "Typed error, request ID and recovery instructions.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "429": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" }, "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "503": { "description": "Typed error, request ID and recovery instructions.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } } } } }, "/claims/status": { "post": { "operationId": "getClaimStatus", "parameters": [ { "name": "X-Lantern-Recovery", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" }, "description": "Required unless the body contains offerId and the shopper email." } ], "requestBody": { "required": true, "x-max-body-bytes": 8192, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimStatusRequestV1" } } } }, "responses": { "200": { "description": "The authorized claim or operation state.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" }, "Retry-After": { "description": "Present only when state is pending: seconds to wait before polling POST /claims/status again.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimStatusResponseV1" } } } }, "400": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "404": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" }, "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "413": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "429": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" }, "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "503": { "description": "Typed error, request ID and recovery instructions.", "headers": { "X-Lantern-Mock": { "$ref": "#/components/headers/LanternMock" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } } } } }, "/openapi.json": { "get": { "operationId": "getPromotionsOpenApi", "parameters": [ { "$ref": "#/components/parameters/ConditionalRead" } ], "responses": { "200": { "description": "This OpenAPI 3.1 contract.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "304": { "description": "The cached representation is unchanged. No response body.", "headers": { "ETag": { "$ref": "#/components/headers/RepresentationETag" } } }, "400": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "429": { "description": "Typed error, request ID and recovery instructions.", "headers": { "Retry-After": { "$ref": "#/components/headers/RateLimitRetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } }, "503": { "description": "Typed error, request ID and recovery instructions.", "headers": {}, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PromotionErrorBodyV1" } } } } } } } }, "components": { "schemas": { "Benefit": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "GIVEAWAY" }, "unitsFree": { "type": "number", "const": 1 } }, "required": [ "kind", "unitsFree" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "PERCENTAGE" }, "basisPoints": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "kind", "basisPoints" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "FREE_SHIPPING" }, "destinationCountry": { "type": "string", "const": "US" }, "ceilingMinor": { "$ref": "#/components/schemas/NullablePositiveInteger" } }, "required": [ "kind", "destinationCountry", "ceilingMinor" ], "additionalProperties": false } ] }, "ShippingTerms": { "type": "object", "properties": { "paidBy": { "type": "string", "enum": [ "MERCHANT", "SHOPPER" ] }, "ceilingMinor": { "$ref": "#/components/schemas/NullablePositiveInteger" } }, "required": [ "paidBy", "ceilingMinor" ], "additionalProperties": false, "if": { "properties": { "paidBy": { "const": "SHOPPER" } }, "required": [ "paidBy" ] }, "then": { "properties": { "ceilingMinor": { "type": "null" } }, "required": [ "ceilingMinor" ] } }, "PublicVariant": { "type": "object", "properties": { "variantId": { "type": "string", "pattern": "^gid:\\/\\/shopify\\/ProductVariant\\/\\d{1,20}$" }, "title": { "$ref": "#/components/schemas/ShortText" } }, "required": [ "variantId", "title" ], "additionalProperties": false }, "PublicProduct": { "type": "object", "properties": { "productId": { "type": "string", "pattern": "^gid:\\/\\/shopify\\/Product\\/\\d{1,20}$" }, "title": { "$ref": "#/components/schemas/PromotionTitle" }, "url": { "$ref": "#/components/schemas/HttpsUrl" }, "variants": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/PublicVariant" }, "uniqueItems": true, "description": "Each variant appears once, by variantId." } }, "required": [ "productId", "title", "url", "variants" ], "additionalProperties": false }, "PublicOfferContentV1": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "publicationRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "termsRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "termsUpdatedAt": { "$ref": "#/components/schemas/Instant" }, "publishedAt": { "$ref": "#/components/schemas/Instant" }, "merchant": { "$ref": "#/components/schemas/PromotionMerchant" }, "title": { "$ref": "#/components/schemas/PromotionTitle" }, "description": { "$ref": "#/components/schemas/PromotionDescription" }, "benefit": { "$ref": "#/components/schemas/Benefit" }, "shipping": { "$ref": "#/components/schemas/PromotionShipping" }, "products": { "$ref": "#/components/schemas/PromotionProducts" }, "collections": { "description": "Handles, in Unicode NFC, of the collections published to the Online Store sales channel that contain any listed product, at most 250. When the union is larger the engine publishes 250 and renders collection signposts only for the handles it published. Optional until the engine publishes it; an offer without it matches no collection filter. Never echoed in public offer bodies.", "maxItems": 250, "type": "array", "items": { "type": "string", "pattern": "^(?:[a-z0-9_-]|[^\\x00-\\x7F])+$", "minLength": 1, "maxLength": 255, "description": "Non-ASCII handles must use lowercase letters, marks or digits in Unicode NFC; the server is the authority. Length is 1 to 255 Unicode code points." }, "uniqueItems": true }, "eligibility": { "$ref": "#/components/schemas/PromotionEligibility" }, "minimumSpendMinor": { "$ref": "#/components/schemas/NullablePositiveInteger" }, "combinesWithOtherDiscounts": { "type": "boolean" }, "startsAt": { "$ref": "#/components/schemas/Instant" }, "issuanceEndsAt": { "$ref": "#/components/schemas/Instant" }, "redemptionEndsAt": { "$ref": "#/components/schemas/Instant" }, "merchantTimezone": { "type": "string", "maxLength": 64, "pattern": "^(UTC|[A-Z][A-Za-z_]+(\\/[A-Z][A-Za-z0-9_+-]*)+)$" }, "claimTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "multipleOf": 60 }, "checkoutModes": { "$ref": "#/components/schemas/PromotionCheckoutModes" }, "claimPageUrl": { "$ref": "#/components/schemas/NullableUrl" } }, "required": [ "schemaVersion", "offerId", "publicationRevision", "termsRevision", "termsUpdatedAt", "publishedAt", "merchant", "title", "description", "benefit", "shipping", "products", "eligibility", "minimumSpendMinor", "combinesWithOtherDiscounts", "startsAt", "issuanceEndsAt", "redemptionEndsAt", "merchantTimezone", "claimTtlSeconds", "checkoutModes", "claimPageUrl" ], "additionalProperties": false, "description": "startsAt is before issuanceEndsAt, and issuanceEndsAt is no later than redemptionEndsAt. Every product URL is on the merchant domain. The offer lists at most 50 variants, each once. Free-shipping offers carry no separate shipping terms, so shipping is null for them." }, "OfferAvailabilityView": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "available", "paused", "exhausted", "ended", "unavailable", "unknown" ] }, "observedAt": { "$ref": "#/components/schemas/NullableInstant" }, "freshUntil": { "$ref": "#/components/schemas/NullableInstant" }, "availabilityVersion": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "snapshot", "live" ] } }, "required": [ "state", "observedAt", "freshUntil", "availabilityVersion", "source" ], "additionalProperties": false }, "PublicOfferV1": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "publicationRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "termsRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "termsUpdatedAt": { "$ref": "#/components/schemas/Instant" }, "publishedAt": { "$ref": "#/components/schemas/Instant" }, "merchant": { "$ref": "#/components/schemas/PromotionMerchant" }, "title": { "$ref": "#/components/schemas/PromotionTitle" }, "description": { "$ref": "#/components/schemas/PromotionDescription" }, "benefit": { "$ref": "#/components/schemas/Benefit" }, "shipping": { "$ref": "#/components/schemas/PromotionShipping" }, "products": { "$ref": "#/components/schemas/PromotionProducts" }, "eligibility": { "$ref": "#/components/schemas/PromotionEligibility" }, "minimumSpendMinor": { "$ref": "#/components/schemas/NullablePositiveInteger" }, "combinesWithOtherDiscounts": { "type": "boolean" }, "startsAt": { "$ref": "#/components/schemas/Instant" }, "issuanceEndsAt": { "$ref": "#/components/schemas/Instant" }, "redemptionEndsAt": { "$ref": "#/components/schemas/Instant" }, "merchantTimezone": { "type": "string", "maxLength": 64, "pattern": "^(UTC|[A-Z][A-Za-z_]+(\\/[A-Z][A-Za-z0-9_+-]*)+)$" }, "claimTtlSeconds": { "type": "integer", "minimum": 60, "maximum": 86400, "multipleOf": 60 }, "checkoutModes": { "$ref": "#/components/schemas/PromotionCheckoutModes" }, "claimPageUrl": { "anyOf": [ { "$ref": "#/components/schemas/HttpsUrl" }, { "type": "null" } ], "description": "Each claimPageUrl is a claim link that works for 60 minutes from when you fetched this document. Give the shopper a link from a recent fetch, not one you saved earlier. For a new link, fetch this document again, or POST /api/promotions/v1/offers/{offerId}/claim-links. Claiming through the API (POST /api/promotions/v1/claims) needs no claim link." }, "claimApiUrl": { "$ref": "#/components/schemas/HttpsUrl" }, "availability": { "$ref": "#/components/schemas/OfferAvailabilityView" } }, "required": [ "schemaVersion", "offerId", "publicationRevision", "termsRevision", "termsUpdatedAt", "publishedAt", "merchant", "title", "description", "benefit", "shipping", "products", "eligibility", "minimumSpendMinor", "combinesWithOtherDiscounts", "startsAt", "issuanceEndsAt", "redemptionEndsAt", "merchantTimezone", "claimTtlSeconds", "checkoutModes", "claimPageUrl", "claimApiUrl", "availability" ], "additionalProperties": false, "description": "startsAt is before issuanceEndsAt, and issuanceEndsAt is no later than redemptionEndsAt. Every product URL is on the merchant domain. The offer lists at most 50 variants, each once. Free-shipping offers carry no separate shipping terms, so shipping is null for them." }, "OffersListResponseV1": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "generatedAt": { "$ref": "#/components/schemas/Instant" }, "mock": { "type": "boolean", "const": true }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOfferV1" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "schemaVersion", "generatedAt", "items", "nextCursor" ], "additionalProperties": false }, "OfferDetailResponseV1": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "generatedAt": { "$ref": "#/components/schemas/Instant" }, "mock": { "type": "boolean", "const": true }, "offer": { "$ref": "#/components/schemas/PublicOfferV1" } }, "required": [ "schemaVersion", "generatedAt", "offer" ], "additionalProperties": false }, "OfferAvailabilityResponseV1": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "generatedAt": { "$ref": "#/components/schemas/Instant" }, "mock": { "type": "boolean", "const": true }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "publicationRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "termsRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "availability": { "$ref": "#/components/schemas/OfferAvailabilityView" }, "currentOffer": { "$ref": "#/components/schemas/PublicOfferV1" } }, "required": [ "schemaVersion", "generatedAt", "offerId", "publicationRevision", "termsRevision", "availability" ], "additionalProperties": false }, "OffersQueryV1": { "type": "object", "properties": { "q": { "$ref": "#/components/schemas/OffersQuery_q" }, "merchantDomain": { "$ref": "#/components/schemas/OffersQuery_merchantDomain" }, "productId": { "$ref": "#/components/schemas/OffersQuery_productId" }, "variantId": { "$ref": "#/components/schemas/OffersQuery_variantId" }, "collection": { "$ref": "#/components/schemas/OffersQuery_collection" }, "promotionType": { "type": "string", "enum": [ "GIVEAWAY", "PERCENTAGE", "FREE_SHIPPING" ] }, "checkoutMode": { "$ref": "#/components/schemas/CheckoutMode" }, "cursor": { "$ref": "#/components/schemas/OffersQuery_cursor" }, "limit": { "default": 20, "type": "string", "pattern": "^(?:[1-9]|[1-4]\\d|50)$" }, "availability": { "default": "snapshot", "type": "string", "enum": [ "snapshot", "live" ] }, "via": { "$ref": "#/components/schemas/OffersQuery_via" } }, "additionalProperties": false }, "OfferDetailQueryV1": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "md", "json" ] } }, "additionalProperties": false }, "AvailabilityObservationV1": { "type": "object", "properties": { "offerId": { "$ref": "#/components/schemas/OfferId" }, "publicationRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "termsRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "availabilityVersion": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "availability": { "type": "string", "enum": [ "available", "paused", "exhausted", "ended", "unavailable" ] }, "observedAt": { "$ref": "#/components/schemas/Instant" }, "freshUntil": { "$ref": "#/components/schemas/Instant" } }, "required": [ "offerId", "publicationRevision", "termsRevision", "availabilityVersion", "availability", "observedAt", "freshUntil" ], "additionalProperties": false, "description": "freshUntil is after observedAt and at most 60 seconds later." }, "AvailabilityRequestV1": { "type": "object", "properties": { "offers": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "offerId": { "$ref": "#/components/schemas/OfferId" }, "publicationRevision": { "$ref": "#/components/schemas/PositiveInteger" } }, "required": [ "offerId", "publicationRevision" ], "additionalProperties": false }, "uniqueItems": true, "description": "Each offer appears once, by offerId." } }, "required": [ "offers" ], "additionalProperties": false }, "AvailabilitySnapshotV1": { "type": "object", "properties": { "observations": { "type": "array", "items": { "$ref": "#/components/schemas/AvailabilityObservationV1" } }, "currentOffers": { "type": "array", "items": { "$ref": "#/components/schemas/PublicOfferContentV1" } }, "missing": { "type": "array", "items": { "$ref": "#/components/schemas/OfferId" } } }, "required": [ "observations", "currentOffers", "missing" ], "additionalProperties": false }, "ProjectionTombstone": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "ENDED", "REVOKED", "UNINSTALLED", "WITHDRAWN" ] }, "at": { "$ref": "#/components/schemas/Instant" } }, "required": [ "reason", "at" ], "additionalProperties": false }, "ProjectionEnvelopeV1": { "anyOf": [ { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "eventId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "publicationRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "contentDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "type": { "type": "string", "const": "offer.published" }, "content": { "$ref": "#/components/schemas/PublicOfferContentV1" } }, "required": [ "schemaVersion", "eventId", "offerId", "publicationRevision", "contentDigest", "type", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "eventId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{8,128}$" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "publicationRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "contentDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "type": { "type": "string", "const": "offer.tombstoned" }, "tombstone": { "$ref": "#/components/schemas/ProjectionTombstone" } }, "required": [ "schemaVersion", "eventId", "offerId", "publicationRevision", "contentDigest", "type", "tombstone" ], "additionalProperties": false } ] }, "ProjectionApplyResultV1": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "applied", "duplicate", "stale" ] }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "storedRevision": { "$ref": "#/components/schemas/PositiveInteger" } }, "required": [ "outcome", "offerId", "storedRevision" ], "additionalProperties": false }, "ExportPublicationsRequestV1": { "type": "object", "properties": { "cursor": { "$ref": "#/components/schemas/NullableExportCursor" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "cursor", "limit" ], "additionalProperties": false }, "ExportPublicationsPageV1": { "type": "object", "properties": { "watermark": { "$ref": "#/components/schemas/ExportCursorText" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectionEnvelopeV1" } }, "nextCursor": { "$ref": "#/components/schemas/NullableExportCursor" } }, "required": [ "watermark", "items", "nextCursor" ], "additionalProperties": false }, "ClaimRequestV1": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "termsRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "variantId": { "type": "string", "pattern": "^gid:\\/\\/shopify\\/ProductVariant\\/\\d{1,20}$" }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+-]+\\.)*[A-Za-z0-9_'+-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "schemaVersion", "offerId", "termsRevision", "variantId", "email" ], "additionalProperties": false }, "ClaimStatusRequestV1": { "anyOf": [ { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "claimId": { "$ref": "#/components/schemas/ClaimId" } }, "required": [ "schemaVersion", "claimId" ], "additionalProperties": false }, { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{8,40}$" } }, "required": [ "schemaVersion", "operationId" ], "additionalProperties": false }, { "$ref": "#/components/schemas/EmailClaimStatusRequestV1" } ], "description": "Send claimId or operationId with the recovery header, or offerId and email with an optional claimId or operationId." }, "EmailClaimStatusRequestV1": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "email": { "type": "string", "maxLength": 254, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+-]+\\.)*[A-Za-z0-9_'+-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9-]*\\.)+[A-Za-z]{2,}$" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{8,40}$" } }, "required": [ "schemaVersion", "offerId", "email" ], "additionalProperties": false, "not": { "required": [ "claimId", "operationId" ] } }, "GatewayClaimInputV1": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/ClaimRequestV1" }, "idempotencyKey": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" }, "recoveryCapability": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" } }, "required": [ "request", "idempotencyKey", "recoveryCapability" ], "additionalProperties": false, "description": "Private input to the website-owned claim gateway. The gateway returns ClaimResultV1." }, "GatewayClaimStatusInputV1": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/ClaimStatusRequestV1" }, "recoveryCapability": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" } }, "required": [ "request", "recoveryCapability" ], "additionalProperties": false, "description": "Private input to the website-owned claim status gateway. The gateway returns ClaimStatusResultV1." }, "ClaimResultV1": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "issued" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "termsRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "expiresAt": { "$ref": "#/components/schemas/Instant" }, "code": { "$ref": "#/components/schemas/ClaimCode" }, "discountUrl": { "$ref": "#/components/schemas/NullableUrl" }, "checkoutModes": { "$ref": "#/components/schemas/ClaimCheckoutModes" } }, "required": [ "state", "claimId", "offerId", "termsRevision", "expiresAt", "code", "discountUrl", "checkoutModes" ], "additionalProperties": false }, { "$ref": "#/components/schemas/PendingClaim" }, { "type": "object", "properties": { "state": { "type": "string", "const": "not_issued" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "availability": { "$ref": "#/components/schemas/DeclinedAvailability" } }, "required": [ "state", "offerId", "availability" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "expired" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "expiresAt": { "$ref": "#/components/schemas/Instant" } }, "required": [ "state", "claimId", "offerId", "expiresAt" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "consumed" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" } }, "required": [ "state", "claimId", "offerId" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "revoked" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" } }, "required": [ "state", "claimId", "offerId" ], "additionalProperties": false } ] }, "ClaimStatusResultV1": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "issued" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "termsRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "expiresAt": { "$ref": "#/components/schemas/Instant" }, "code": { "$ref": "#/components/schemas/ClaimCode" }, "discountUrl": { "$ref": "#/components/schemas/NullableUrl" }, "checkoutModes": { "$ref": "#/components/schemas/ClaimCheckoutModes" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" } }, "required": [ "state", "claimId", "offerId", "termsRevision", "expiresAt", "code", "discountUrl", "checkoutModes" ], "additionalProperties": false }, { "$ref": "#/components/schemas/PendingClaim" }, { "type": "object", "properties": { "state": { "type": "string", "const": "not_issued" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "availability": { "$ref": "#/components/schemas/DeclinedAvailability" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" } }, "required": [ "state", "offerId", "availability" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "expired" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "expiresAt": { "$ref": "#/components/schemas/Instant" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" } }, "required": [ "state", "claimId", "offerId", "expiresAt" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "consumed" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" } }, "required": [ "state", "claimId", "offerId" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "revoked" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" } }, "required": [ "state", "claimId", "offerId" ], "additionalProperties": false } ] }, "ClaimResponseV1": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "issued" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "termsRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "expiresAt": { "$ref": "#/components/schemas/Instant" }, "code": { "$ref": "#/components/schemas/ClaimCode" }, "discountUrl": { "$ref": "#/components/schemas/NullableUrl" }, "checkoutModes": { "$ref": "#/components/schemas/ClaimCheckoutModes" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "claimId", "offerId", "termsRevision", "expiresAt", "code", "discountUrl", "checkoutModes", "next" ], "additionalProperties": false }, { "$ref": "#/components/schemas/PendingClaimResponse" }, { "type": "object", "properties": { "state": { "type": "string", "const": "not_issued" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "availability": { "$ref": "#/components/schemas/DeclinedAvailability" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "offerId", "availability", "next" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "expired" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "expiresAt": { "$ref": "#/components/schemas/Instant" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "claimId", "offerId", "expiresAt", "next" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "consumed" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "claimId", "offerId", "next" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "revoked" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "claimId", "offerId", "next" ], "additionalProperties": false } ] }, "ClaimStatusResponseV1": { "anyOf": [ { "type": "object", "properties": { "state": { "type": "string", "const": "issued" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "termsRevision": { "$ref": "#/components/schemas/PositiveInteger" }, "expiresAt": { "$ref": "#/components/schemas/Instant" }, "code": { "$ref": "#/components/schemas/ClaimCode" }, "discountUrl": { "$ref": "#/components/schemas/NullableUrl" }, "checkoutModes": { "$ref": "#/components/schemas/ClaimCheckoutModes" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "claimId", "offerId", "termsRevision", "expiresAt", "code", "discountUrl", "checkoutModes", "next" ], "additionalProperties": false }, { "$ref": "#/components/schemas/PendingClaimResponse" }, { "type": "object", "properties": { "state": { "type": "string", "const": "not_issued" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "availability": { "$ref": "#/components/schemas/DeclinedAvailability" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "offerId", "availability", "next" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "expired" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "expiresAt": { "$ref": "#/components/schemas/Instant" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "claimId", "offerId", "expiresAt", "next" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "consumed" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "claimId", "offerId", "next" ], "additionalProperties": false }, { "type": "object", "properties": { "state": { "type": "string", "const": "revoked" }, "claimId": { "$ref": "#/components/schemas/ClaimId" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "operationId": { "$ref": "#/components/schemas/ClaimStatusOperationId" }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "claimId", "offerId", "next" ], "additionalProperties": false } ] }, "PromotionErrorBodyV1": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "enum": [ "CLAIM_LINK_UNAVAILABLE", "MALFORMED_REQUEST", "OFFER_NOT_FOUND", "CLAIM_NOT_FOUND", "STALE_TERMS", "IDEMPOTENCY_CONFLICT", "PROJECTION_CONFLICT", "OFFER_EXPIRED", "PAYLOAD_TOO_LARGE", "INELIGIBLE_INPUT", "PROJECTION_DIGEST_MISMATCH", "RATE_LIMITED", "PROFILE_UNAVAILABLE", "LIVE_AVAILABILITY_UNAVAILABLE", "CLAIM_OUTCOME_UNKNOWN" ] }, "requestId": { "type": "string" }, "mock": { "type": "boolean", "const": true }, "retrySameRequest": { "type": "boolean", "const": true }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "currentOffer": { "$ref": "#/components/schemas/PublicOfferV1" } }, "required": [ "error", "code", "requestId" ], "additionalProperties": false }, "ClaimLinkMintRequestV1": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "termsRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "via": { "type": "string", "pattern": "^[a-z0-9-]{1,40}$" } }, "required": [ "schemaVersion", "termsRevision" ], "additionalProperties": false }, "ClaimLinkMintResponseV1": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "1" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "termsRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "mintedAt": { "$ref": "#/components/schemas/Instant" }, "expiresAt": { "$ref": "#/components/schemas/Instant" }, "claimPageUrl": { "$ref": "#/components/schemas/HttpsUrl" }, "fallbackClaimPageUrl": { "$ref": "#/components/schemas/HttpsUrl" } }, "required": [ "schemaVersion", "offerId", "termsRevision", "mintedAt", "expiresAt", "claimPageUrl", "fallbackClaimPageUrl" ], "additionalProperties": false }, "PromotionMerchant": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 253, "allOf": [ { "not": { "pattern": "^www\\." } } ], "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z0-9-]{0,62}[a-z][a-z0-9-]{0,62}$", "description": "Lowercase host with no leading www., equal to its own normalization." }, "name": { "$ref": "#/components/schemas/ShortText" } }, "required": [ "domain", "name" ], "additionalProperties": false }, "PromotionEligibility": { "type": "object", "properties": { "country": { "type": "string", "const": "US" }, "currency": { "type": "string", "const": "USD" }, "claimsPerEmail": { "type": "number", "const": 1 }, "quantityPerClaim": { "type": "number", "const": 1 } }, "required": [ "country", "currency", "claimsPerEmail", "quantityPerClaim" ], "additionalProperties": false }, "PromotionTitle": { "type": "string", "minLength": 1, "maxLength": 160, "pattern": "^[^\\x00-\\x1F\\x7F-\\x9F\u2028\u2029\u202a-\u202e\u2066-\u2069]*$", "description": "The server also refuses lone surrogates." }, "PromotionDescription": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^(?:[^\\x00-\\x1F\\x7F-\\x9F\u2028\u2029\u202a-\u202e\u2066-\u2069]|\\n)*$", "description": "The server also refuses lone surrogates." }, { "type": "null" } ] }, "PromotionProducts": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "$ref": "#/components/schemas/PublicProduct" } }, "PromotionCheckoutModes": { "minItems": 1, "type": "array", "items": { "$ref": "#/components/schemas/CheckoutMode" }, "uniqueItems": true }, "Instant": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{3})?Z$" }, "OfferId": { "type": "string", "pattern": "^ofr_[A-Za-z0-9]{8,40}$" }, "ClaimId": { "type": "string", "pattern": "^clm_[A-Za-z0-9]{8,40}$" }, "HttpsUrl": { "type": "string", "maxLength": 2048, "pattern": "^[hH][tT][tT][pP][sS]://", "description": "HTTPS URL without credentials or port; server checked." }, "ClaimStatusOperationId": { "description": "Required when the status request uses operationId; must echo that operationId.", "type": "string", "pattern": "^op_[A-Za-z0-9]{8,40}$" }, "ClaimCheckoutModes": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutMode" }, "uniqueItems": true }, "ClaimCode": { "type": "string", "pattern": "^[A-Z0-9-]{6,64}$" }, "OffersQuery_q": { "description": "The server normalizes this value before validating it. Leading and trailing whitespace is trimmed, then it must be 1 to 200 characters on one line.", "type": "string" }, "OffersQuery_merchantDomain": { "description": "The server normalizes this value before validating it. Whitespace is trimmed, letters are lowercased and a leading www. is removed, then it must be a hostname of at most 253 characters.", "type": "string" }, "OffersQuery_productId": { "description": "A Shopify product GID. Requires merchantDomain.", "type": "string", "pattern": "^gid:\\/\\/shopify\\/Product\\/\\d{1,20}$" }, "OffersQuery_variantId": { "description": "A Shopify product variant GID. Requires merchantDomain.", "type": "string", "pattern": "^gid:\\/\\/shopify\\/ProductVariant\\/\\d{1,20}$" }, "OffersQuery_collection": { "description": "A Shopify collection handle, compared in Unicode NFC. Requires merchantDomain. The server normalizes this value before validating it.", "maxLength": 1020, "type": "string" }, "OffersQuery_cursor": { "description": "Opaque cursor from nextCursor. Only valid with the same filters.", "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$" }, "OffersQuery_via": { "description": "Names the signpost an agent followed. Ignored for filtering, cursors and caching.", "type": "string", "pattern": "^[a-z0-9-]{1,40}$" }, "PositiveInteger": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "NullablePositiveInteger": { "anyOf": [ { "$ref": "#/components/schemas/PositiveInteger" }, { "type": "null" } ] }, "PendingClaim": { "type": "object", "properties": { "state": { "type": "string", "const": "pending" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{8,40}$" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "expiresAt": { "$ref": "#/components/schemas/NullableInstant" }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "state", "operationId", "offerId", "expiresAt", "retryAfterSeconds" ], "additionalProperties": false }, "PendingClaimResponse": { "type": "object", "properties": { "state": { "type": "string", "const": "pending" }, "operationId": { "type": "string", "pattern": "^op_[A-Za-z0-9]{8,40}$" }, "offerId": { "$ref": "#/components/schemas/OfferId" }, "expiresAt": { "$ref": "#/components/schemas/NullableInstant" }, "retryAfterSeconds": { "type": "integer", "minimum": 1, "maximum": 60 }, "next": { "type": "string" }, "mock": { "type": "boolean", "const": true } }, "required": [ "state", "operationId", "offerId", "expiresAt", "retryAfterSeconds", "next" ], "additionalProperties": false }, "ShortText": { "type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[^\\x00-\\x1F\\x7F-\\x9F\u2028\u2029\u202a-\u202e\u2066-\u2069]*$", "description": "The server also refuses lone surrogates." }, "NullableUrl": { "anyOf": [ { "$ref": "#/components/schemas/HttpsUrl" }, { "type": "null" } ] }, "NullableInstant": { "anyOf": [ { "$ref": "#/components/schemas/Instant" }, { "type": "null" } ] }, "PromotionShipping": { "anyOf": [ { "$ref": "#/components/schemas/ShippingTerms" }, { "type": "null" } ] }, "DeclinedAvailability": { "type": "string", "enum": [ "paused", "exhausted", "ended", "unavailable" ] }, "ExportCursorText": { "type": "string", "minLength": 1, "maxLength": 512, "pattern": "^[^\\x00-\\x1F\\x7F-\\x9F\u2028\u2029\u202a-\u202e\u2066-\u2069]*$", "description": "The server also refuses lone surrogates." }, "NullableExportCursor": { "anyOf": [ { "$ref": "#/components/schemas/ExportCursorText" }, { "type": "null" } ] }, "CheckoutMode": { "type": "string", "enum": [ "ucp", "acp", "link" ] } }, "parameters": { "OffersQuery_q": { "name": "q", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OffersQuery_q" } }, "OffersQuery_merchantDomain": { "name": "merchantDomain", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/OffersQuery_merchantDomain" } }, "OffersQuery_productId": { "name": "productId", "in": "query", "required": false, "description": "A Shopify product GID. Requires merchantDomain.", "schema": { "$ref": "#/components/schemas/OffersQuery_productId" } }, "OffersQuery_variantId": { "name": "variantId", "in": "query", "required": false, "description": "A Shopify product variant GID. Requires merchantDomain.", "schema": { "$ref": "#/components/schemas/OffersQuery_variantId" } }, "OffersQuery_collection": { "name": "collection", "in": "query", "required": false, "description": "A Shopify collection handle, compared in Unicode NFC. Requires merchantDomain. The server normalizes this value before validating it.", "schema": { "$ref": "#/components/schemas/OffersQuery_collection" } }, "OffersQuery_promotionType": { "name": "promotionType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GIVEAWAY", "PERCENTAGE", "FREE_SHIPPING" ] } }, "OffersQuery_checkoutMode": { "name": "checkoutMode", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CheckoutMode" } }, "OffersQuery_cursor": { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from nextCursor. Only valid with the same filters.", "schema": { "$ref": "#/components/schemas/OffersQuery_cursor" } }, "OffersQuery_limit": { "name": "limit", "in": "query", "required": false, "schema": { "default": 20, "type": "string", "pattern": "^(?:[1-9]|[1-4]\\d|50)$" } }, "OffersQuery_availability": { "name": "availability", "in": "query", "required": false, "schema": { "default": "snapshot", "type": "string", "enum": [ "snapshot", "live" ] } }, "OffersQuery_via": { "name": "via", "in": "query", "required": false, "description": "Names the signpost an agent followed. Ignored for filtering, cursors and caching.", "schema": { "$ref": "#/components/schemas/OffersQuery_via" } }, "ConditionalRead": { "name": "If-None-Match", "in": "header", "required": false, "description": "Return 304 when a cached representation matches. Ignored for live or mock offer reads.", "schema": { "type": "string" } }, "OfferId": { "name": "offerId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/OfferId" } }, "RecoveryCapability": { "name": "X-Lantern-Recovery", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43,128}$" } } }, "headers": { "LanternMock": { "description": "True only for sample data.", "schema": { "type": "string", "const": "true" } }, "RepresentationETag": { "description": "Representation validator; absent on live or mock reads.", "schema": { "type": "string" } }, "RateLimitRetryAfter": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer", "minimum": 1 } }, "NoStore": { "schema": { "type": "string", "const": "no-store" } } } } }