{"components":{"schemas":{"AddCartItemsRequest":{"description":"Add one or more items to a cart. `items` has the same shape as when creating the cart; an item for an option already in the cart increases that line's quantity instead of adding a second line.","properties":{"country":{"description":"ISO-3166 alpha-2 country code. Use `US` -- the only market available today.","type":"string"},"items":{"items":{"$ref":"#/components/schemas/CartItemInput"},"type":"array"}},"required":["items"],"type":"object"},"AuthenticationError":{"description":"Returned with HTTP 401 when the API key is missing or invalid, before the request reaches the endpoint.","properties":{"code":{"description":"Machine-readable failure class, for example invalid_argument, not_found or unauthenticated.","type":"string"},"details":{"description":"Always `null` on an authentication failure.","nullable":true,"type":"object"},"message":{"description":"Human-readable explanation. Do not branch on it.","type":"string"}},"required":["code","message"],"type":"object"},"CartItemInput":{"description":"One requested line item on a create/add-items request.","properties":{"expectedPrice":{"description":"The per-unit price your site is showing, in minor units. When it disagrees with Groupon's live price the call fails with `PRICE_MISMATCH` and reports the current price, so the shopper never sees one price on your site and another at checkout. Optional, but strongly recommended.","type":"number"},"optionId":{"type":"string"},"productId":{"type":"string"},"quantity":{"type":"number"}},"required":["productId","optionId","quantity"],"type":"object"},"CreateCartRequest":{"description":"Create a cart with its first item or items. At least one item is required.","properties":{"clientReference":{"type":"string"},"country":{"description":"ISO-3166 alpha-2 country code. Use `US` -- the only market available today.","type":"string"},"currency":{"type":"string"},"items":{"items":{"$ref":"#/components/schemas/CartItemInput"},"type":"array"}},"required":["country","items"],"type":"object"},"OctoAvailabilityType":{"enum":["START_TIME","OPENING_HOURS"],"type":"string"},"OctoBookingStatus":{"description":"The lifecycle state of a booking.\n\n| Value | Meaning |\n|---|---|\n| `ON_HOLD` | Reserved, and either no payment has been taken yet, or payment was taken but the tickets' state could not be read yet. Read the order again later. |\n| `PENDING` | Payment is being processed, or it has been taken and the tickets are still being issued. Read the order again later. |\n| `CONFIRMED` | Paid and reserved. The shopper's vouchers are available. |\n| `REDEEMED` | The shopper has used the booking. |\n| `CANCELLED` | Cancelled or refunded. |\n| `REJECTED` | The hold was taken but payment could not be captured. Not redeemable, and it will not become redeemable. |\n| `EXPIRED` | The hold lapsed before payment. |","enum":["ON_HOLD","CONFIRMED","REDEEMED","CANCELLED","EXPIRED","REJECTED","PENDING"],"type":"string"},"OctoCart":{"description":"A cart. Keep the `id` from the create response and send it as `cartId` on every later call about this cart.","properties":{"buyLink":{"description":"The checkout URL for this cart. Send the shopper here to pay. Always present.\n\n- **With CJ** (a CJ publisher id is registered for your API key): an affiliate\nlink that credits your CJ account with the sale.\n- **Without CJ** (no CJ publisher id is registered for your API key): the direct\nGroupon checkout page for the cart. No affiliate attribution applies.\n\nThe checkout page itself is cobranded with your display name and logo when a\nlogo URL is registered for your API key, and the standard Groupon checkout when\nit is not.\n\nIn both cases take it from the most recent cart response and use it unchanged --\nit is rebuilt on every call, and a hand-constructed URL earns no commission.","type":"string"},"clientReference":{"nullable":true,"type":"string"},"country":{"description":"ISO-3166 alpha-2 country code. Use `US` -- the only market available today.","type":"string"},"currency":{"type":"string"},"id":{"type":"string"},"itemCount":{"type":"number"},"items":{"items":{"$ref":"#/components/schemas/OctoCartItem"},"type":"array"},"messages":{"items":{"$ref":"#/components/schemas/OctoCartMessage"},"type":"array"},"partner":{"$ref":"#/components/schemas/OctoCartPartner"},"status":{"$ref":"#/components/schemas/OctoCartStatus"},"testMode":{"type":"boolean"},"totals":{"$ref":"#/components/schemas/OctoCartTotals"},"utcCreatedAt":{"nullable":true,"type":"string"},"utcExpiresAt":{"nullable":true,"type":"string"},"utcUpdatedAt":{"nullable":true,"type":"string"}},"required":["id","status","testMode","partner","buyLink","country","currency","clientReference","itemCount","items","totals","messages","utcCreatedAt","utcUpdatedAt","utcExpiresAt"],"type":"object"},"OctoCartItem":{"description":"One line on a cart.\n\n`productId` and `optionId` are the catalog ids used both to add a line and to\nlook one up; `id` is the line's own identifier and carries the same value as\n`optionId`.\n\n`title`, `optionTitle`, `media` and `pricing` are read live from the catalogue\non every request. When a deal is sold out, has ended, or the option no longer\nexists, `available` is `false`, `unavailableReason` says which, and those\nfields come back `null` or empty -- the rest of the cart still reads normally.","properties":{"available":{"type":"boolean"},"id":{"type":"string"},"lineTotal":{"description":"`pricing.retail * quantity`, or `null` when `pricing` is `null` (degraded line -- excluded from `totals`, not treated as $0).","nullable":true,"type":"number"},"media":{"items":{"$ref":"#/components/schemas/OctoMedia"},"type":"array"},"optionId":{"type":"string"},"optionTitle":{"nullable":true,"type":"string"},"pricing":{"allOf":[{"$ref":"#/components/schemas/OctoCartItemPricing"}],"nullable":true},"productId":{"type":"string"},"quantity":{"type":"number"},"title":{"nullable":true,"type":"string"},"unavailableReason":{"$ref":"#/components/schemas/OctoCartItemUnavailableReason"}},"required":["id","productId","optionId","title","optionTitle","media","quantity","available","unavailableReason","pricing","lineTotal"],"type":"object"},"OctoCartItemPricing":{"description":"What one cart line costs.\n\n`null` on a line whose price could not be read; `messages[]` says why.","properties":{"currency":{"type":"string"},"currencyPrecision":{"type":"number"},"includedTaxes":{"description":"Tax already included in `retail`, itemised.\n\nEmpty when Groupon publishes no per-line tax breakdown for this deal.","items":{"$ref":"#/components/schemas/OctoTax"},"type":"array"},"net":{"nullable":true,"type":"number"},"original":{"type":"number"},"retail":{"type":"number"}},"required":["original","retail","net","currency","currencyPrecision","includedTaxes"],"type":"object"},"OctoCartItemUnavailableReason":{"description":"Why a cart line cannot be bought, or `null` when it is available.","enum":["SOLD_OUT","DEAL_ENDED","OPTION_REMOVED"],"nullable":true,"type":"string"},"OctoCartMessage":{"description":"A non-fatal advisory about one cart line.\n\nRead these alongside the cart: a line can be present but not fully priced, and\nthe message says why. They never mean the request failed.","properties":{"code":{"type":"string"},"content":{"type":"string"},"path":{"description":"JSONPath into the cart response, e.g. `$.items[0]`.","type":"string"},"type":{"enum":["warning","info"],"type":"string"}},"required":["type","code","content","path"],"type":"object"},"OctoCartPartner":{"description":"The partner the cart belongs to -- you.","properties":{"name":{"description":"Your display name, as shown to shoppers on Groupon's checkout page.","nullable":true,"type":"string"},"partnerId":{"description":"Your partner id: the stable identifier stamped on orders placed from this cart. It does not change when your API key is rotated.","type":"string"}},"required":["partnerId","name"],"type":"object"},"OctoCartStatus":{"description":"The cart's lifecycle state.","enum":["ACTIVE","LOCKED","CHECKED_OUT","EXPIRED","ABANDONED"],"type":"string"},"OctoCartTotals":{"description":"Cart totals, in minor units.\n\nA line whose price could not be read contributes nothing here; `messages[]`\nsays which, so a total is never silently short.","properties":{"currency":{"type":"string"},"currencyPrecision":{"type":"number"},"grandTotal":{"type":"number"},"savings":{"type":"number"},"subtotal":{"type":"number"}},"required":["subtotal","savings","grandTotal","currency","currencyPrecision"],"type":"object"},"OctoContactField":{"enum":["firstName","lastName","emailAddress","phoneNumber","country","notes"],"type":"string"},"OctoDeliveryFormat":{"enum":["PDF_URL","QRCODE"],"type":"string"},"OctoDeliveryMethod":{"enum":["TICKET","VOUCHER"],"type":"string"},"OctoDiscountedPrice":{"description":"A promotional price for one option, and what a shopper needs to use it.\n\nAll three fields travel together, and the whole object is `null` when no\npromotion applies.\n\nA Groupon extension -- not part of the standard OCTO contract.","properties":{"amount":{"description":"The promotional price, in the same minor units and currency as the sibling `retail`.","type":"number"},"endDate":{"description":"When the promotion stops working -- ISO-8601 with an explicit UTC offset, e.g. `\"2026-04-02T23:59:00+02:00\"`. `null` when no end date is known.","nullable":true,"type":"string"},"promoCode":{"description":"The code a shopper enters to get `amount`, e.g. `\"PRIMAVERA\"`. `null` when the promotion has no code.","nullable":true,"type":"string"}},"required":["amount","promoCode","endDate"],"type":"object"},"OctoDurationUnit":{"enum":["hour","minute","day"],"type":"string"},"OctoError":{"description":"The error every failed request reports. Branch on `error`, never on `errorMessage`. The five price fields are present only when `error` is `PRICE_MISMATCH`.","properties":{"currency":{"description":"`PRICE_MISMATCH` only: ISO-4217 currency of both prices.","type":"string"},"currencyPrecision":{"description":"`PRICE_MISMATCH` only: decimal places to divide by for display.","type":"number"},"currentPrice":{"description":"`PRICE_MISMATCH` only: the current price, in minor units. Re-render with it and retry in one round-trip.","type":"number"},"error":{"$ref":"#/components/schemas/OctoErrorCode"},"errorMessage":{"description":"Human-readable explanation, for your logs. Do not branch on it.","type":"string"},"expectedPrice":{"description":"`PRICE_MISMATCH` only: the price you sent, in minor units.","type":"number"},"path":{"description":"`PRICE_MISMATCH` only: JSONPath into your request naming the item concerned, e.g. `$.items[0]` or `$.expectedPrice`.","type":"string"},"requestId":{"description":"Quote it when contacting Groupon about the failure.","type":"string"}},"required":["error","errorMessage","requestId"],"type":"object"},"OctoErrorCode":{"description":"The machine-readable error code returned on a failed request.\n\nEvery error response carries one of these as `error`, alongside a\nhuman-readable `errorMessage`. Branch on the code, not the message.","enum":["INVALID_PRODUCT_ID","INVALID_BOOKING_UUID","INVALID_CART_ID","BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","INVALID_BOOKING_STATE","UNPROCESSABLE_ENTITY","PRICE_MISMATCH","PRODUCT_NOT_CARTABLE","CART_ITEM_LIMIT","RATE_LIMITED","SELF_REGISTRATION_CLOSED","INTERNAL_SERVER_ERROR"],"type":"string"},"OctoErrorEnvelope":{"description":"Returned on every failure other than authentication. The HTTP status matches `code`.","properties":{"code":{"description":"Machine-readable failure class, for example invalid_argument, not_found or unauthenticated.","type":"string"},"details":{"allOf":[{"$ref":"#/components/schemas/OctoError"}],"nullable":true,"type":"object"},"message":{"description":"Human-readable explanation. Do not branch on it.","type":"string"}},"required":["code","message"],"type":"object"},"OctoLocation":{"description":"Content capability — geographic redemption location.","properties":{"city":{"nullable":true,"type":"string"},"country":{"nullable":true,"type":"string"},"id":{"nullable":true,"type":"string"},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"name":{"nullable":true,"type":"string"},"postalCode":{"nullable":true,"type":"string"},"state":{"description":"Two-letter state or region code, e.g. `NV`. The `state` filter on `GET /products` takes the full name (`Nevada`) instead.","nullable":true,"type":"string"},"street":{"nullable":true,"type":"string"}},"required":["id","name","latitude","longitude","city","state","country","postalCode","street"],"type":"object"},"OctoMedia":{"description":"Content capability — a media asset.","properties":{"height":{"nullable":true,"type":"number"},"role":{"type":"string"},"url":{"type":"string"},"width":{"nullable":true,"type":"number"}},"required":["url","role","width","height"],"type":"object"},"OctoOption":{"properties":{"active":{"description":"Whether this option is currently live.\n\nAn active deal can still carry inactive options, so check this before\noffering one. `null` means Groupon does not know -- treat it as unknown, not\nas inactive. To list only live options, filter on `active !== false`.\n\nA Groupon extension -- not part of the standard OCTO contract.","nullable":true,"type":"boolean"},"availabilityLocalStartTimes":{"description":"Always empty today, for EVERY product regardless of `availabilityType` — start times arrive with the availability endpoints, which are out of scope. A START_TIME product does not carry them here either.","items":{"type":"string"},"type":"array"},"cancellationCutoff":{"type":"string"},"cancellationCutoffAmount":{"type":"number"},"cancellationCutoffUnit":{"$ref":"#/components/schemas/OctoDurationUnit"},"default":{"type":"boolean"},"id":{"type":"string"},"internalName":{"type":"string"},"reference":{"nullable":true,"type":"string"},"requiredContactFields":{"items":{"$ref":"#/components/schemas/OctoContactField"},"type":"array"},"restrictions":{"$ref":"#/components/schemas/OctoOptionRestrictions"},"selections":{"description":"Groupon extension. Always present — an empty array when the option carries no choose-one attribute, which is the majority case.","items":{"$ref":"#/components/schemas/OctoSelection"},"type":"array"},"units":{"items":{"$ref":"#/components/schemas/OctoUnit"},"type":"array"}},"required":["id","default","internalName","reference","active","availabilityLocalStartTimes","cancellationCutoff","cancellationCutoffAmount","cancellationCutoffUnit","requiredContactFields","restrictions","units","selections"],"type":"object"},"OctoOptionRestrictions":{"properties":{"maxUnits":{"nullable":true,"type":"number"},"minUnits":{"type":"number"}},"required":["minUnits","maxUnits"],"type":"object"},"OctoPricing":{"properties":{"currency":{"type":"string"},"currencyPrecision":{"type":"number"},"discountedPrice":{"allOf":[{"$ref":"#/components/schemas/OctoDiscountedPrice"}],"description":"The promotional price a shopper pays with an active Groupon promo code, plus the code and its expiry.\n\n`null` when no promotion applies. Absent entirely on endpoints where a\npromotional price has no meaning -- only `GET /octo-gateway/v1/products` populates it.\n\nA Groupon extension -- not part of the standard OCTO contract.","nullable":true},"includedTaxes":{"items":{"$ref":"#/components/schemas/OctoTax"},"type":"array"},"net":{"nullable":true,"type":"number"},"original":{"type":"number"},"retail":{"type":"number"}},"required":["original","retail","net","currency","currencyPrecision","includedTaxes"],"type":"object"},"OctoProduct":{"properties":{"allowFreesale":{"type":"boolean"},"availabilityRequired":{"type":"boolean"},"availabilityType":{"$ref":"#/components/schemas/OctoAvailabilityType"},"categoryLabels":{"items":{"type":"string"},"type":"array"},"deliveryFormats":{"items":{"$ref":"#/components/schemas/OctoDeliveryFormat"},"type":"array"},"deliveryMethods":{"items":{"$ref":"#/components/schemas/OctoDeliveryMethod"},"type":"array"},"description":{"type":"string"},"id":{"type":"string"},"instantConfirmation":{"type":"boolean"},"instantDelivery":{"type":"boolean"},"internalName":{"type":"string"},"locale":{"type":"string"},"locations":{"items":{"$ref":"#/components/schemas/OctoLocation"},"type":"array"},"media":{"items":{"$ref":"#/components/schemas/OctoMedia"},"type":"array"},"options":{"items":{"$ref":"#/components/schemas/OctoOption"},"type":"array"},"redemptionMethod":{"$ref":"#/components/schemas/OctoRedemptionMethod"},"reference":{"nullable":true,"type":"string"},"shortDescription":{"type":"string"},"status":{"allOf":[{"$ref":"#/components/schemas/OctoProductStatus"}],"description":"Whether this deal is on sale.\n\nSeparate from the `active` query parameter, which filters the page, and from\nan option's `available` flag, which is about bookable availability."},"timeZone":{"type":"string"},"title":{"description":"Content capability (octo/content)","type":"string"}},"required":["id","internalName","reference","locale","timeZone","allowFreesale","instantConfirmation","instantDelivery","availabilityRequired","availabilityType","deliveryFormats","deliveryMethods","redemptionMethod","options","status","title","description","shortDescription","media","locations","categoryLabels"],"type":"object"},"OctoProductStatus":{"description":"A deal's lifecycle state.\n\n`active` is on sale, `sold_out` has no inventory left, and `expired` has\nended. A Groupon extension, not part of the standard OCTO contract.","enum":["active","sold_out","expired"],"type":"string"},"OctoRedemptionMethod":{"enum":["DIGITAL","PRINT","MANIFEST"],"type":"string"},"OctoSelection":{"description":"A choice the shopper must make when booking, such as a pickup point or a service variant.\n\nExactly one value must be chosen. Echo `attributeId` and the chosen value's\n`id` back as `selections: [{ attributeId, valueId }]` when you request\navailability.\n\nA Groupon extension, not part of the standard OCTO contract.","properties":{"attributeId":{"type":"string"},"required":{"description":"Always true — a choose-one attribute has no \"skip\" value.","type":"boolean"},"title":{"type":"string"},"values":{"items":{"$ref":"#/components/schemas/OctoSelectionValue"},"type":"array"}},"required":["attributeId","title","required","values"],"type":"object"},"OctoSelectionValue":{"description":"One selectable value of a choose-one attribute, with the id echoed back verbatim in availability requests.","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"type":"object"},"OctoSupplierContact":{"description":"The supplier's contact block (all fields optional per OCTO).","properties":{"address":{"nullable":true,"type":"string"},"email":{"nullable":true,"type":"string"},"telephone":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"}},"required":["website","email","telephone","address"],"type":"object"},"OctoTax":{"description":"Pricing capability — a single included-tax line.","properties":{"name":{"type":"string"},"net":{"description":"Groupon exposes no partner-net tax at this layer, so `net` is null (spec allows it).","nullable":true,"type":"number"},"original":{"type":"number"},"retail":{"type":"number"}},"required":["name","retail","original","net"],"type":"object"},"OctoUnit":{"properties":{"id":{"type":"string"},"internalName":{"type":"string"},"pricing":{"description":"Pricing capability. One row per unit (pricingPer = UNIT).","items":{"$ref":"#/components/schemas/OctoPricing"},"type":"array"},"reference":{"nullable":true,"type":"string"},"restrictions":{"$ref":"#/components/schemas/OctoUnitRestrictions"},"type":{"$ref":"#/components/schemas/OctoUnitType"}},"required":["id","internalName","reference","type","restrictions","pricing"],"type":"object"},"OctoUnitRestrictions":{"properties":{"maxQuantity":{"nullable":true,"type":"number"},"minQuantity":{"nullable":true,"type":"number"}},"required":["minQuantity","maxQuantity"],"type":"object"},"OctoUnitType":{"enum":["ADULT","YOUTH","CHILD","INFANT","FAMILY","SENIOR","STUDENT","MILITARY","OTHER"],"type":"string"},"PartnerBookingGetResponse":{"description":"One of your orders. On failure the error fields are set instead and every booking field is absent.","properties":{"error":{"$ref":"#/components/schemas/OctoErrorCode"},"errorMessage":{"type":"string"},"id":{"type":"string"},"items":{"items":{"$ref":"#/components/schemas/PartnerBookingItem"},"type":"array"},"requestId":{"type":"string"},"status":{"$ref":"#/components/schemas/OctoBookingStatus"},"supplierReference":{"nullable":true,"type":"string"},"utcCreatedAt":{"type":"string"},"uuid":{"type":"string"}},"type":"object"},"PartnerBookingItem":{"description":"One line of an order: a product, the option bought, and its tickets.","properties":{"optionId":{"description":"The option bought, as `options[].id` on `GET /products` and `optionId` on the cart item.","type":"string"},"productId":{"description":"The product, as `id` on `GET /products` and as `productId` on the cart item you sent. Use it to join this line back to your catalog. `null` when the product is no longer in the catalog; `optionId` still identifies what was bought.","nullable":true,"type":"string"},"quantity":{"description":"How many of this option were bought.","type":"number"},"status":{"allOf":[{"$ref":"#/components/schemas/OctoBookingStatus"}],"description":"This item's own state. It can differ from the order's: one item may be fully redeemed while another is still confirmed, or cancelled while another is not. `CANCELLED` once every ticket of the item is cancelled."},"unitItems":{"description":"One entry per ticket of this item.","items":{"$ref":"#/components/schemas/PartnerBookingUnitItem"},"type":"array"}},"required":["productId","optionId","quantity","status","unitItems"],"type":"object"},"PartnerBookingUnitItem":{"description":"One reserved unit on an order -- a single ticket or voucher.","properties":{"myGrouponUrl":{"description":"A link to this unit on My Groupon, where the shopper views and redeems it.\n\nShow it to the shopper after checkout; it is their voucher.","type":"string"},"status":{"allOf":[{"$ref":"#/components/schemas/OctoBookingStatus"}],"description":"This ticket's own state, which can differ from the order's -- one ticket may be redeemed or cancelled while others are not."},"uuid":{"description":"This ticket's instance id — `order.items[].inventoryUnits[i].id`.","type":"string"}},"required":["uuid","status","myGrouponUrl"],"type":"object"},"PartnerMeGetResponse":{"description":"Your partner registration. On failure the error fields are set instead and every registration field is absent.","properties":{"category0":{"items":{"type":"string"},"type":"array"},"category1":{"items":{"type":"string"},"type":"array"},"category2":{"items":{"type":"string"},"type":"array"},"cjPublisherId":{"nullable":true,"type":"string"},"createdAt":{"type":"string"},"displayName":{"type":"string"},"error":{"$ref":"#/components/schemas/OctoErrorCode"},"errorMessage":{"type":"string"},"inventoryCountries":{"items":{"type":"string"},"type":"array"},"inventoryStates":{"items":{"type":"string"},"type":"array"},"logoUrl":{"nullable":true,"type":"string"},"maxPageSize":{"nullable":true,"type":"number"},"partnerContactEmail":{"type":"string"},"partnerContactName":{"type":"string"},"partnerId":{"type":"string"},"redirectUrl":{"nullable":true,"type":"string"},"requestId":{"type":"string"},"status":{"$ref":"#/components/schemas/PartnerStatus"},"updatedAt":{"type":"string"}},"type":"object"},"PartnerRegisterResponse":{"description":"Your partner registration and API key. On failure the error fields are set instead and both are absent.","properties":{"error":{"$ref":"#/components/schemas/OctoErrorCode"},"errorMessage":{"type":"string"},"partner":{"$ref":"#/components/schemas/PartnerRegistrationView"},"requestId":{"type":"string"},"token":{"type":"string"}},"type":"object"},"PartnerRegistrationInput":{"description":"A partner registration to create.","properties":{"category0":{"description":"Category permalinks you will sell at depth 0 (e.g. `local`). Omit or send `[]` for no restriction.","items":{"type":"string"},"type":"array"},"category1":{"description":"Category permalinks you will sell at depth 1 (e.g. `things-to-do`). Omit or send `[]` for no restriction.","items":{"type":"string"},"type":"array"},"category2":{"description":"Category permalinks you will sell at depth 2. Omit or send `[]` for no restriction.","items":{"type":"string"},"type":"array"},"cjPublisherId":{"description":"Your Commission Junction publisher id, if you have one. With it, cart `buyLink`s are CJ affiliate links; omit it (or send `null` or blank) and `buyLink` is the direct Groupon checkout page.","nullable":true,"type":"string"},"displayName":{"description":"Shown to shoppers on Groupon's checkout. At most 60 characters, Latin letters only. It must not contain \"Groupon\", a web address, an email address, a phone number, or invisible characters. A name that breaks a rule is rejected with `BAD_REQUEST` naming the rule, and the call counts toward the rate limit.","type":"string"},"inventoryCountries":{"description":"Countries you will sell, ISO-3166 alpha-2. Only `US` is available today; omit it for `[\"US\"]`.","items":{"type":"string"},"type":"array"},"inventoryStates":{"description":"US states you will sell, by full name. Omit or send `[]` for no state restriction.","items":{"type":"string"},"type":"array"},"logoUrl":{"description":"Logo shown on Groupon's cobranded checkout. Must be an `https://` URL. Omit it and your shoppers check out on the standard Groupon page.","type":"string"},"maxPageSize":{"description":"Your ceiling on `GET /products?limit=`, a positive integer. Omit for the service default of 1,000.","type":"number"},"partnerContactEmail":{"description":"Where Groupon contacts you.","type":"string"},"partnerContactName":{"description":"The person Groupon contacts about this integration.","type":"string"},"redirectUrl":{"description":"Where Groupon's checkout sends the shopper back to after payment. Must be an `https://` URL.","type":"string"}},"required":["displayName","partnerContactName","partnerContactEmail"],"type":"object"},"PartnerRegistrationView":{"description":"A partner registration. Never includes the API key.","properties":{"category0":{"description":"Category permalinks you may sell at depth 0 (e.g. `local`). Empty = no restriction.","items":{"type":"string"},"type":"array"},"category1":{"description":"Category permalinks you may sell at depth 1 (e.g. `things-to-do`). Empty = no restriction.","items":{"type":"string"},"type":"array"},"category2":{"description":"Category permalinks you may sell at depth 2. Empty = no restriction.","items":{"type":"string"},"type":"array"},"cjPublisherId":{"description":"`null` = no CJ publisher id: cart `buyLink` is the direct Groupon checkout page.","nullable":true,"type":"string"},"createdAt":{"type":"string"},"createdBy":{"description":"INTERNAL: portal only; GET /octo-gateway/v1/partners/me omits both (they can hold employee user ids).","type":"string"},"displayName":{"description":"Shown to shoppers on Groupon's checkout.","type":"string"},"inventoryCountries":{"description":"Countries you may sell, ISO-3166 alpha-2.","items":{"type":"string"},"type":"array"},"inventoryStates":{"description":"US states you may sell, by full name (`Pennsylvania`, not `PA`). Empty = no state restriction.","items":{"type":"string"},"type":"array"},"logoUrl":{"description":"Logo shown on Groupon's cobranded checkout; `null` = no logo, and your shoppers check out on the standard Groupon page instead.","nullable":true,"type":"string"},"maxPageSize":{"description":"Your ceiling on `GET /products?limit=`; `null` = the service default.","nullable":true,"type":"number"},"partnerContactEmail":{"type":"string"},"partnerContactName":{"type":"string"},"partnerId":{"description":"Your partner id: stable for the life of the registration, and the id Groupon attributes your orders to.","type":"string"},"redirectUrl":{"description":"Where Groupon's checkout sends the shopper back to after payment; `null` = no link.","nullable":true,"type":"string"},"status":{"$ref":"#/components/schemas/PartnerStatus"},"updatedAt":{"type":"string"},"updatedBy":{"type":"string"}},"required":["partnerId","displayName","cjPublisherId","partnerContactName","partnerContactEmail","inventoryCountries","inventoryStates","category0","category1","category2","logoUrl","redirectUrl","maxPageSize","status","createdAt","updatedAt","createdBy","updatedBy"],"type":"object"},"PartnerStatus":{"description":"`active`, or `deactivated` once the partner is switched off.","enum":["active","deactivated"],"type":"string"},"ProductsListResponse":{"description":"A page of products. On failure the error fields are set instead and every product field is absent.","properties":{"error":{"$ref":"#/components/schemas/OctoErrorCode"},"errorMessage":{"type":"string"},"hasMore":{"type":"boolean"},"nextCursor":{"nullable":true,"type":"string"},"products":{"items":{"$ref":"#/components/schemas/OctoProduct"},"type":"array"},"requestId":{"type":"string"},"timestamp":{"type":"string"}},"type":"object"},"SupplierGetResponse":{"description":"Your supplier record. On failure the error fields are set instead and every supplier field is absent.","properties":{"contact":{"$ref":"#/components/schemas/OctoSupplierContact"},"endpoint":{"type":"string"},"error":{"$ref":"#/components/schemas/OctoErrorCode"},"errorMessage":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"requestId":{"type":"string"}},"type":"object"},"UpdateCartItemRequest":{"description":"Change the quantity of one line in a cart. A quantity of 0 is rejected; to remove the line, delete it instead.","properties":{"country":{"description":"ISO-3166 alpha-2 country code. Use `US` -- the only market available today.","type":"string"},"expectedPrice":{"description":"The per-unit price your site is showing, in minor units. When it disagrees with Groupon's live price the call fails with `PRICE_MISMATCH` and reports the current price, so the shopper never sees one price on your site and another at checkout. Optional, but strongly recommended.","type":"number"},"quantity":{"type":"number"}},"required":["quantity"],"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"Partner API key, returned once by `POST /octo-gateway/v1/register` or issued by Groupon. Format: `grpn_` + 8 hex + `_` + 56 hex. Send it on every request except `POST /octo-gateway/v1/register`. This is not a bearer token: `Authorization: Bearer ...` returns 401.","in":"header","name":"g-api-key","type":"apiKey"}}},"info":{"description":"Pull Groupon deals into your own storefront, mirror a shopper's cart, and read order status after checkout.\n\nGet an API key with `POST /octo-gateway/v1/register`, the only endpoint called without one. The key is returned once: store it server-side. Authenticate with the `g-api-key` header on every other request. All amounts are integers in minor units (cents for USD); divide by 10^`currencyPrecision` to display. Treat `cursor` values as opaque and send them back exactly as received. Only the `US` market is available today.\n\nCall these endpoints from your backend, never from browser JavaScript or a mobile app: the API key must not be exposed to end users.\n\nCheckout: send the shopper to the `buyLink` of the most recent cart response, unchanged; do not construct it yourself. Which checkout path applies depends on whether a CJ publisher id is registered for your API key. With CJ, `buyLink` is a CJ affiliate link that credits your CJ account with the sale. Without CJ, `buyLink` is the direct Groupon checkout page for the cart, and no affiliate attribution applies. `buyLink` is present on every cart response in both cases. The checkout page is cobranded with your display name and logo when a logo URL is registered for your API key; without one, shoppers check out on the standard Groupon page.\n\nAn order read returns every item of the order under `items`, one per product and option bought, each with its own tickets. An order placed from a cart has one item per cart line; this is a Groupon extension to the OCTO booking model, which describes a single product.\n\nMatch each order item to what you sold by its `productId` and `optionId`: they are the product's `id` and the option's `id` on `GET /products`, and the ids you sent on the cart line.\n\nEndpoints under `/octo/v1/` are deprecated aliases of the same endpoints under `/octo-gateway/v1/`, kept for integrations built before the rename and removed on 2027-03-31.","title":"Groupon Partner Storefront API (OCTO)","version":"v004"},"openapi":"3.0.3","paths":{"/octo-gateway/v1/carts":{"post":{"description":"There is no empty cart -- `items` is required and must hold at least one\nentry. All items are validated before anything is added: if any one fails,\nnothing is added and no cart is created.\n\nReturns the full cart, including the `buyLink` you must use verbatim as your\ncheckout URL. Store the returned cart `id` against the shopper's session on\nyour server. Only your partner account can read or change a cart it created;\nany other cart id returns `INVALID_CART_ID`.\n\nSend `expectedPrice` per item: the per-unit price your site is showing. If\nGroupon's live price differs the call fails with `PRICE_MISMATCH` and reports\nthe current price, so you can update your side and ask the shopper to confirm\nbefore retrying. Without it, the shopper may see one price on your site and\nanother at checkout.\n\nLimits: at most 20 different options per cart, and quantity 1 to 100 per line.","operationId":"cartsCreate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCartRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Create a cart, together with its first item or items."}},"/octo-gateway/v1/carts/{cartId}":{"delete":{"description":"Call this when the shopper empties their basket or leaves, and discard the\n`cartId` afterwards. Also discard it once an order has been placed from it.\n\nAfter abandoning, reading the cart returns an empty cart (`itemCount: 0`), and\nchanging or removing a line returns `INVALID_PRODUCT_ID`. Adding an item does\nnot fail -- it starts a fresh cart under the same id -- so stop using the id and\nuse a new cart for anything the shopper adds next.\n\nA `cartId` that was not created by your partner account returns `INVALID_CART_ID`.","operationId":"cartsAbandon","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No content. The response has no body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Abandon a cart. Returns no body on success."},"get":{"description":"Always read the `buyLink` from the most recent cart response rather than\nstoring one -- it is refreshed on every call.\n\nA `cartId` that was not created by your partner account returns `INVALID_CART_ID`.","operationId":"cartsGet","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}},{"description":"ISO-3166 alpha-2 country code. Use `US` -- the only market available today.","in":"query","name":"country","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Read a cart: its items, totals and current `buyLink`."}},"/octo-gateway/v1/carts/{cartId}/items":{"post":{"description":"This ADDS quantity rather than replacing it, so a retry after a timeout can\ndouble a line. On a timeout, read the cart back and reconcile instead of\nblind-retrying. Adding an option the cart already holds increases that line's\nquantity rather than creating a second line.\n\nReturns the full updated cart, including a fresh `buyLink`.\n\nLimits: at most 20 different options per cart, and quantity 1 to 100 per line.\n\nA `cartId` that was not created by your partner account returns `INVALID_CART_ID`.","operationId":"cartItemsAdd","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCartItemsRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Add one or more items to an existing cart."}},"/octo-gateway/v1/carts/{cartId}/items/{itemId}":{"delete":{"description":"`itemId` is the cart line's `id`, which is the `optionId` the line was\ncreated from. Returns the full updated cart; removing the last line leaves a\ncart with `itemCount: 0` rather than deleting it.\n\nA `cartId` that was not created by your partner account returns `INVALID_CART_ID`.","operationId":"cartItemsRemove","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}},{"in":"path","name":"itemId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Remove one item from a cart."},"patch":{"description":"The quantity you send REPLACES the line's quantity (unlike adding an item,\nwhich increases it). Valid range is 1 to 100; to remove a line, use the\nremove-item endpoint rather than setting the quantity to zero.\n\nReturns the full updated cart, including a fresh `buyLink`.\n\nA `cartId` that was not created by your partner account returns `INVALID_CART_ID`.","operationId":"cartItemsUpdate","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}},{"in":"path","name":"itemId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCartItemRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Change the quantity of one cart item."}},"/octo-gateway/v1/partner-bookings/{uuid}":{"get":{"description":"Gives the order's status and, under `items`, every product and option that\nwas bought with one \"View on Groupon\" link per ticket, so you can confirm the\npurchase, match each item to the cart line you sent, and show the shopper\ntheir vouchers.\n\nPoll this after the shopper returns from checkout. An order may briefly\nreport as pending before payment settles.","operationId":"partnerBookingGet","parameters":[{"in":"path","name":"uuid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerBookingGetResponse"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoError"}}},"description":"Error. The body is the error object itself, with HTTP 400. Branch on `error`, not on the status."}},"summary":"Read an order after checkout, by the `grouponOrderUuid` Groupon appends to your redirect URL."}},"/octo-gateway/v1/partners/me":{"get":{"description":"Use it to check that your API key works. The response never includes the key.\nTo change anything shown here, contact Groupon support.","operationId":"partnerMeGet","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerMeGetResponse"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoError"}}},"description":"Error. The body is the error object itself, with HTTP 400. Branch on `error`, not on the status."}},"summary":"Read your own partner registration: what you registered and what you may sell."}},"/octo-gateway/v1/products":{"get":{"description":"Walk the full catalogue once, then poll for changes with `updatedSince`.\nPaginate by sending the returned `nextCursor` back as `cursor`, keeping every\nother query parameter identical across one walk. `timestamp` is present only\non the last page (`hasMore: false`); use it as the next walk's `updatedSince`.\n\nDeals that require a booking are not returned by this endpoint.\n\nOnly the `US` market is available today, so `country=US` is required.","operationId":"productsList","parameters":[{"description":"ISO-3166 alpha-2 country code. Use `US` -- the only market available today.\n\nA Groupon extension; required.","in":"query","name":"country","required":true,"schema":{"type":"string"}},{"description":"Products per page. Defaults to 100; **10 is recommended**. The maximum is 1,000 unless your account has a different cap, and a larger value is silently reduced to it rather than rejected. A large page can exceed the request time budget and fail, so walk the catalogue with `limit=10`.\n\nA Groupon extension.","in":"query","name":"limit","required":false,"schema":{"type":"number"}},{"description":"The `nextCursor` from the previous page. Omit on the first page.\n\nTreat the value as opaque and send it back exactly as received, keeping\nevery other query parameter identical across one walk.\n\nA Groupon extension.","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"US state matched against the deal's divisions (Groupon extension).\n\nSend the FULL STATE NAME exactly as stored, e.g. `Pennsylvania`,\n`California`, `New York` — NOT an abbreviation such as `PA`, and not\n`PENNSYLVANIA`. The match is case-SENSITIVE: only surrounding whitespace is\ntrimmed, and the value is otherwise passed through verbatim, so a\ndifferently-cased or abbreviated value returns an EMPTY page rather than an\nerror. Omit to apply no state filter.\n\nLocations on the response report `state` as a two-letter code (`PA`); this\nfilter still takes the full name.","in":"query","name":"state","required":false,"schema":{"type":"string"}},{"description":"Top-level category permalink: `local`, `goods` or `travel`. A Groupon extension. Each `category1` value belongs to exactly one of these.","in":"query","name":"category0","required":false,"schema":{"type":"string"}},{"description":"Category permalink one level below `category0`. A Groupon extension. Send it alone, or together with its own `category0`; a pair from different parents returns no products. Values, by parent:\n\n- `local`: `beauty-and-spas`, `health-and-fitness`, `things-to-do`,\n`personal-services`, `food-and-drink`, `automotive`, `home-improvement`,\n`retail`, `gift-cards`.\n- `goods`: `v1-personalized-items`, `sports-and-outdoors`, `electronics`,\n`grocery-and-household`, `for-the-home`, `baby-kids-and-toys`,\n`health-and-beauty`, `entertainment-and-media`, `jewelry-and-watches`,\n`pet-supplies`, `mens-clothing-shoes-and-accessories`,\n`auto-and-home-improvement`.\n- `travel`: `air-inclusive`, `city`, `family-trips`,\n`outdoor-activities-recreation`, `beach-destinations`, `all-inclusive`,\n`hotel-travel`, `unique-lodging`, `cruises`, `waterparks`,\n`spa-and-wellness`.","in":"query","name":"category1","required":false,"schema":{"type":"string"}},{"description":"Category permalink at depth 2. A Groupon extension.","in":"query","name":"category2","required":false,"schema":{"type":"string"}},{"description":"Category permalink at depth 3. A Groupon extension.","in":"query","name":"category3","required":false,"schema":{"type":"string"}},{"description":"Whether to filter on the deal's active flag (Groupon extension). When OMITTED no filter is applied at all and the page carries both active and inactive deals — read each product's `status` to tell them apart.\n\nDistinct from `status` (the deal's lifecycle state on the response) and from\nan option's `available` flag (bookable availability).","in":"query","name":"active","required":false,"schema":{"type":"boolean"}},{"description":"ISO-8601 freshness watermark (Groupon extension). Returns only deals whose price or content changed at or after this instant. Omit to return all deals.\n\nUse the `timestamp` from the final page of your previous walk; it already\nallows for clock skew and for deals updated while that walk was running.\n\nWhen a Groupon-wide promotion has started since this instant, prices can\nchange on deals whose own update time did not move, so the filter is\ndropped for the whole walk and every deal is returned. That decision is\nmade on the first page and carried in the cursor, so a walk is never partly\nincremental. Treat every page as authoritative and upsert what you receive.","in":"query","name":"updatedSince","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsListResponse"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoError"}}},"description":"Error. The body is the error object itself, with HTTP 400. Branch on `error`, not on the status."}},"summary":"List Groupon deals available to you, as OCTO Products."}},"/octo-gateway/v1/register":{"post":{"description":"This is the only endpoint called without `g-api-key`. The response carries your\nregistration and your API key as `token`. The key is returned once, in this\nresponse only: store it server-side before doing anything else. Send it as\n`g-api-key` on every other request, starting with `GET /octo-gateway/v1/partners/me`\nto check it.\n\nWhile self-registration is closed, every call fails with `error: \"SELF_REGISTRATION_CLOSED\"`.\n\nA lost or leaked key, and any change to what you registered, goes through Groupon support.\n\nCalls are rate-limited per client IP and in total, and calls that fail validation count toward the\nlimit, so check your fields before calling. Over the limit the response is HTTP 429 with\n`error: \"RATE_LIMITED\"`; wait for the `retry-after` header before trying again.","operationId":"partnerRegister","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerRegistrationInput"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerRegisterResponse"}}},"description":"Successful response"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoError"}}},"description":"Error. The body is the error object itself, with HTTP 400. Branch on `error`, not on the status."}},"security":[],"summary":"Register as a partner and receive your API key."}},"/octo-gateway/v1/supplier":{"get":{"description":"Identifies the Groupon entity your bookings are made against. Read it once at\nonboarding to confirm your integration is pointed at the right supplier; it\ndoes not change between requests.","operationId":"supplierGet","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierGetResponse"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoError"}}},"description":"Error. The body is the error object itself, with HTTP 400. Branch on `error`, not on the status."}},"summary":"Your supplier record."}},"/octo/v1/carts":{"post":{"deprecated":true,"description":"Deprecated alias of `POST /octo-gateway/v1/carts`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then.","operationId":"cartsCreateLegacyPath","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCartRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Deprecated alias of `POST /octo-gateway/v1/carts`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then."}},"/octo/v1/carts/{cartId}":{"delete":{"deprecated":true,"description":"Deprecated alias of `DELETE /octo-gateway/v1/carts/:cartId`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then.","operationId":"cartsAbandonLegacyPath","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No content. The response has no body."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Deprecated alias of `DELETE /octo-gateway/v1/carts/:cartId`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then."},"get":{"deprecated":true,"description":"Deprecated alias of `GET /octo-gateway/v1/carts/:cartId`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then.","operationId":"cartsGetLegacyPath","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}},{"description":"ISO-3166 alpha-2 country code. Use `US` -- the only market available today.","in":"query","name":"country","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Deprecated alias of `GET /octo-gateway/v1/carts/:cartId`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then."}},"/octo/v1/carts/{cartId}/items":{"post":{"deprecated":true,"description":"Deprecated alias of `POST /octo-gateway/v1/carts/:cartId/items`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then.","operationId":"cartItemsAddLegacyPath","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCartItemsRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Deprecated alias of `POST /octo-gateway/v1/carts/:cartId/items`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then."}},"/octo/v1/carts/{cartId}/items/{itemId}":{"delete":{"deprecated":true,"description":"Deprecated alias of `DELETE /octo-gateway/v1/carts/:cartId/items/:itemId`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then.","operationId":"cartItemsRemoveLegacyPath","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}},{"in":"path","name":"itemId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Deprecated alias of `DELETE /octo-gateway/v1/carts/:cartId/items/:itemId`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then."},"patch":{"deprecated":true,"description":"Deprecated alias of `PATCH /octo-gateway/v1/carts/:cartId/items/:itemId`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then.","operationId":"cartItemsUpdateLegacyPath","parameters":[{"in":"path","name":"cartId","required":true,"schema":{"type":"string"}},{"in":"path","name":"itemId","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCartItemRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoCart"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoErrorEnvelope"}}},"description":"Error. The HTTP status reflects `code`; the endpoint's own error is in `details`."}},"summary":"Deprecated alias of `PATCH /octo-gateway/v1/carts/:cartId/items/:itemId`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then."}},"/octo/v1/partner-bookings/{uuid}":{"get":{"deprecated":true,"description":"Deprecated alias of `GET /octo-gateway/v1/partner-bookings/:uuid`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then.","operationId":"partnerBookingGetLegacyPath","parameters":[{"in":"path","name":"uuid","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnerBookingGetResponse"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoError"}}},"description":"Error. The body is the error object itself, with HTTP 400. Branch on `error`, not on the status."}},"summary":"Deprecated alias of `GET /octo-gateway/v1/partner-bookings/:uuid`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then."}},"/octo/v1/products":{"get":{"deprecated":true,"description":"Deprecated alias of `GET /octo-gateway/v1/products`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then.","operationId":"productsListLegacyPath","parameters":[{"description":"ISO-3166 alpha-2 country code. Use `US` -- the only market available today.\n\nA Groupon extension; required.","in":"query","name":"country","required":true,"schema":{"type":"string"}},{"description":"Products per page. Defaults to 100; **10 is recommended**. The maximum is 1,000 unless your account has a different cap, and a larger value is silently reduced to it rather than rejected. A large page can exceed the request time budget and fail, so walk the catalogue with `limit=10`.\n\nA Groupon extension.","in":"query","name":"limit","required":false,"schema":{"type":"number"}},{"description":"The `nextCursor` from the previous page. Omit on the first page.\n\nTreat the value as opaque and send it back exactly as received, keeping\nevery other query parameter identical across one walk.\n\nA Groupon extension.","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"US state matched against the deal's divisions (Groupon extension).\n\nSend the FULL STATE NAME exactly as stored, e.g. `Pennsylvania`,\n`California`, `New York` — NOT an abbreviation such as `PA`, and not\n`PENNSYLVANIA`. The match is case-SENSITIVE: only surrounding whitespace is\ntrimmed, and the value is otherwise passed through verbatim, so a\ndifferently-cased or abbreviated value returns an EMPTY page rather than an\nerror. Omit to apply no state filter.\n\nLocations on the response report `state` as a two-letter code (`PA`); this\nfilter still takes the full name.","in":"query","name":"state","required":false,"schema":{"type":"string"}},{"description":"Top-level category permalink: `local`, `goods` or `travel`. A Groupon extension. Each `category1` value belongs to exactly one of these.","in":"query","name":"category0","required":false,"schema":{"type":"string"}},{"description":"Category permalink one level below `category0`. A Groupon extension. Send it alone, or together with its own `category0`; a pair from different parents returns no products. Values, by parent:\n\n- `local`: `beauty-and-spas`, `health-and-fitness`, `things-to-do`,\n`personal-services`, `food-and-drink`, `automotive`, `home-improvement`,\n`retail`, `gift-cards`.\n- `goods`: `v1-personalized-items`, `sports-and-outdoors`, `electronics`,\n`grocery-and-household`, `for-the-home`, `baby-kids-and-toys`,\n`health-and-beauty`, `entertainment-and-media`, `jewelry-and-watches`,\n`pet-supplies`, `mens-clothing-shoes-and-accessories`,\n`auto-and-home-improvement`.\n- `travel`: `air-inclusive`, `city`, `family-trips`,\n`outdoor-activities-recreation`, `beach-destinations`, `all-inclusive`,\n`hotel-travel`, `unique-lodging`, `cruises`, `waterparks`,\n`spa-and-wellness`.","in":"query","name":"category1","required":false,"schema":{"type":"string"}},{"description":"Category permalink at depth 2. A Groupon extension.","in":"query","name":"category2","required":false,"schema":{"type":"string"}},{"description":"Category permalink at depth 3. A Groupon extension.","in":"query","name":"category3","required":false,"schema":{"type":"string"}},{"description":"Whether to filter on the deal's active flag (Groupon extension). When OMITTED no filter is applied at all and the page carries both active and inactive deals — read each product's `status` to tell them apart.\n\nDistinct from `status` (the deal's lifecycle state on the response) and from\nan option's `available` flag (bookable availability).","in":"query","name":"active","required":false,"schema":{"type":"boolean"}},{"description":"ISO-8601 freshness watermark (Groupon extension). Returns only deals whose price or content changed at or after this instant. Omit to return all deals.\n\nUse the `timestamp` from the final page of your previous walk; it already\nallows for clock skew and for deals updated while that walk was running.\n\nWhen a Groupon-wide promotion has started since this instant, prices can\nchange on deals whose own update time did not move, so the filter is\ndropped for the whole walk and every deal is returned. That decision is\nmade on the first page and carried in the cursor, so a walk is never partly\nincremental. Treat every page as authoritative and upsert what you receive.","in":"query","name":"updatedSince","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductsListResponse"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoError"}}},"description":"Error. The body is the error object itself, with HTTP 400. Branch on `error`, not on the status."}},"summary":"Deprecated alias of `GET /octo-gateway/v1/products`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then."}},"/octo/v1/supplier":{"get":{"deprecated":true,"description":"Deprecated alias of `GET /octo-gateway/v1/supplier`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then.","operationId":"supplierGetLegacyPath","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierGetResponse"}}},"description":"Successful response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationError"}}},"description":"Missing or invalid API key."},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OctoError"}}},"description":"Error. The body is the error object itself, with HTTP 400. Branch on `error`, not on the status."}},"summary":"Deprecated alias of `GET /octo-gateway/v1/supplier`, kept for integrations built before the rename. Identical request, response and authentication. Removed on 2027-03-31; move to the new path before then."}}},"security":[{"ApiKeyAuth":[]}],"servers":[{"description":"(NA) Production environment","url":"https://api.enc.groupon.com"}]}