{"openapi":"3.1.0","info":{"title":"Mobiari Storefront API","description":"The shopper-facing API storefront themes call: catalog, cart, checkout and customer accounts. Most endpoints are public and addressed by store slug.","license":{"name":""},"version":"1.0.0"},"servers":[{"url":"https://api.mobiari.com/v1","description":"Production"},{"url":"http://localhost:4000/v1","description":"Local development"}],"paths":{"/storefront-api/{store_slug}/api/cart":{"get":{"tags":["Cart"],"summary":"Get the shopper's cart","description":"The open cart named by `cart_id`, the `X-Cart-Id` header or the\n`cart_id` cookie. When none of them names an open cart in the requested\ncurrency, a new empty cart is created. The response carries the cart id\nin `X-Cart-Id` and sets the `cart_id` cookie.","operationId":"getStorefrontCart","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"cart_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"currency","in":"query","description":"ISO 4217 code; defaults to the store's currency. A cart in another\ncurrency is not reused.","required":false,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCart"}}}},"400":{"description":"Invalid currency code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/cart/contact":{"post":{"tags":["Cart"],"summary":"Save the checkout contact details","description":"Stores the shopper's name, e-mail, phone, address and document on the\ncart, so an abandoned cart can be recovered and checkout pre-filled.\nCreates the cart when the shopper has none. The details are untrusted:\nthey are not matched against the store's customers here, and the answer\nis the same whether or not they belong to one.","operationId":"saveStorefrontCartContact","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartContactUpsertRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartContactSaved"}}}},"400":{"description":"Invalid currency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Cart"],"summary":"Save the checkout contact details (PATCH)","description":"Same as `POST .../api/cart/contact`.","operationId":"updateStorefrontCartContact","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartContactUpsertRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartContactSaved"}}}},"400":{"description":"Invalid currency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/cart/freight/quote":{"post":{"tags":["Cart"],"summary":"Quote freight for the cart","description":"Asks every freight module of the store (carriers and local delivery\nzones) for options to the CEP and saves the quote on the cart; pick one\nwith `POST .../api/cart/freight/select`.","operationId":"quoteStorefrontCartFreight","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartFreightQuoteApiRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontFreightQuote"}}}},"400":{"description":"No cart named, or an invalid CEP or cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store, or the cart is not this store's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The store has no freight configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The carriers did not answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/cart/freight/select":{"post":{"tags":["Cart"],"summary":"Select a freight option","description":"Applies one option of the cart's last quote to the cart; its price\nbecomes the cart's shipping. An expired quote must be requoted.","operationId":"selectStorefrontCartFreight","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartFreightSelectApiRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontFreightSelection"}}}},"400":{"description":"No cart named, no quote, an unknown option or an expired quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store, or the cart is not this store's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/cart/items":{"post":{"tags":["Cart"],"summary":"Set a cart line","description":"Sets the variant's quantity in the cart (adding the line if needed); 0\nremoves it. Stock is reserved for the cart and any selected freight is\ncleared, since the parcel changed. Creates the cart when the shopper has\nnone. Answers with the whole cart.","operationId":"setStorefrontCartItem","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartItemUpsertRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCart"}}}},"400":{"description":"Invalid variant id or currency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store or variant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`error: insufficient_stock`: not enough stock for the quantity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Cart"],"summary":"Set a cart line (PATCH)","description":"Same as `POST .../api/cart/items`.","operationId":"updateStorefrontCartItem","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartItemUpsertRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCart"}}}},"400":{"description":"Invalid variant id or currency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store or variant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`error: insufficient_stock`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/cart/items/{variant_id}":{"delete":{"tags":["Cart"],"summary":"Remove a cart line","description":"Releases the line's stock reservation and clears any selected freight.\nAnswers with the whole cart.","operationId":"removeStorefrontCartItem","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"variant_id","in":"path","description":"Variant id","required":true,"schema":{"type":"string"}},{"name":"cart_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"currency","in":"query","description":"ISO 4217 code; defaults to the store's currency. A cart in another\ncurrency is not reused.","required":false,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCart"}}}},"400":{"description":"No cart named, or an invalid variant id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store, or the cart is not this store's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/cart/pickup":{"post":{"tags":["Cart"],"summary":"Choose pickup or shipping","description":"With a `location_id`, the cart switches to pickup at that store location:\nfreight is cleared and the location's pickup fee becomes the shipping.\nWith `fulfillment_method: \"shipping\"`, the cart goes back to shipping and\nneeds a freight option again.","operationId":"setStorefrontCartPickup","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartPickupRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPickupSelection"}}}},"400":{"description":"No cart named, no `location_id` for pickup, or the location does not offer pickup","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store or location, or the cart is not this store's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/categories/{category_slug}/products":{"get":{"tags":["Catalog"],"summary":"List a category's products","operationId":"listStorefrontCategoryProducts","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"category_slug","in":"path","description":"Category slug","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 100 (out-of-range values are clamped). Defaults to 24.","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"offset","in":"query","description":"Products to skip. Defaults to 0.","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"search","in":"query","description":"Free-text search within the category.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontProductList"}}}},"404":{"description":"No such store, or no active category with this slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/checkout":{"post":{"tags":["Checkout"],"summary":"Confirm a paid checkout","description":"Turns the cart into an order (if it is not one already) and answers with\nit once a payment for it is approved. Payment happens through\n`POST .../api/payments/intents`, which also creates the order; this call\nis how the theme confirms the outcome.","operationId":"checkoutStorefrontCart","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCheckoutApiRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCheckoutResult"}}}},"400":{"description":"No cart named, or the cart is empty","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store, or the cart is not this store's","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Not enough stock for a line","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`error: payment_required`: no approved payment yet (`details` has `order_id` and `cart_id`), or freight not selected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/freight/simulate":{"post":{"tags":["Cart"],"summary":"Simulate freight for products","description":"Quotes freight for a set of variants without touching a cart, for the\nproduct page's \"calculate shipping\" box. Nothing is saved.","operationId":"simulateStorefrontFreight","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontFreightSimulationRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontFreightSimulation"}}}},"400":{"description":"No item with a positive quantity, an invalid variant id or CEP","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store or variant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"The store has no freight configured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The carriers did not answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/locations":{"get":{"tags":["Locations"],"summary":"List store locations","description":"Active locations shown in the store locator, by position. A plain array.","operationId":"listStorefrontLocations","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontLocation"}}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/payments/config":{"get":{"tags":["Checkout"],"summary":"Get the payment configuration","description":"The store's Mercado Pago public key, for the card form.","operationId":"getStorefrontPaymentConfig","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPaymentConfig"}}}},"404":{"description":"No such store, or no Mercado Pago connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/payments/installments":{"get":{"tags":["Checkout"],"summary":"Get card installment plans","description":"The installment plans the card's issuer really offers for the amount,\nwith the per-installment value and whether it is interest-free. Call it\nonce the shopper has typed the card's first 6 digits, so the picker\nshows what will actually be charged (an issuer without an interest-free\nplan for the amount would otherwise apply its default interest).","operationId":"getStorefrontInstallments","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"bin","in":"query","description":"The card number's first 6 digits (more are ignored).","required":true,"schema":{"type":"string"}},{"name":"amount_cents","in":"query","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontInstallments"}}}},"400":{"description":"`error: invalid_bin_or_amount`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store, or no Mercado Pago connected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Mercado Pago did not answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/payments/intents":{"post":{"tags":["Checkout"],"summary":"Pay for the cart","description":"Turns the cart into an order (once; later calls reuse it) and starts a\npayment with the store's gateway: a PIX charge (answered with the QR code\nin `next_action`) or a card payment with a Mercado Pago card token. An\norder already paid answers its approved payment instead of charging\nagain. A card approved on the spot marks the order paid.","operationId":"createStorefrontPaymentIntent","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCreateIntentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPaymentIntent"}}}},"400":{"description":"No cart, an empty cart (`cart_empty`, `cart_not_found`), a missing card token or payer data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store or cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`currency_mismatch`, or `insufficient_stock` for a line","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"`freight_selection_required`, or the gateway refused the payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/payments/intents/{intent_id}":{"get":{"tags":["Checkout"],"summary":"Get a payment attempt","description":"Poll this while a PIX charge is pending: `status` turns `approved` once\npaid. When the request names a cart, the intent must belong to it.","operationId":"getStorefrontPaymentIntent","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"intent_id","in":"path","description":"Payment intent id","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPaymentIntent"}}}},"400":{"description":"Invalid intent id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store or intent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/pickup-locations":{"get":{"tags":["Locations"],"summary":"List pickup locations","description":"Active locations that offer pickup, by position; the cart's pickup\npicker. A plain array (a store has a handful).","operationId":"listStorefrontPickupLocations","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontLocation"}}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/products":{"get":{"tags":["Catalog"],"summary":"List products","description":"Active products visible on the web channel, newest first (by relevance\nwhen `search` is sent).","operationId":"listStorefrontProducts","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 100 (out-of-range values are clamped). Defaults to 24.","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"offset","in":"query","description":"Products to skip. Defaults to 0.","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"search","in":"query","description":"Free-text search over title, description and slug (typo tolerant).","required":false,"schema":{"type":"string"}},{"name":"category_slug","in":"query","description":"Only products in this category.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontProductList"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/products/search":{"get":{"tags":["Catalog"],"summary":"Search products","description":"The product listing with the search text in `q`, ordered by relevance\n(full-text rank plus title similarity, so typos still match).","operationId":"searchStorefrontProducts","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","description":"Search text. Without it, every product is listed.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, 1 to 100 (out-of-range values are clamped). Defaults to 24.","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"offset","in":"query","description":"Products to skip. Defaults to 0.","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"category_slug","in":"query","description":"Only products in this category.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontProductList"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/products/{product_ref}":{"get":{"tags":["Catalog"],"summary":"Get a product","description":"By slug or id. Variants, images (product-level and per variant) and\ncategories come with it.","operationId":"getStorefrontProduct","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"product_ref","in":"path","description":"Product slug or id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontProductDetail"}}}},"404":{"description":"No such store, or no active product visible on the web channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/products/{product_ref}/reviews":{"get":{"tags":["Engagement"],"summary":"List a product's reviews","description":"Approved reviews, newest first, with the rating summary. The product is\naddressed by slug or id.","operationId":"listStorefrontProductReviews","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"product_ref","in":"path","description":"Product slug or id","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"1 to 100; defaults to 20.","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontReviews"}}}},"404":{"description":"No such store or product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Engagement"],"summary":"Submit a product review","description":"Stored as `pending` when the store moderates reviews, `approved`\notherwise. Marked as a verified purchase when the e-mail bought the\nproduct in this store.","operationId":"submitStorefrontProductReview","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"product_ref","in":"path","description":"Product slug or id","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewSubmitRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Review"}}}},"400":{"description":"Invalid author, e-mail, body or rating","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Reviews are disabled for the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store or product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/api/products/{product_ref}/subscribe":{"post":{"tags":["Engagement"],"summary":"Subscribe to a product","description":"\"Let me know\": the shopper gets an e-mail when the product is back in\nstock or its price drops (through the store's journey for\n`inventory.back_in_stock` / `products.price_dropped`). Creates the contact\nif the e-mail is new, with marketing consent only when\n`marketing_opt_in` is true. Signing up again reactivates the\nsubscription.","operationId":"subscribeToProduct","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"product_ref","in":"path","description":"Product id or slug","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSubscribeRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductSubscribeResponse"}}}},"400":{"description":"Unreadable body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store or product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Not an e-mail address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{}]}},"/storefront-api/{store_slug}/cart/add":{"post":{"tags":["Cart"],"summary":"Add to cart (theme form)","description":"The endpoint behind Liquid themes' `routes.cart_add_url`: adds the\nquantity (default 1) to the variant's line, creating the cart and setting\nthe `cart_id` cookie on the first add. Copies the visitor's first-touch\nattribution cookie onto a new cart.","operationId":"themeCartAdd","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartAddRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartAck"}}}},"400":{"description":"Invalid variant id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store or variant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`error: insufficient_stock`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/cart/change":{"post":{"tags":["Cart"],"summary":"Change a line (theme form)","description":"The endpoint behind `routes.cart_change_url`: sets the variant's\nquantity, removing the line at 0. Answers `ok` without doing anything\nwhen there is no cart. Clears any selected freight.","operationId":"themeCartChange","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartChangeRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartAck"}}}},"400":{"description":"Invalid variant id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`error: insufficient_stock`; `details` has `available`, `max_shippable` and `limiting_sku`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/cart/clear":{"post":{"tags":["Cart"],"summary":"Empty the cart (theme form)","description":"The endpoint behind `routes.cart_clear_url`: removes every line and\nreleases the cart's stock reservations.","operationId":"themeCartClear","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartAck"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/cart/freight/quote":{"post":{"tags":["Cart"],"summary":"Quote freight (theme form)","description":"The endpoint behind `routes.cart_freight_quote_url`; same as\n`POST .../api/cart/freight/quote`, for the cart in the cookie. Answers\n`ok` with no quote when there is no cart.","operationId":"themeCartFreightQuote","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartFreightQuoteRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontFreightQuote"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The freight could not be quoted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/cart/freight/select":{"post":{"tags":["Cart"],"summary":"Select freight (theme form)","description":"The endpoint behind `routes.cart_freight_select_url`; same as\n`POST .../api/cart/freight/select`, for the cart in the cookie.","operationId":"themeCartFreightSelect","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"x-cart-id","in":"header","description":"The shopper's cart; the `cart_id` cookie or body field works too","required":false,"schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartFreightSelectRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartAck"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"The option could not be selected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/customers/login":{"post":{"tags":["Account"],"summary":"Sign a customer in","description":"Exchanges e-mail and password for a customer session token.","operationId":"loginStorefrontCustomer","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCustomerLoginRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCustomerSession"}}}},"400":{"description":"Wrong e-mail or password (also for accounts without a password)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many attempts from this address or for this e-mail","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/customers/me":{"get":{"tags":["Account"],"summary":"Get the signed-in customer","operationId":"getStorefrontCustomer","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCustomerProfile"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"customer_auth":[]}]}},"/storefront-api/{store_slug}/customers/me/orders":{"get":{"tags":["Account"],"summary":"List the signed-in customer's orders","description":"The 100 most recent orders, newest first, as a plain array.","operationId":"listStorefrontCustomerOrders","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCustomerOrder"}}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"customer_auth":[]}]}},"/storefront-api/{store_slug}/customers/register":{"post":{"tags":["Account"],"summary":"Create a customer account","description":"Starts a registration: e-mails the shopper a link, valid 15 minutes,\nthat finishes it (`POST .../customers/verify` with the token and a\npassword). Nothing is signed in and no password is stored until then, so\nnobody can take over an e-mail they do not control; a customer the store\nalready knows from an order or import (no password yet) is adopted at\nthat point, keeping its order history. The answer is the same whether or\nnot the e-mail already has an account.","operationId":"registerStorefrontCustomer","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCustomerRegisterRequest"}}},"required":true},"responses":{"202":{"description":"Verification e-mail sent (if the address can register)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontRegistrationPending"}}}},"400":{"description":"Invalid e-mail, or a password under 8 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many attempts from this address or for this e-mail","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront-api/{store_slug}/customers/verify":{"post":{"tags":["Account"],"summary":"Finish a customer registration","description":"Sets the password with the token from the verification e-mail and signs\nthe customer in. The token is single use and expires 15 minutes after it\nwas sent.","operationId":"verifyStorefrontCustomer","parameters":[{"name":"store_slug","in":"path","description":"Store slug","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCustomerVerifyRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCustomerSession"}}}},"400":{"description":"`invalid_verification_token`: invalid, expired or already used link; or a password under 8 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No such store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: too many verification attempts","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/storefront/orders":{"post":{"tags":["Channel API"],"summary":"Create an order","description":"Records a pending order on the sales channel from the external\nstorefront's cart. Totals are computed from the prices the request\nsends (`products[].price`, `shipping.price`, `discount` as a fraction\nof the subtotal), not from the catalog; the customer is found by e-mail\nor created. No stock is reserved and no payment is taken. Lines whose\nproduct or variant is not an active one of this store are skipped.","operationId":"createChannelOrder","parameters":[{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelOrderRequest"}}},"required":true},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelOrderCreated"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"channel_key":[]}]}},"/storefront/products":{"get":{"tags":["Channel API"],"summary":"List the channel's products","description":"Active products published to the sales channel (or to every channel),\nnewest first, paged by `page`/`limit`. Prices are decimals in BRL.","operationId":"listChannelProducts","parameters":[{"name":"search","in":"query","description":"Title or slug contains this text.","required":false,"schema":{"type":"string"}},{"name":"category","in":"query","description":"Only products in the collection with this slug.","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Page size, up to 100. Defaults to 12.","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"page","in":"query","description":"1-based page number. Defaults to 1.","required":false,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelProductList"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"channel_key":[]}]}},"/storefront/products/{slug}":{"get":{"tags":["Channel API"],"summary":"Get one of the channel's products","operationId":"getChannelProduct","parameters":[{"name":"slug","in":"path","description":"Product slug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelProduct"}}}},"401":{"description":"`unauthorized`: missing, expired or revoked credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`forbidden` / `missing_permission`: the caller lacks the permission this operation needs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"No active product with this slug on the channel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"channel_key":[]}]}},"/widget/{key}/bootstrap":{"get":{"tags":["Engagement"],"summary":"Get the chat widget settings","description":"Everything the chat widget needs to render before a conversation\nexists. Public; the channel's allowed origins apply.","operationId":"getWidgetBootstrap","parameters":[{"name":"key","in":"path","description":"The chat channel's public key (`data-key` of the embed script)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetBootstrap"}}}},"403":{"description":"`origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found`: no enabled chat channel with this key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/widget/{key}/conversations":{"post":{"tags":["Engagement"],"summary":"Start a chat","description":"Opens a conversation on the store's chat channel and returns the token\nthat proves ownership. At most 10 per minute per client address.","operationId":"startWidgetConversation","parameters":[{"name":"key","in":"path","description":"The chat channel's public key (`data-key` of the embed script)","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetStartRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetStartResponse"}}}},"403":{"description":"`origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`slow_down` (`error`): too many new chats from this address","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/widget/{key}/conversations/{conversation_id}":{"get":{"tags":["Engagement"],"summary":"Get the chat","operationId":"getWidgetConversation","parameters":[{"name":"key","in":"path","description":"The chat channel's public key (`data-key` of the embed script)","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"query","description":"The token `POST /widget/{key}/conversations` returned. Prefer the\n`X-Visitor-Token` header; the query parameter is for clients that\ncannot set headers.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetConversation"}}}},"401":{"description":"`bad_token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"tags":["Engagement"],"summary":"Update the shopper's contact details","description":"Fields left out are kept. A matching customer of the store is linked.","operationId":"updateWidgetContact","parameters":[{"name":"key","in":"path","description":"The chat channel's public key (`data-key` of the embed script)","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"query","description":"The token `POST /widget/{key}/conversations` returned. Prefer the\n`X-Visitor-Token` header; the query parameter is for clients that\ncannot set headers.","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetContactRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetConversation"}}}},"401":{"description":"`bad_token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/widget/{key}/conversations/{conversation_id}/cart":{"get":{"tags":["Engagement"],"summary":"Get the chat's cart","description":"The cart the team or the bot assembled in this chat, with its payment\nlink. Authenticated with the visitor token like the rest of the widget\nAPI.","operationId":"getWidgetCart","parameters":[{"name":"key","in":"path","description":"The chat channel's public key","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"query","description":"The token `POST /widget/{key}/conversations` returned. Prefer the\n`X-Visitor-Token` header; the query parameter is for clients that\ncannot set headers.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetCartResponse"}}}},"401":{"description":"`bad_token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/widget/{key}/conversations/{conversation_id}/csat":{"post":{"tags":["Engagement"],"summary":"Rate the chat","description":"The shopper's satisfaction score, 1 to 5, with an optional comment.","operationId":"rateWidgetConversation","parameters":[{"name":"key","in":"path","description":"The chat channel's public key (`data-key` of the embed script)","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"query","description":"The token `POST /widget/{key}/conversations` returned. Prefer the\n`X-Visitor-Token` header; the query parameter is for clients that\ncannot set headers.","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetCsatRequest"}}},"required":true},"responses":{"204":{"description":"Recorded"},"400":{"description":"`invalid_score`: not 1 to 5","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`bad_token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/widget/{key}/conversations/{conversation_id}/messages":{"get":{"tags":["Engagement"],"summary":"List the chat's messages","description":"The latest 200 messages, oldest first.","operationId":"listWidgetMessages","parameters":[{"name":"key","in":"path","description":"The chat channel's public key (`data-key` of the embed script)","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"query","description":"The token `POST /widget/{key}/conversations` returned. Prefer the\n`X-Visitor-Token` header; the query parameter is for clients that\ncannot set headers.","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetThread"}}}},"401":{"description":"`bad_token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"tags":["Engagement"],"summary":"Send a chat message","description":"At most 20 messages per minute per conversation. A resolved or snoozed\nconversation reopens; the bot answers when it is on.","operationId":"sendWidgetMessage","parameters":[{"name":"key","in":"path","description":"The chat channel's public key (`data-key` of the embed script)","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"query","description":"The token `POST /widget/{key}/conversations` returned. Prefer the\n`X-Visitor-Token` header; the query parameter is for clients that\ncannot set headers.","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetSendRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetSendResponse"}}}},"400":{"description":"`empty` (`error`): no text","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"`bad_token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`slow_down` (`error`): over 20 messages a minute","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/widget/{key}/conversations/{conversation_id}/read":{"post":{"tags":["Engagement"],"summary":"Mark the chat as read","description":"The shopper saw the team's messages: they turn `read` for the team.","operationId":"markWidgetConversationRead","parameters":[{"name":"key","in":"path","description":"The chat channel's public key (`data-key` of the embed script)","required":true,"schema":{"type":"string"}},{"name":"conversation_id","in":"path","description":"Conversation id","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"query","description":"The token `POST /widget/{key}/conversations` returned. Prefer the\n`X-Visitor-Token` header; the query parameter is for clients that\ncannot set headers.","required":false,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"A unique value (e.g. a UUID) per logical request. Retrying with the same key within 24 hours replays the first response instead of repeating the side effect; the replay carries `Idempotent-Replayed: true`. Reusing a key for a different request is a 422 `idempotency_key_reused`; retrying while the first is still running is a 409 `idempotency_request_in_progress`. JSON bodies up to 1 MB.","required":false,"schema":{"type":"string","maxLength":255}}],"responses":{"204":{"description":"Marked read"},"401":{"description":"`bad_token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"`origin_not_allowed`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`not_found`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"`rate_limited`: over the request budget; see `Retry-After`","headers":{"RateLimit-Limit":{"schema":{"type":"integer"},"description":"Requests allowed per window."},"RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests left in the current window."},"RateLimit-Reset":{"schema":{"type":"integer"},"description":"Seconds until the window resets."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until the budget resets."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"default":{"description":"Any other error, in the standard error shape","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"CartCustomerType":{"type":"string","description":"Whether the cart's shopper matched a customer on file (`existing`) or\nnot yet (`new`).","enum":["existing","new"]},"ChannelOrderAddress":{"type":"object","properties":{"city":{"type":["string","null"]},"complement":{"type":["string","null"]},"district":{"type":["string","null"]},"number":{"type":["string","null"]},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"zipcode":{"type":["string","null"]}}},"ChannelOrderContact":{"type":"object","properties":{"email":{"type":["string","null"]},"name":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"ChannelOrderCreated":{"type":"object","description":"The order the channel created.","required":["id","status","total_cents","message"],"properties":{"id":{"type":"string","format":"uuid"},"message":{"type":"string","description":"`Order created successfully`."},"status":{"type":"string","description":"Always `pending`."},"total_cents":{"type":"integer","format":"int64"}}},"ChannelOrderLine":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"price":{"type":["number","null"],"format":"double"},"quantity":{"type":["integer","null"],"format":"int32"},"variationId":{"type":["string","null"]}}},"ChannelOrderRequest":{"type":"object","properties":{"address":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ChannelOrderAddress"}]},"contact":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ChannelOrderContact"}]},"discount":{"type":["number","null"],"format":"double"},"paymentMethod":{"type":["string","null"]},"products":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ChannelOrderLine"}},"shipping":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ChannelOrderShipping"}]},"shippingMethod":{"type":["string","null"]}}},"ChannelOrderShipping":{"type":"object","properties":{"carrier":{"type":["string","null"]},"delivery_time":{"type":["integer","null"],"format":"int32"},"price":{"type":["number","null"],"format":"double"},"service_type":{"type":["string","null"]}}},"ChannelProduct":{"type":"object","required":["id","name","slug","price","isPromotional","status","createdAt","updatedAt","projectId","description","hasVariations","boxes","images","categories","subCategories","tags","variations"],"properties":{"boxes":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProductBox"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProductCategory"}},"createdAt":{"type":"string"},"description":{"type":"string"},"hasVariations":{"type":"boolean"},"id":{"type":"string"},"images":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProductImage"}},"integrationId":{"type":["string","null"]},"isPromotional":{"type":"boolean"},"measureImage":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ChannelProductImage"}]},"name":{"type":"string"},"price":{"type":"number","format":"double"},"priority":{"type":["integer","null"],"format":"int32"},"projectId":{"type":"string"},"promotionalPrice":{"type":["number","null"],"format":"double"},"quickDescription":{"type":["string","null"]},"sku":{"type":["string","null"]},"slug":{"type":"string"},"specifications":{"type":["string","null"]},"status":{"type":"string"},"subCategories":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProductCategory"}},"tags":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProductTag"}},"updatedAt":{"type":"string"},"variations":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProductVariation"}},"weight":{"type":["number","null"],"format":"double"}}},"ChannelProductBox":{"type":"object","required":["id","name","description","width","height","depth","weight"],"properties":{"depth":{"type":"number","format":"double"},"description":{"type":"string"},"height":{"type":"number","format":"double"},"id":{"type":"string"},"name":{"type":"string"},"weight":{"type":"number","format":"double"},"width":{"type":"number","format":"double"}}},"ChannelProductCategory":{"type":"object","required":["id","name","slug","description"],"properties":{"description":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}}},"ChannelProductImage":{"type":"object","required":["id","url","path","name","alt","createdAt","updatedAt","projectId"],"properties":{"alt":{"type":"string"},"createdAt":{"type":"string"},"height":{"type":["integer","null"],"format":"int32"},"id":{"type":"string"},"name":{"type":"string"},"path":{"type":"string"},"projectId":{"type":"string"},"updatedAt":{"type":"string"},"url":{"type":"string"},"width":{"type":["integer","null"],"format":"int32"}}},"ChannelProductList":{"type":"object","required":["data","total","pageCount"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProduct"}},"pageCount":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"}}},"ChannelProductTag":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"ChannelProductVariation":{"type":"object","required":["id","name","price","isPromotional","type","images","boxes"],"properties":{"boxes":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProductBox"}},"color":{"type":["string","null"]},"id":{"type":"string"},"images":{"type":"array","items":{"$ref":"#/components/schemas/ChannelProductImage"}},"isPromotional":{"type":"boolean"},"name":{"type":"string"},"price":{"type":"number","format":"double"},"promotionalPrice":{"type":["number","null"],"format":"double"},"size":{"type":["string","null"]},"sku":{"type":["string","null"]},"type":{"type":"string"},"weight":{"type":["number","null"],"format":"double"}}},"ConversationCart":{"type":"object","description":"The assisted-sale cart of a conversation: what the team, the bot and the\ncontact all see, paid through `url`.","required":["cart_id","status","currency","item_count","subtotal_cents","discount_cents","shipping_cents","total_cents","paid","items"],"properties":{"cart_id":{"type":"string","format":"uuid"},"currency":{"type":"string"},"discount_cents":{"type":"integer","format":"int64"},"expires_at":{"type":["string","null"],"format":"date-time","description":"When the link stops working."},"item_count":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ConversationCartItem"}},"order_id":{"type":["string","null"],"format":"uuid"},"order_number":{"type":["string","null"]},"paid":{"type":"boolean","description":"The order is paid."},"shipping_cents":{"type":"integer","format":"int64"},"status":{"type":"string","description":"`open`, `converted` (an order was created), `abandoned` or `expired`."},"subtotal_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"},"url":{"type":["string","null"],"description":"The payment link to send the contact."}}},"ConversationCartItem":{"type":"object","required":["variant_id","product_id","title","quantity","unit_price_cents","total_cents"],"properties":{"image":{"type":["string","null"]},"product_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","format":"int32"},"sku":{"type":["string","null"]},"title":{"type":"string"},"total_cents":{"type":"integer","format":"int64"},"unit_price_cents":{"type":"integer","format":"int64"},"variant_id":{"type":"string","format":"uuid"}}},"ConversationMessagePayload":{"type":"object","description":"The documented keys of a message `payload`. All optional; others may appear.","properties":{"assignee_user_id":{"type":["string","null"],"format":"uuid","description":"System `assignment` messages: the new assignee (null when unassigned)."},"attachments":{"type":["array","null"],"items":{"type":"object"},"description":"Attachment metadata as the channel sent it. Use the message's\n`attachments` for download URLs."},"cart":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationCart","description":"Assisted-sale cart snapshot: render a cart card with its payment link."}]},"email":{"type":["object","null"],"description":"E-mail messages: subject, sender, sanitized HTML body, attachments."},"interactive":{"type":["boolean","null"],"description":"The contact tapped a button instead of typing."},"kind":{"type":["string","null"],"description":"System messages: `assignment`, `handover` or `resolved`."},"location":{"type":["object","null"],"description":"WhatsApp location messages: `latitude`, `longitude`, `name`, `address`."},"paid_order_id":{"type":["string","null"],"description":"The bot's payment confirmation: the paid order."},"pix":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationPixCharge","description":"A PIX charge created from the cart: render the QR code."}]},"pix_code":{"type":["boolean","null"],"description":"True on the follow-up message that carries only the PIX copy-and-paste code."},"products":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ConversationProductCard"},"description":"Product cards the bot suggested."},"quick_replies":{"type":["array","null"],"items":{"type":"string"},"description":"Up to three suggested answers, shown as buttons."},"reason":{"type":["string","null"],"description":"System `handover` messages: why the bot handed over."}}},"ConversationMessageSender":{"type":"string","description":"Who wrote a message. `visitor` is the contact (the customer, on any\nchannel), `agent` a team member, `bot` the store's AI agent, `system` an\nevent line (assignment, hand-over, resolution).","enum":["visitor","agent","bot","system"]},"ConversationPixCharge":{"type":"object","description":"A PIX charge for the order created from the cart.","required":["order_id","order_number","amount_cents","amount"],"properties":{"amount":{"type":"string","description":"Formatted (\"R$ 129,90\")."},"amount_cents":{"type":"integer","format":"int64"},"cart":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationCart","description":"The cart the order came from. Absent in the bot's PIX messages."}]},"copy_paste":{"type":["string","null"],"description":"The PIX copy-and-paste code."},"expires_at":{"type":["string","null"],"format":"date-time"},"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"qr_code_base64":{"type":["string","null"],"description":"PNG of the QR code, base64."}}},"ConversationProductCard":{"type":"object","description":"A product card inside a bot message.","required":["id","title","price","url"],"properties":{"compare_at":{"type":["string","null"],"description":"Formatted original price when on promotion."},"id":{"type":"string","format":"uuid"},"image":{"type":["string","null"]},"price":{"type":"string","description":"Formatted price (\"R$ 129,90\")."},"title":{"type":"string"},"url":{"type":"string","description":"Product page on the storefront."}}},"ConversationStatus":{"type":"string","description":"Where a conversation stands. `open`: someone should answer; `pending`:\nthe bot handed over and nobody took it yet; `snoozed`: hidden until\n`snoozed_until` (a new customer message wakes it); `resolved`: closed\n(a new customer message reopens it).","enum":["open","pending","snoozed","resolved"]},"ErrorResponse":{"type":"object","description":"Canonical error body. Every error response from the API has this shape,\nwhatever produced it: handlers that build an [`ApiError`], the older\nhelpers below, bare status codes and axum's own rejections (the last two\nare rewritten by `common::api::normalize_errors`).\n\n`error` stays the human-readable message so consumers written against\nthe original `{\"error\": \"...\"}` body keep working; `code` is the stable,\nmachine-readable part clients should branch on.","required":["error","code"],"properties":{"code":{"type":"string","description":"Stable snake_case identifier for the failure, e.g. `not_found`,\n`validation_failed`, `discount_code_expired`.","example":"not_found"},"details":{"type":["object","null"],"description":"Structured context for the failure, such as per-field validation\nmessages. Shape depends on `code`."},"error":{"type":"string","description":"Human-readable message. Wording may change; do not match on it.","example":"Order not found"}}},"FreightQuoteOption":{"type":"object","description":"One freight option of a quote: a carrier service or a local delivery\nzone, with its price and delivery time.","required":["option_id","service_name","shipping_cents","raw"],"properties":{"carrier_name":{"type":["string","null"]},"delivery_days":{"type":["integer","null"],"format":"int32"},"option_id":{"type":"string"},"provider_code":{"type":"string","description":"Which module produced this option. A quote can now merge several\ncarriers plus the store's own local delivery, so provenance has to\ntravel with each option — it used to be recovered by sniffing\n`option_id.starts_with(\"local_delivery:\")` at checkout.\n\n`#[serde(default)]` because quotes persisted before this field existed\nare still deserialized; those fall back to the quote row's provider."},"quotation_code":{"type":["string","null"],"description":"The provider's own quotation reference for this option, when it has\none. Stored per option because each carrier issues its own."},"raw":{"type":"object","description":"The carrier's own option payload."},"service_name":{"type":"string"},"shipping_cents":{"type":"integer","format":"int64"}}},"MessageDeliveryStatus":{"type":"string","description":"Delivery of an outbound (agent or bot) message. On WhatsApp it follows\nMeta's status callbacks: `sent` (accepted), `delivered` (on the phone),\n`read`, or `failed` with `delivery_error`. On the web widget `read` means\nthe visitor opened the chat. Messages from the contact stay `sent`.\nTolerate unknown values.","enum":["sent","delivered","read","failed"]},"PaymentIntentStatus":{"type":"string","description":"State of a payment attempt: `pending` (waiting for the customer),\n`processing` (the gateway is settling), `requires_action`, `approved`\n(paid), `failed`, `cancelled`, `expired` (e.g. an unpaid PIX code) or\n`refunded`.","enum":["pending","processing","requires_action","approved","failed","cancelled","expired","refunded"]},"PaymentMethod":{"type":"string","description":"A payment method a gateway can offer at checkout.","enum":["pix","card"]},"ProductRatingSummary":{"type":"object","description":"Approved reviews of a product, by rating.","required":["total","average","count_5","count_4","count_3","count_2","count_1"],"properties":{"average":{"type":"number","format":"double","description":"Mean rating, 0 when there are none."},"count_1":{"type":"integer","format":"int64"},"count_2":{"type":"integer","format":"int64"},"count_3":{"type":"integer","format":"int64"},"count_4":{"type":"integer","format":"int64"},"count_5":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64"}}},"ProductSubscribeRequest":{"type":"object","description":"\"Let me know\" sign-up. Also accepted form-encoded.","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":["string","null"]},"kind":{"$ref":"#/components/schemas/ProductSubscriptionKind","description":"`back_in_stock` (the default) or `price_drop`; anything else is\ntreated as `back_in_stock`."},"marketing_opt_in":{"type":["boolean","null"],"description":"The shopper ticked \"send me news\". Only used when the e-mail is new\nto the store."},"variant_id":{"type":["string","null"],"format":"uuid","description":"Watch one variant only (back in stock)."}}},"ProductSubscribeResponse":{"type":"object","description":"The sign-up was recorded.","required":["ok","message"],"properties":{"message":{"type":"string","description":"A Portuguese confirmation to show the shopper."},"ok":{"type":"boolean","description":"Always true."}}},"ProductSubscriptionKind":{"type":"string","description":"What a shopper wants to hear about.","enum":["back_in_stock","price_drop"]},"Review":{"type":"object","description":"A product review.","required":["id","store_id","product_id","author_name","author_email","rating","body","status","is_verified_purchase","created_at","updated_at"],"properties":{"author_email":{"type":"string"},"author_name":{"type":"string"},"body":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"customer_id":{"type":["string","null"],"format":"uuid"},"id":{"type":"string","format":"uuid"},"is_verified_purchase":{"type":"boolean","description":"The author's e-mail bought the product in this store."},"order_id":{"type":["string","null"],"format":"uuid"},"product_id":{"type":"string","format":"uuid"},"rating":{"type":"integer","format":"int32","description":"1 to 5."},"status":{"$ref":"#/components/schemas/ReviewStatus"},"store_id":{"type":"string","format":"uuid"},"title":{"type":["string","null"]},"updated_at":{"type":"string","format":"date-time"}}},"ReviewStatus":{"type":"string","description":"`pending` (waiting for moderation), `approved` (shown on the storefront)\nor `rejected`.","enum":["pending","approved","rejected"]},"ReviewSubmitRequest":{"type":"object","description":"A shopper's review.","required":["author_name","author_email","rating","body"],"properties":{"author_email":{"type":"string"},"author_name":{"type":"string","description":"1 to 200 characters."},"body":{"type":"string","description":"1 to 5000 characters."},"rating":{"type":"integer","format":"int32","description":"1 to 5."},"title":{"type":["string","null"]}}},"StoreLocationPhoto":{"type":"object","description":"A photo of a location.","required":["url"],"properties":{"alt":{"type":["string","null"]},"url":{"type":"string"}}},"StorefrontCart":{"type":"object","description":"The shopper's open cart.","required":["id","store_id","item_count","subtotal_cents","tax_cents","shipping_cents","discount_cents","total_cents","currency","requires_shipping","freight_options","items","fulfillment_method"],"properties":{"contact_draft":{"$ref":"#/components/schemas/StorefrontCartContactDraft"},"currency":{"type":"string"},"destination_postal_code":{"type":["string","null"],"description":"CEP of the last freight quote."},"discount_cents":{"type":"integer","format":"int64"},"freight_options":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontFreightOption"},"description":"Options of the last freight quote."},"fulfillment_method":{"type":"string","description":"`shipping` or `pickup`."},"id":{"type":"string","format":"uuid"},"item_count":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCartItem"}},"pickup_location_id":{"type":["string","null"],"format":"uuid"},"requires_shipping":{"type":"boolean","description":"Some line is a physical product."},"selected_freight_option_id":{"type":["string","null"]},"shipping_cents":{"type":"integer","format":"int64"},"store_id":{"type":"string","format":"uuid"},"subtotal_cents":{"type":"integer","format":"int64"},"tax_cents":{"type":"integer","format":"int64"},"total_cents":{"type":"integer","format":"int64"}}},"StorefrontCartAck":{"type":"object","description":"A theme form endpoint's acknowledgement.","required":["ok"],"properties":{"cart_id":{"type":["string","null"],"format":"uuid","description":"The cart written to; only on `cart/add`."},"ok":{"type":"boolean","description":"Always true."}}},"StorefrontCartAddRequest":{"type":"object","description":"Add a variant to the cart (theme form endpoint).","required":["variant_id"],"properties":{"quantity":{"type":["integer","null"],"format":"int32","description":"Defaults to 1."},"variant_id":{"type":"string"}}},"StorefrontCartChangeRequest":{"type":"object","description":"Set a line's quantity (theme form endpoint); 0 or less removes it.","required":["variant_id","quantity"],"properties":{"quantity":{"type":"integer","format":"int32"},"variant_id":{"type":"string"}}},"StorefrontCartContactDraft":{"type":"object","description":"The contact details saved on the cart, for pre-filling checkout.","properties":{"additional_info":{"type":["string","null"]},"city":{"type":["string","null"]},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"zip_code":{"type":["string","null"]}}},"StorefrontCartContactSaved":{"type":"object","description":"The contact draft was saved.","required":["success","cart_id","customer_type"],"properties":{"cart_id":{"type":"string","format":"uuid"},"customer_type":{"$ref":"#/components/schemas/CartCustomerType","description":"Deprecated: always `new`, for the same reason."},"identified_customer_id":{"type":["string","null"],"format":"uuid","description":"Deprecated: always null. This public endpoint no longer says whether\nthe e-mail or phone belongs to a customer on file.","deprecated":true},"success":{"type":"boolean","description":"Always true."}}},"StorefrontCartContactUpsertRequest":{"type":"object","description":"The shopper's contact and delivery details, saved as the cart's draft.\nEvery field replaces the stored one (send the whole form), except\n`document`, which a blank value does not erase.","properties":{"additional_info":{"type":["string","null"]},"cart_id":{"type":["string","null"]},"city":{"type":["string","null"]},"currency":{"type":["string","null"]},"document":{"type":["string","null"],"description":"CPF/CNPJ; stored as digits."},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"zip_code":{"type":["string","null"]}}},"StorefrontCartFreightQuoteApiRequest":{"type":"object","description":"Quote freight for the cart.","required":["destination_postal_code"],"properties":{"cart_id":{"type":["string","null"]},"currency":{"type":["string","null"]},"destination_postal_code":{"type":"string","description":"CEP, with or without the dash (8 digits)."}}},"StorefrontCartFreightQuoteRequest":{"type":"object","description":"Quote freight for the cart (theme form endpoint).","required":["destination_postal_code"],"properties":{"destination_postal_code":{"type":"string","description":"CEP, with or without the dash."}}},"StorefrontCartFreightSelectApiRequest":{"type":"object","description":"Pick a freight option from the cart's last quote.","required":["option_id"],"properties":{"cart_id":{"type":["string","null"]},"currency":{"type":["string","null"]},"option_id":{"type":"string"}}},"StorefrontCartFreightSelectRequest":{"type":"object","description":"Pick a freight option from the cart's last quote (theme form endpoint).","required":["option_id"],"properties":{"option_id":{"type":"string"}}},"StorefrontCartItem":{"type":"object","description":"One line of the shopper's cart.","required":["id","product_id","variant_id","title","quantity","unit_price_cents","total_cents"],"properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","format":"int32"},"sku":{"type":["string","null"]},"title":{"type":"string","description":"Product title, with the variant title when it adds anything."},"total_cents":{"type":"integer","format":"int64"},"unit_price_cents":{"type":"integer","format":"int64"},"variant_id":{"type":"string","format":"uuid"}}},"StorefrontCartItemUpsertRequest":{"type":"object","description":"Set a line's quantity; 0 removes it.","required":["variant_id","quantity"],"properties":{"cart_id":{"type":["string","null"]},"currency":{"type":["string","null"]},"quantity":{"type":"integer","format":"int32"},"variant_id":{"type":"string"}}},"StorefrontCartPickupRequest":{"type":"object","description":"Switch the cart between pickup at a store location and shipping.","properties":{"cart_id":{"type":["string","null"]},"fulfillment_method":{"type":["string","null"],"description":"`pickup` or `shipping`. Defaults to `pickup` when `location_id` is\nsent, `shipping` otherwise."},"location_id":{"type":["string","null"],"description":"The pickup location; required for `pickup`."}}},"StorefrontCheckoutApiRequest":{"type":"object","description":"Which cart to check out.","properties":{"cart_id":{"type":["string","null"]},"currency":{"type":["string","null"]}}},"StorefrontCheckoutResult":{"type":"object","description":"The paid order the cart became.","required":["order_id","cart_id"],"properties":{"cart_id":{"type":"string","format":"uuid"},"order_id":{"type":"string","format":"uuid"}}},"StorefrontCreateIntentRequest":{"type":"object","description":"Pay for the cart.","required":["method"],"properties":{"card_token":{"type":["string","null"],"description":"Mercado Pago card token from the card form; required for `card`."},"cart_id":{"type":["string","null"]},"currency":{"type":["string","null"]},"installments":{"type":["integer","null"],"format":"int32","description":"For `card`; capped by the store (and a quote's) maximum."},"method":{"$ref":"#/components/schemas/PaymentMethod"},"payer":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/StorefrontPayer"}]}}},"StorefrontCustomerLoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string"},"password":{"type":"string"}}},"StorefrontCustomerOrder":{"type":"object","description":"One of the customer's orders.","required":["id","status","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"currency":{"type":["string","null"],"description":"ISO 4217 code."},"fulfillment_status":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"number":{"type":["string","null"],"description":"Human order number, when assigned."},"payment_status":{"type":["string","null"]},"status":{"type":"string","description":"Order status (`pending`, `paid`, `shipped`, `delivered`, `cancelled`...)."},"total_cents":{"type":["integer","null"],"format":"int64"}}},"StorefrontCustomerProfile":{"type":"object","description":"The signed-in customer.","required":["id","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"email":{"type":["string","null"]},"full_name":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"phone":{"type":["string","null"]}}},"StorefrontCustomerRegisterRequest":{"type":"object","description":"A new customer account.","required":["email","password"],"properties":{"email":{"type":"string"},"full_name":{"type":["string","null"]},"password":{"type":"string","description":"At least 8 characters. Checked here; the password itself is chosen\nwhen the e-mail is verified (`POST .../customers/verify`)."},"phone":{"type":["string","null"]}}},"StorefrontCustomerSession":{"type":"object","description":"A customer session: send `token` as `Authorization: Bearer <token>` to\nthe account endpoints of this store. Valid for 30 days.","required":["token","customer"],"properties":{"customer":{"$ref":"#/components/schemas/StorefrontCustomerProfile"},"token":{"type":"string"}}},"StorefrontCustomerVerifyRequest":{"type":"object","description":"Finish registration with the token from the verification e-mail.","required":["token","password"],"properties":{"password":{"type":"string","description":"At least 8 characters."},"token":{"type":"string","description":"The `token` from the verification link (valid 15 minutes, single use)."}}},"StorefrontFreightOption":{"type":"object","description":"A freight option of the cart's last quote.","required":["option_id","service_name","shipping_cents","provider_code","raw"],"properties":{"carrier_name":{"type":["string","null"]},"delivery":{"type":["string","null"]},"delivery_days":{"type":["integer","null"],"format":"int32"},"dispatch":{"type":["string","null"]},"is_required_term":{"type":["boolean","null"]},"logo":{"type":["string","null"]},"modal":{"type":["string","null"]},"option_id":{"type":"string"},"price":{"type":["number","null"],"format":"double","description":"Price in reais, as the carrier reported it. Prefer `shipping_cents`."},"provider_code":{"type":"string","description":"Which module produced this option (`central_do_frete`,\n`local_delivery`, ...). The carrier-shaped fields below are kept for\ntheme compatibility."},"raw":{"type":"object","description":"The carrier's own option payload."},"service_name":{"type":"string"},"service_type":{"type":["string","null"]},"shipping_carrier":{"type":["string","null"]},"shipping_carrier_document":{"type":["string","null"]},"shipping_cents":{"type":"integer","format":"int64"}}},"StorefrontFreightQuote":{"type":"object","description":"A freight quote: every option the store's carriers (and its local\ndelivery zones) offer for the destination. Options stay selectable\nuntil `expires_at`.","required":["quote_id","provider_code","destination_postal_code","options"],"properties":{"destination_postal_code":{"type":"string","description":"CEP, digits only."},"expires_at":{"type":["string","null"],"format":"date-time"},"options":{"type":"array","items":{"$ref":"#/components/schemas/FreightQuoteOption"}},"provider_code":{"type":"string","description":"The store's primary carrier."},"quotation_code":{"type":["string","null"]},"quote_id":{"type":"string","format":"uuid"}}},"StorefrontFreightSelection":{"type":"object","description":"The freight option now applied to the cart.","required":["cart_id","quote_id","provider_code","selected_option_id","shipping_cents"],"properties":{"cart_id":{"type":"string","format":"uuid"},"provider_code":{"type":"string"},"quote_id":{"type":"string","format":"uuid"},"selected_option_id":{"type":"string"},"shipping_cents":{"type":"integer","format":"int64"}}},"StorefrontFreightSimulation":{"type":"object","description":"A freight simulation for a set of variants, without a cart.","required":["provider_code","destination_postal_code","options","simulated_item_count","simulated_subtotal_cents"],"properties":{"destination_postal_code":{"type":"string","description":"CEP, digits only."},"expires_at":{"type":["string","null"],"format":"date-time"},"options":{"type":"array","items":{"$ref":"#/components/schemas/FreightQuoteOption"}},"provider_code":{"type":"string"},"quotation_code":{"type":["string","null"]},"simulated_item_count":{"type":"integer","format":"int32"},"simulated_subtotal_cents":{"type":"integer","format":"int64"}}},"StorefrontFreightSimulationItemRequest":{"type":"object","description":"One line of a freight simulation.","required":["variant_id","quantity"],"properties":{"quantity":{"type":"integer","format":"int32"},"variant_id":{"type":"string"}}},"StorefrontFreightSimulationRequest":{"type":"object","description":"Quote freight for a set of variants without a cart (product page).","required":["destination_postal_code","items"],"properties":{"destination_postal_code":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontFreightSimulationItemRequest"}},"whatsapp":{"type":["string","null"],"description":"Shopper's WhatsApp, passed to carriers that want a recipient."}}},"StorefrontInstallmentOption":{"type":"object","description":"One installment plan for the card.","required":["installments","installment_amount","total_amount","installment_rate","interest_free","label"],"properties":{"installment_amount":{"type":"number","format":"double","description":"Per installment, in reais."},"installment_rate":{"type":"number","format":"double","description":"Interest rate, percent; 0 when interest-free."},"installments":{"type":"integer","format":"int64"},"interest_free":{"type":"boolean"},"label":{"type":"string","description":"Ready-made label, e.g. `6x de R$ 50,00 sem juros`."},"total_amount":{"type":"number","format":"double","description":"Total charged, in reais."}}},"StorefrontInstallments":{"type":"object","description":"The installment plans the card's issuer offers for the amount.","required":["payment_method_id","options"],"properties":{"issuer_id":{"type":["integer","null"],"format":"int64"},"options":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontInstallmentOption"},"description":"At most 6 plans."},"payment_method_id":{"type":"string","description":"Card brand as Mercado Pago names it (`visa`, `master`, ...); empty\nwhen unknown."}}},"StorefrontLocation":{"type":"object","description":"A store location as shoppers see it.","required":["id","slug","name","country","timezone","hours_json","photos_json","amenities_json","is_pickup_enabled","pickup_lead_minutes","pickup_fee_cents","position"],"properties":{"amenities_json":{"type":"array","items":{"type":"string"},"description":"Amenity labels, e.g. `estacionamento`."},"city":{"type":["string","null"]},"complement":{"type":["string","null"]},"country":{"type":"string"},"description":{"type":["string","null"]},"email":{"type":["string","null"]},"hours_json":{"type":"object"},"id":{"type":"string","format":"uuid"},"is_pickup_enabled":{"type":"boolean"},"latitude":{"type":["number","null"],"format":"double"},"longitude":{"type":["number","null"],"format":"double"},"name":{"type":"string"},"neighborhood":{"type":["string","null"]},"number":{"type":["string","null"]},"phone":{"type":["string","null"]},"photos_json":{"type":"array","items":{"$ref":"#/components/schemas/StoreLocationPhoto"}},"pickup_fee_cents":{"type":"integer","format":"int64","description":"Charged as shipping when picking up here."},"pickup_instructions":{"type":["string","null"]},"pickup_lead_minutes":{"type":"integer","format":"int32"},"position":{"type":"integer","format":"int32"},"postal_code":{"type":["string","null"]},"slug":{"type":"string"},"state":{"type":["string","null"]},"street":{"type":["string","null"]},"timezone":{"type":"string"},"whatsapp":{"type":["string","null"]}}},"StorefrontPayer":{"type":"object","description":"Who pays, as typed at checkout.","properties":{"document":{"type":["string","null"]},"email":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]}}},"StorefrontPaymentConfig":{"type":"object","description":"What the theme needs to render the card form.","properties":{"public_key":{"type":["string","null"],"description":"Mercado Pago public key, for its card tokenization SDK."}}},"StorefrontPaymentIntent":{"type":"object","description":"A payment attempt as the shopper's browser sees it.","required":["intent_id","order_id","status","amount_cents","currency","provider_code","method","snapshot"],"properties":{"amount_cents":{"type":"integer","format":"int64"},"currency":{"type":"string"},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]},"expires_at":{"type":["string","null"],"format":"date-time","description":"When an unpaid PIX code stops working."},"intent_id":{"type":"string","format":"uuid"},"method":{"$ref":"#/components/schemas/PaymentMethod"},"next_action":{"type":["object","null"],"description":"What the shopper must do next, e.g. the PIX QR code and copy-paste\ncode for a pending PIX charge."},"order_id":{"type":"string","format":"uuid","description":"The order the cart became."},"provider_code":{"type":"string"},"snapshot":{"type":"object","description":"The gateway's answer, sanitized (no card data or secrets)."},"status":{"$ref":"#/components/schemas/PaymentIntentStatus"}}},"StorefrontPickupSelection":{"type":"object","description":"The cart's new fulfillment method.","required":["ok","fulfillment_method"],"properties":{"fulfillment_method":{"type":"string","description":"`pickup` or `shipping`."},"ok":{"type":"boolean","description":"Always true."},"pickup_location_id":{"type":["string","null"],"format":"uuid","description":"Set for `pickup`."},"shipping_cents":{"type":["integer","null"],"format":"int64","description":"The location's pickup fee; set for `pickup`."}}},"StorefrontProductCategoryItem":{"type":"object","description":"A category a product belongs to.","required":["id","name","slug"],"properties":{"description":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}}},"StorefrontProductDetail":{"type":"object","description":"A product with its images, variants and categories.","required":["id","title","slug","highlights","status","images","variants","categories"],"properties":{"categories":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductCategoryItem"}},"description":{"type":["string","null"]},"highlights":{"type":"array","items":{"type":"string"}},"id":{"type":"string","format":"uuid"},"images":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductImageItem"},"description":"Product-level images (variant images are under each variant)."},"model_placement":{"type":["string","null"]},"model_url":{"type":["string","null"],"description":"3D model (glTF/GLB) for the product viewer."},"price":{"type":["string","null"],"description":"Price as a decimal string (`\"129.90\"`)."},"rich_text_description":{"type":["string","null"]},"sale_price":{"type":["string","null"],"description":"Sale price as a decimal string, when on sale."},"short_description":{"type":["string","null"]},"slug":{"type":"string"},"status":{"type":"string","description":"Always `active`: other products are not served."},"title":{"type":"string"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductVariantItem"}}}},"StorefrontProductImageItem":{"type":"object","description":"A product or variant image.","required":["id","url","sizes","position"],"properties":{"alt":{"type":["string","null"]},"id":{"type":"string","format":"uuid"},"image_kind":{"type":["string","null"],"description":"`gallery` or `measurement` (a dimensions drawing, listed last)."},"position":{"type":"integer","format":"int32"},"sizes":{"type":"array","items":{"type":"string"},"description":"`url` followed by its resized renditions, when served by the API."},"url":{"type":"string"}}},"StorefrontProductItem":{"type":"object","description":"A product in a listing.","required":["id","title","slug","image_sizes"],"properties":{"id":{"type":"string","format":"uuid"},"image_alt":{"type":["string","null"]},"image_sizes":{"type":"array","items":{"type":"string"},"description":"`image_url` followed by its resized renditions (small, medium,\nlarge, thumbnail) when the image is served by the API."},"image_url":{"type":["string","null"],"description":"Main gallery image."},"price":{"type":["string","null"],"description":"Price as a decimal string in the store currency (`\"129.90\"`). Falls\nback to the cheapest active variant when the product has none."},"sale_price":{"type":["string","null"],"description":"Sale price as a decimal string, when on sale."},"short_description":{"type":["string","null"]},"slug":{"type":"string"},"title":{"type":"string"}}},"StorefrontProductList":{"type":"object","description":"A page of products. Paged by `limit`/`offset`.","required":["items","total","limit","offset"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductItem"}},"limit":{"type":"integer","format":"int64"},"offset":{"type":"integer","format":"int64"},"total":{"type":"integer","format":"int64","description":"Count of all matching products."}}},"StorefrontProductVariantItem":{"type":"object","description":"A purchasable variant of a product.","required":["id","title","images"],"properties":{"compare_at_cents":{"type":["integer","null"],"format":"int64","description":"Reference (\"from\") price in cents, shown struck through."},"id":{"type":"string","format":"uuid"},"image_url":{"type":["string","null"],"description":"The variant's main image, when it has its own."},"images":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductImageItem"},"description":"Images attached to this variant."},"metadata":{"type":["object","null"],"description":"Always null; kept for older themes."},"price_cents":{"type":["integer","null"],"format":"int64"},"sku":{"type":["string","null"]},"title":{"type":"string"}}},"StorefrontRegistrationPending":{"type":"object","description":"The answer to every registration request, whether or not the e-mail\nalready has an account (so the endpoint does not reveal which addresses\nare registered).","required":["message","verification_required"],"properties":{"message":{"type":"string"},"verification_required":{"type":"boolean","description":"Always true: the account exists only after the e-mailed link is used."}}},"StorefrontReviewItem":{"type":"object","description":"An approved review as shoppers see it.","required":["id","author_name","rating","body","is_verified_purchase","created_at"],"properties":{"author_name":{"type":"string"},"body":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"id":{"type":"string","format":"uuid"},"is_verified_purchase":{"type":"boolean"},"rating":{"type":"integer","format":"int32"},"title":{"type":["string","null"]}}},"StorefrontReviews":{"type":"object","description":"A page of a product's approved reviews, with the rating summary.","required":["items","total","summary"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontReviewItem"}},"summary":{"$ref":"#/components/schemas/ProductRatingSummary"},"total":{"type":"integer","format":"int64","description":"Approved reviews of the product."}}},"WidgetBootstrap":{"type":"object","description":"How the chat widget looks and greets.","required":["starters","store_name","title","subtitle","color","position","launcher_text","avatar_url","greeting","offline_message","collect_contact","require_contact","bot_name","bot_enabled","online","privacy_url"],"properties":{"avatar_url":{"type":"string"},"bot_enabled":{"type":"boolean"},"bot_name":{"type":"string"},"brand":{"type":["object","null"],"description":"Brand tokens (colors, fonts, logo) from the store's brand system.\nNull when the store has none."},"collect_contact":{"type":"boolean","description":"Ask for name and e-mail."},"color":{"type":"string","description":"Accent color, `#rrggbb`."},"greeting":{"type":"string"},"launcher_text":{"type":"string"},"offline_message":{"type":"string"},"online":{"type":"boolean","description":"Someone (a team member or the bot) answers now."},"position":{"type":"string","description":"`right` or `left`."},"privacy_url":{"type":"string"},"require_contact":{"type":"boolean","description":"Require them before the first message."},"starters":{"type":"array","items":{"type":"string"},"description":"Suggested first messages (when the bot is on)."},"store_name":{"type":"string"},"subtitle":{"type":"string"},"title":{"type":"string"}}},"WidgetCartResponse":{"type":"object","description":"The shopper's view of the cart.","properties":{"cart":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationCart","description":"Null until the team or the bot adds something."}]}}},"WidgetContactRequest":{"type":"object","properties":{"email":{"type":["string","null"]},"name":{"type":["string","null"]},"phone":{"type":["string","null"]}}},"WidgetConversation":{"type":"object","description":"The shopper's view of their conversation.","required":["id","status","bot_active","assigned","unread_for_visitor","created_at"],"properties":{"assigned":{"type":"boolean","description":"A team member took the conversation."},"bot_active":{"type":"boolean","description":"The bot is answering."},"contact_email":{"type":["string","null"]},"contact_name":{"type":["string","null"]},"contact_phone":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"csat_score":{"type":["integer","null"],"format":"int32"},"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/ConversationStatus"},"unread_for_visitor":{"type":"integer","format":"int32","description":"Team and bot messages the shopper has not read."}}},"WidgetCsatRequest":{"type":"object","required":["score"],"properties":{"comment":{"type":["string","null"]},"score":{"type":"integer","format":"int32","description":"1 to 5."}}},"WidgetMessage":{"type":"object","description":"A chat message as the shopper sees it.","required":["id","sender","text","payload","delivery_status","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"delivery_status":{"$ref":"#/components/schemas/MessageDeliveryStatus"},"id":{"type":"string","format":"uuid"},"payload":{"$ref":"#/components/schemas/ConversationMessagePayload","description":"Product cards, quick replies, the cart or a PIX charge."},"read_at":{"type":["string","null"],"format":"date-time"},"sender":{"$ref":"#/components/schemas/ConversationMessageSender"},"text":{"type":"string"}}},"WidgetSendRequest":{"type":"object","required":["text"],"properties":{"payload":{"type":["object","null"]},"text":{"type":"string","description":"Up to 4000 characters."}}},"WidgetSendResponse":{"type":"object","required":["message","conversation"],"properties":{"conversation":{"$ref":"#/components/schemas/WidgetConversation"},"message":{"$ref":"#/components/schemas/WidgetMessage"}}},"WidgetStartRequest":{"type":"object","properties":{"attributes":{"type":["object","null"],"description":"Page context (`page_url`, `referrer`, `locale`...)."},"email":{"type":["string","null"]},"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"text":{"type":["string","null"],"description":"Optional first message sent together with the opening."},"visitor_id":{"type":["string","null"],"description":"A stable id for this browser, to recognise returning visitors."}}},"WidgetStartResponse":{"type":"object","required":["conversation","token"],"properties":{"conversation":{"$ref":"#/components/schemas/WidgetConversation"},"message":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/WidgetMessage","description":"The first message, when `text` was sent."}]},"token":{"type":"string","description":"Proves ownership of the conversation: send it as `X-Visitor-Token`\non every later call and keep it with the conversation id."}}},"WidgetThread":{"type":"object","description":"The chat and its latest messages.","required":["conversation","messages"],"properties":{"conversation":{"$ref":"#/components/schemas/WidgetConversation"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/WidgetMessage"},"description":"The latest 200 messages, oldest first. Team assignment notices are\nleft out."}}}},"securitySchemes":{"channel_key":{"type":"apiKey","in":"header","name":"X-Channel-Key","description":"A sales channel's API key, generated in the admin under the channel."},"customer_auth":{"type":"http","scheme":"bearer","bearerFormat":"customer session token","description":"`Authorization: Bearer <token>` with the token from the store's customer login or register call. Valid for 30 days, only in the store that issued it."}}},"tags":[{"name":"Catalog","description":"Products and collections as shoppers see them"},{"name":"Cart","description":"The shopper's cart: lines, contact details, freight and pickup. The cart id travels in the `X-Cart-Id` header or the `cart_id` cookie"},{"name":"Checkout","description":"Turning the cart into a paid order: payment intents, installments and confirmation"},{"name":"Locations","description":"Store locations and pickup points"},{"name":"Account","description":"Customer sign-in, profile and orders"},{"name":"Engagement","description":"Chat, forms, reviews and subscriptions"},{"name":"Channel API","description":"The headless sales-channel API: products and order intake for an external storefront, authenticated by the sales channel's API key in `X-Channel-Key`. Field names are camelCase"}]}