{ "openapi": "3.0.3", "info": { "title": "Firmly Cart API v2", "description": "The V2 Cart API introduces multi-shipment support, allowing items to be grouped into separate shipments with different fulfillment types (standard shipping, scheduled delivery, in-store pickup).", "version": "2.0.0", "contact": { "name": "Firmly Support", "url": "https://firmly.work" } }, "servers": [ { "url": "https://api.firmly.work/api/v2", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Cart Management", "description": "Basic cart operations (get, add, update, clear)" }, { "name": "Shipment Configuration", "description": "Fulfillment and shipping setup" }, { "name": "Addon Management", "description": "Addon services and selections" }, { "name": "Checkout", "description": "Customer address and billing information" }, { "name": "Promotions", "description": "Promotional codes and discounts" }, { "name": "Session Management", "description": "Cross-domain cart operations and global preferences" }, { "name": "Orders", "description": "Order persistence and retrieval" } ], "paths": { "/domains/{domain}/cart": { "get": { "tags": ["Cart Management"], "summary": "Get Cart", "description": "Retrieve the current state of a shopping cart with all line items, shipments, pricing, and addon information.", "operationId": "getCart", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "responses": { "200": { "description": "Current cart state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CartNotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/domains/{domain}/cart/line-items": { "post": { "tags": ["Cart Management"], "summary": "Add Line Item", "description": "Add a new product variant to the shopping cart. Creates a cart if one doesn't exist.", "operationId": "addLineItem", "parameters": [ { "$ref": "#/components/parameters/domain" }, { "name": "flush_cart", "in": "query", "description": "Clear cart before adding item", "schema": { "type": "string", "enum": ["true", "false"], "default": "false" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddLineItemRequest" } } } }, "responses": { "200": { "description": "Updated cart with new line item", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ProductNotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/domains/{domain}/cart/line-items/{line_item_id}": { "patch": { "tags": ["Cart Management"], "summary": "Update Line Item", "description": "Update the quantity of a line item in the cart. Set quantity to 0 to remove the item.", "operationId": "updateLineItem", "parameters": [ { "$ref": "#/components/parameters/domain" }, { "name": "line_item_id", "in": "path", "required": true, "description": "Line item identifier", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLineItemRequest" } } } }, "responses": { "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/LineItemNotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/domains/{domain}/cart/clear": { "post": { "tags": ["Cart Management"], "summary": "Clear Cart", "description": "Remove all items from the shopping cart, resetting it to an empty state.", "operationId": "clearCart", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "responses": { "200": { "description": "Empty cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CartNotFound" } } } }, "/domains/{domain}/cart/shipments/fulfillment-type": { "post": { "tags": ["Shipment Configuration"], "summary": "Set Fulfillment Type", "description": "Changes the fulfillment method for a specific shipment. This V2-exclusive endpoint enables switching between standard shipping, scheduled delivery, and in-store pickup options.", "operationId": "setFulfillmentType", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFulfillmentTypeRequest" } } } }, "responses": { "200": { "description": "Updated cart with new fulfillment type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ShipmentNotFound" } } } }, "/domains/{domain}/cart/shipments/shipping-method": { "post": { "tags": ["Shipment Configuration"], "summary": "Set Shipping Method", "description": "Select a shipping method for a specific shipment from available options.", "operationId": "setShippingMethod", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetShippingMethodRequest" } } } }, "responses": { "200": { "description": "Updated cart with selected shipping method", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ShipmentNotFound" } } } }, "/domains/{domain}/cart/shipments/get-availability": { "post": { "tags": ["Shipment Configuration"], "summary": "Get Shipment Availability", "description": "Get available options based on fulfillment type: dates/times for scheduled delivery, locations for pickup, or shipping methods for standard delivery.", "operationId": "getShipmentAvailability", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAvailabilityRequest" } } } }, "responses": { "200": { "description": "Availability information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentAvailabilityResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/ShipmentNotFound" } } } }, "/domains/{domain}/cart/addons": { "post": { "tags": ["Addon Management"], "summary": "Add Addon", "description": "Apply addon services to your cart with flexible scoping options. Supports cart-level, item-level, and group-level addon services with granular selection control.", "operationId": "addAddon", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAddonRequest" } } } }, "responses": { "200": { "description": "Updated cart with addon selections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CartNotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } }, "put": { "tags": ["Addon Management"], "summary": "Update Addons", "description": "Replace all addon selections with a new set.", "operationId": "updateAddons", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAddonRequest" } } } }, "responses": { "200": { "description": "Updated cart with addon selections", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CartNotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/domains/{domain}/cart/addons/{addon_id}": { "delete": { "tags": ["Addon Management"], "summary": "Remove Addon", "description": "Remove a specific addon from the cart by its ID.", "operationId": "removeAddon", "parameters": [ { "$ref": "#/components/parameters/domain" }, { "name": "addon_id", "in": "path", "required": true, "description": "Addon identifier to remove", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Updated cart without the addon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/AddonNotFound" } } } }, "/domains/{domain}/checkout/shipping-info": { "post": { "tags": ["Checkout"], "summary": "Set Shipping Info", "description": "Update customer shipping address information for the cart.", "operationId": "setShippingInfo", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingInfoRequest" } } } }, "responses": { "200": { "description": "Updated cart with shipping information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CartNotFound" } } } }, "/domains/{domain}/checkout/billing-info": { "post": { "tags": ["Checkout"], "summary": "Set Billing Info", "description": "Update customer billing address information for the cart.", "operationId": "setBillingInfo", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingInfoRequest" } } } }, "responses": { "200": { "description": "Updated cart with billing information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CartNotFound" } } } }, "/domains/{domain}/checkout/consents": { "get": { "tags": ["Checkout"], "summary": "Get Consents", "description": "Retrieve available consent options for checkout (e.g., marketing emails, SMS).", "operationId": "getConsents", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "responses": { "200": { "description": "Available consent options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Checkout"], "summary": "Set Consents", "description": "Update customer consent preferences for marketing communications.", "operationId": "setConsents", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetConsentsRequest" } } } }, "responses": { "200": { "description": "Updated cart with consent preferences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/domains/{domain}/cart/promo-codes": { "post": { "tags": ["Promotions"], "summary": "Add Promo Codes", "description": "Apply one or more promotional codes to the cart for discounts.", "operationId": "addPromoCodes", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPromoCodesRequest" } } } }, "responses": { "200": { "description": "Updated cart with promo codes applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CartNotFound" }, "422": { "$ref": "#/components/responses/InvalidPromoCode" } } } }, "/domains/{domain}/cart/promo-codes/clear": { "post": { "tags": ["Promotions"], "summary": "Clear Promo Codes", "description": "Remove all promotional codes from the cart.", "operationId": "clearPromoCodes", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "responses": { "200": { "description": "Updated cart without promo codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShoppingCartV2" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CartNotFound" } } } }, "/carts/session/active": { "get": { "tags": ["Session Management"], "summary": "Get Active Carts", "description": "Retrieve all active shopping carts across different domains for the current session.", "operationId": "getActiveCarts", "responses": { "200": { "description": "List of active carts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveCartsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/carts/session/domains": { "get": { "tags": ["Session Management"], "summary": "Get Active Domains", "description": "Retrieve all domains that have active carts in the current session.", "operationId": "getActiveDomains", "responses": { "200": { "description": "List of active domains", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveDomainsResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/carts/session/postal-code": { "get": { "tags": ["Session Management"], "summary": "Get Postal Code", "description": "Retrieve the postal code stored in the current session.", "operationId": "getPostalCode", "responses": { "200": { "description": "Current postal code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostalCodeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Session Management"], "summary": "Set Postal Code", "description": "Update the postal code for the current session, affecting tax and shipping calculations.", "operationId": "setPostalCode", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPostalCodeRequest" } } } }, "responses": { "200": { "description": "Postal code updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostalCodeResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/carts/session/transfer": { "post": { "tags": ["Session Management"], "summary": "Session Transfer", "description": "Transfer cart session data between devices or sessions.", "operationId": "sessionTransfer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTransferRequest" } } } }, "responses": { "200": { "description": "Session transferred successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionTransferResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/domains/{domain}/orders": { "post": { "tags": ["Orders"], "summary": "Persist Order", "description": "Save the current cart as an order after successful payment.", "operationId": "persistOrder", "parameters": [ { "$ref": "#/components/parameters/domain" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PersistOrderRequest" } } } }, "responses": { "200": { "description": "Order saved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/CartNotFound" } } } }, "/domains/{domain}/orders/by-device/{device_id}": { "get": { "tags": ["Orders"], "summary": "Get Orders by Device ID", "description": "Retrieve order history for a specific device.", "operationId": "getOrdersByDeviceId", "parameters": [ { "$ref": "#/components/parameters/domain" }, { "name": "device_id", "in": "path", "required": true, "description": "Device identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of orders for device", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrdersListResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Device authentication token in x-firmly-authorization header" } }, "parameters": { "domain": { "name": "domain", "in": "path", "required": true, "description": "Domain of the current merchant website (e.g. example.com)", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "ErrorBadRequest", "message": "Invalid request parameters" } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "ErrorUnauthorized", "message": "Invalid or missing authentication token" } } } }, "CartNotFound": { "description": "Cart Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "ErrorCartNotFound", "message": "Cart does not exist" } } } }, "ProductNotFound": { "description": "Product Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "ErrorProductNotFound", "message": "Product variant not found" } } } }, "LineItemNotFound": { "description": "Line Item Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "ErrorLineItemNotFound", "message": "Line item not found in cart" } } } }, "ShipmentNotFound": { "description": "Shipment Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "ErrorShipmentNotFound", "message": "Shipment not found", "details": { "shipment_id": "missing-shipment-id" } } } } }, "AddonNotFound": { "description": "Addon Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "ErrorAddonNotFound", "message": "Addon not found in cart" } } } }, "UnprocessableEntity": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "ErrorUnprocessableEntity", "message": "The given payload has unprocessable data" } } } }, "InvalidPromoCode": { "description": "Invalid Promo Code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": "ErrorInvalidPromoCode", "message": "Promotional code is invalid or expired" } } } } }, "schemas": { "ShoppingCartV2": { "type": "object", "required": ["cart_id", "platform_id", "shop_id", "line_items", "shipments", "sub_total", "total", "schema_version"], "properties": { "cart_id": { "type": "string", "description": "Unique cart identifier (UUID)" }, "platform_id": { "type": "string", "description": "Platform identifier" }, "shop_id": { "type": "string", "description": "Shop identifier" }, "line_items": { "type": "array", "description": "Array of cart items", "items": { "$ref": "#/components/schemas/LineItem" } }, "shipments": { "type": "array", "description": "Multi-shipment array", "items": { "$ref": "#/components/schemas/Shipment" } }, "addons": { "$ref": "#/components/schemas/AddonsContainer" }, "sub_total": { "$ref": "#/components/schemas/Amount" }, "cart_discount": { "$ref": "#/components/schemas/Amount" }, "shipping_total": { "$ref": "#/components/schemas/Amount" }, "addon_total": { "$ref": "#/components/schemas/Amount" }, "tax_total": { "$ref": "#/components/schemas/Amount" }, "total": { "$ref": "#/components/schemas/Amount" }, "shipping_info": { "$ref": "#/components/schemas/ShippingInfo" }, "billing_info": { "$ref": "#/components/schemas/BillingInfo" }, "coupons": { "type": "array", "description": "Applied promo codes", "items": { "type": "string" } }, "schema_version": { "type": "string", "description": "Always '2.0' for v2 API", "example": "2.0" } } }, "LineItem": { "type": "object", "required": ["line_item_id", "variant_id", "quantity", "price", "total"], "properties": { "line_item_id": { "type": "string", "description": "Unique item identifier" }, "variant_id": { "type": "string", "description": "Product variant identifier" }, "sku": { "type": "string", "description": "Stock keeping unit" }, "description": { "type": "string", "description": "Product description" }, "quantity": { "type": "integer", "minimum": 1, "description": "Item quantity" }, "price": { "$ref": "#/components/schemas/Amount" }, "total": { "$ref": "#/components/schemas/Amount" }, "product": { "$ref": "#/components/schemas/Product" }, "variant": { "$ref": "#/components/schemas/Variant" } } }, "Shipment": { "type": "object", "required": ["shipment_id", "fulfillment_type", "line_item_ids"], "properties": { "shipment_id": { "type": "string", "description": "Unique shipment identifier (UUID)" }, "fulfillment_type": { "$ref": "#/components/schemas/FulfillmentType" }, "fulfillment_type_options": { "type": "array", "description": "Available fulfillment options", "items": { "$ref": "#/components/schemas/FulfillmentType" } }, "line_item_ids": { "type": "array", "description": "Items in this shipment", "items": { "type": "string" } }, "shipping_method_options": { "type": "array", "description": "Available shipping methods", "items": { "$ref": "#/components/schemas/ShippingMethod" } }, "shipping_method": { "$ref": "#/components/schemas/ShippingMethod" }, "selected_location": { "$ref": "#/components/schemas/PickupLocation" }, "selected_date": { "type": "string", "format": "date", "description": "Selected delivery/pickup date (YYYY-MM-DD)" }, "selected_time_slot": { "$ref": "#/components/schemas/TimeSlot" }, "notes": { "type": "string", "description": "Delivery instructions" } } }, "FulfillmentType": { "type": "object", "required": ["id", "name", "description"], "properties": { "id": { "type": "string", "enum": ["SHIP_TO_ADDRESS", "SCHEDULED_DELIVERY", "PICKUP_IN_STORE"], "description": "Fulfillment type identifier" }, "name": { "type": "string", "description": "Human-readable name" }, "description": { "type": "string", "description": "Detailed description" } } }, "ShippingMethod": { "type": "object", "required": ["id", "description", "price"], "properties": { "id": { "type": "string", "description": "Unique method identifier" }, "description": { "type": "string", "description": "Human-readable description" }, "price": { "$ref": "#/components/schemas/Amount" }, "estimated_delivery": { "type": "string", "description": "Delivery time estimate" } } }, "AddonsContainer": { "type": "object", "required": ["offers", "selections"], "properties": { "offers": { "type": "array", "description": "Available addon services", "items": { "$ref": "#/components/schemas/AddonOffer" } }, "selections": { "type": "array", "description": "Currently applied addons", "items": { "$ref": "#/components/schemas/AddonSelection" } } } }, "AddonOffer": { "type": "object", "required": ["addon_id", "display", "scope", "price"], "properties": { "addon_id": { "type": "string", "description": "Unique addon identifier" }, "display": { "$ref": "#/components/schemas/AddonDisplay" }, "scope": { "type": "string", "enum": ["CART", "ITEM", "GROUP"], "description": "Where the service applies" }, "coverage_mode": { "type": "string", "enum": ["PER_ITEM", "PREDEFINED_GROUP", "FREE_GROUPING"], "description": "How items are covered" }, "eligible_line_item_ids": { "type": "array", "description": "Items eligible for this addon", "items": { "type": "string" } }, "price": { "$ref": "#/components/schemas/Amount" }, "line_item_pricing": { "type": "object", "description": "Different pricing per item", "additionalProperties": { "type": "object", "properties": { "price": { "$ref": "#/components/schemas/Amount" } } } }, "constraints": { "$ref": "#/components/schemas/AddonConstraints" }, "child_offers": { "type": "array", "description": "Hierarchical sub-options", "items": { "$ref": "#/components/schemas/AddonOffer" } } } }, "AddonSelection": { "type": "object", "required": ["addon_id"], "properties": { "addon_id": { "type": "string", "description": "References AddonOffer.addon_id" }, "selected_line_item_ids": { "type": "array", "description": "Items this addon applies to", "items": { "type": "string" } }, "selected_child_ids": { "type": "array", "description": "Selected child offers", "items": { "type": "string" } }, "price": { "$ref": "#/components/schemas/Amount" }, "line_item_pricing": { "type": "object", "description": "Per-item pricing breakdown", "additionalProperties": { "type": "object", "properties": { "price": { "$ref": "#/components/schemas/Amount" } } } }, "metadata": { "type": "object", "description": "Addon-specific attributes" } } }, "AddonDisplay": { "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Human-readable name" }, "description": { "type": "string", "description": "Short description" }, "long_description": { "type": "string", "description": "Detailed description" }, "image_url": { "type": "string", "format": "uri", "description": "Addon image" }, "links": { "type": "array", "description": "Related links", "items": { "type": "string", "format": "uri" } } } }, "AddonConstraints": { "type": "object", "properties": { "exclusive_group_id": { "type": "string", "description": "Mutual exclusivity group" }, "requires_addon_ids": { "type": "array", "description": "Required prerequisite addons", "items": { "type": "string" } } } }, "Amount": { "type": "object", "required": ["value", "currency"], "properties": { "value": { "type": "number", "description": "Decimal value (e.g., 99.99)" }, "currency": { "type": "string", "description": "Currency code (e.g., 'USD')" }, "number": { "type": "integer", "description": "Value in smallest unit (e.g., cents: 9999)" }, "symbol": { "type": "string", "description": "Currency symbol (e.g., '$')" } } }, "ShippingInfo": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" }, "zip": { "type": "string" }, "phone": { "type": "string" } } }, "BillingInfo": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" }, "zip": { "type": "string" }, "phone": { "type": "string" } } }, "TimeSlot": { "type": "object", "required": ["slot_id", "start_time", "end_time", "description", "available"], "properties": { "slot_id": { "type": "string", "description": "Unique slot identifier" }, "start_time": { "$ref": "#/components/schemas/Time" }, "end_time": { "$ref": "#/components/schemas/Time" }, "description": { "type": "string", "description": "Human-readable description" }, "available": { "type": "boolean", "description": "Whether slot is available" }, "price": { "$ref": "#/components/schemas/Amount" } } }, "Time": { "type": "object", "required": ["utc", "local", "local_timezone"], "properties": { "utc": { "type": "string", "format": "date-time", "description": "UTC timestamp" }, "local": { "type": "string", "format": "date-time", "description": "Local time" }, "local_timezone": { "type": "string", "description": "Timezone identifier" } } }, "PickupLocation": { "type": "object", "required": ["location_id", "name", "address", "available"], "properties": { "location_id": { "type": "string", "description": "Unique location identifier" }, "name": { "type": "string", "description": "Store name" }, "address": { "$ref": "#/components/schemas/Address" }, "phone": { "type": "string", "description": "Store phone number" }, "hours": { "$ref": "#/components/schemas/StoreHours" }, "available": { "type": "boolean", "description": "Whether pickup is available" } } }, "Address": { "type": "object", "properties": { "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "state_or_province": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, "StoreHours": { "type": "object", "description": "Store operating hours" }, "Product": { "type": "object", "description": "Product information" }, "Variant": { "type": "object", "description": "Product variant information" }, "AddLineItemRequest": { "type": "object", "required": ["add_to_cart_ref", "quantity"], "properties": { "add_to_cart_ref": { "type": "object", "required": ["variant_id"], "properties": { "variant_id": { "type": "string", "description": "Product variant identifier" }, "product_id": { "type": "string", "description": "Product identifier" }, "variant_handles": { "type": "array", "description": "Variant handle identifiers", "items": { "type": "string" } } } }, "quantity": { "type": "integer", "minimum": 1, "description": "Quantity to add" } } }, "UpdateLineItemRequest": { "type": "object", "required": ["quantity"], "properties": { "quantity": { "type": "integer", "minimum": 0, "description": "New quantity (0 to remove)" } } }, "SetFulfillmentTypeRequest": { "type": "object", "required": ["shipment_id", "fulfillment_type"], "properties": { "shipment_id": { "type": "string", "description": "Target shipment identifier" }, "fulfillment_type": { "type": "string", "enum": ["SHIP_TO_ADDRESS", "SCHEDULED_DELIVERY", "PICKUP_IN_STORE"], "description": "New fulfillment method" }, "location_id": { "type": "string", "description": "Required for PICKUP_IN_STORE" } } }, "SetShippingMethodRequest": { "type": "object", "required": ["shipment_id", "shipping_method_id"], "properties": { "shipment_id": { "type": "string", "description": "Target shipment identifier" }, "shipping_method_id": { "type": "string", "description": "Selected shipping method ID" } } }, "GetAvailabilityRequest": { "type": "object", "required": ["shipment_id"], "properties": { "shipment_id": { "type": "string", "description": "Target shipment identifier" } } }, "ShipmentAvailabilityResponse": { "type": "object", "properties": { "available_dates": { "type": "array", "description": "Available delivery/pickup dates", "items": { "type": "string", "format": "date" } }, "time_slots": { "type": "object", "description": "Time slots by date", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/TimeSlot" } } }, "pickup_locations": { "type": "array", "description": "Available pickup locations", "items": { "$ref": "#/components/schemas/PickupLocation" } }, "shipping_methods": { "type": "array", "description": "Available shipping methods", "items": { "$ref": "#/components/schemas/ShippingMethod" } } } }, "AddAddonRequest": { "type": "object", "required": ["selections"], "properties": { "selections": { "type": "array", "items": { "type": "object", "required": ["addon_id"], "properties": { "addon_id": { "type": "string", "description": "Addon identifier" }, "selected_line_item_ids": { "type": "array", "description": "Items to apply addon to", "items": { "type": "string" } }, "selected_child_ids": { "type": "array", "description": "Child addon selections", "items": { "type": "string" } } } } } } }, "ShippingInfoRequest": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" }, "zip": { "type": "string" }, "phone": { "type": "string" } } }, "BillingInfoRequest": { "type": "object", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "company": { "type": "string" }, "address1": { "type": "string" }, "address2": { "type": "string" }, "city": { "type": "string" }, "province": { "type": "string" }, "country": { "type": "string" }, "zip": { "type": "string" }, "phone": { "type": "string" } } }, "ConsentsResponse": { "type": "object", "properties": { "available_consents": { "type": "array", "items": { "$ref": "#/components/schemas/ConsentOption" } } } }, "ConsentOption": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "required": { "type": "boolean" }, "default_value": { "type": "boolean" } } }, "SetConsentsRequest": { "type": "object", "properties": { "consents": { "type": "object", "additionalProperties": { "type": "boolean" } } } }, "AddPromoCodesRequest": { "type": "object", "required": ["codes"], "properties": { "codes": { "type": "array", "description": "Promotional codes to apply", "items": { "type": "string" } } } }, "ActiveCartsResponse": { "type": "object", "properties": { "carts": { "type": "array", "items": { "$ref": "#/components/schemas/CartSummary" } } } }, "CartSummary": { "type": "object", "properties": { "domain": { "type": "string" }, "cart_id": { "type": "string" }, "item_count": { "type": "integer" }, "total": { "$ref": "#/components/schemas/Amount" } } }, "ActiveDomainsResponse": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" } } } }, "PostalCodeResponse": { "type": "object", "properties": { "postal_code": { "type": "string" } } }, "SetPostalCodeRequest": { "type": "object", "required": ["postal_code"], "properties": { "postal_code": { "type": "string" } } }, "SessionTransferRequest": { "type": "object", "properties": { "source_device_id": { "type": "string" }, "target_device_id": { "type": "string" } } }, "SessionTransferResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "PersistOrderRequest": { "type": "object", "properties": { "payment_confirmation": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "payment_method": { "type": "string" } } } } }, "OrderResponse": { "type": "object", "properties": { "order_id": { "type": "string" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "thank_you_page": { "type": "string", "format": "uri" } } }, "OrdersListResponse": { "type": "object", "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } } } }, "Order": { "type": "object", "properties": { "order_id": { "type": "string" }, "order_number": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "total": { "$ref": "#/components/schemas/Amount" }, "status": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": ["error", "message"], "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Human-readable error message" }, "details": { "type": "object", "description": "Additional error details" } } } } } }