{"openapi":"3.1.0","info":{"title":"Shopemaa Storefront API","description":"The API a storefront uses to show a Shopemaa store and sell from it: the catalogue, content pages, cart quotes, checkout, shopper accounts, reviews and analytics events. Use it to build your own storefront in any framework, or to sell from an app or site you already have.\n\nGuides and examples for developers are on [shopemaa.com/developers](https://shopemaa.com/developers).\n\n## Which store a request is for\n\n- **From your server**: send `Shopemaa-App-Key` (the *appKey* scheme). The key selects its store whatever host the storefront runs on. Make one in the Shopemaa dashboard under **Settings › Developers › Storefront API keys**; a storefront deployed on Shopemaa Cloud gets its own as `SHOPEMAA_APP_KEY`. The key is a secret: call the API from server code only, never from the browser, and never log it. A wrong key is a 403, and too many wrong keys from one address are a 429.\n- **Without a key**, the API finds the store from the host: `Storefront-Host` when sent, else the request's `Host`. That works only on the store's Shopemaa address or a verified custom domain, and only for browsing (catalogue, content, cart quotes).\n- Send `Storefront-Host: \u003cthe host the visitor opened\u003e` on every call, so redirects from a store's old addresses keep working.\n\nCheckout, order status and every shopper account endpoint need the App key.\n\n## Shoppers, protected stores and events\n\n- **Shopper sign-in**: `POST /storefront/v1/customers/login` returns a token; send it as `Customer-Token` (the *customerToken* scheme) on account calls. On checkout it makes the order the shopper's (without it, a guest order, if the store allows guest checkout), and on cart quotes the shopper's sales apply.\n- **Password-protected stores**: `POST /storefront/v1/store/password` returns an access token; send it as `Storefront-Token`.\n- **Events**: have your storefront's server forward the visitor's events to `POST /public/v1/storefront/events` with the App key, passing the visitor's address and user agent in `Shopemaa-Visitor-Ip` and `Shopemaa-Visitor-User-Agent`. Neither is stored.\n\n## Conventions\n\nJSON names are snake_case. Lists page with `page` (from 0) and `size`. Checkout requires an `Idempotency-Key`: a new one per attempt, the same on retries, so a retried request returns the same order. Errors are JSON with the HTTP status, and too many requests are a 429.","contact":{"name":"Support","email":"support@shopemaa.com"},"version":"1.0.0"},"externalDocs":{"description":"Shopemaa for developers","url":"https://shopemaa.com/developers"},"servers":[{"url":"https://api.shopemaa.com","description":"Production"},{"url":"https://stage-api.shopemaa.com","description":"Stage"},{"url":"http://localhost:8282","description":"Local development"}],"tags":[{"name":"Store","description":"The store's profile, and the password of a password-protected store"},{"name":"Catalogue","description":"Products, collections, categories, search, product sections, cart quotes and pickup points"},{"name":"Content","description":"Published pages, blog posts, menus and policies"},{"name":"Checkout","description":"Checkout and order status, for signed-in shoppers and guests"},{"name":"Shopper accounts","description":"Sign-up, sign-in, password reset and the signed-in shopper's account: profile, addresses, orders, library and reviews"},{"name":"Reviews","description":"Published product reviews and their photos"},{"name":"Review requests","description":"Reviewing an order's items from a review request email (Review-Token)"},{"name":"Events","description":"Anonymous storefront events for the store's analytics"}],"paths":{"/public/v1/storefront/events":{"post":{"tags":["Events"],"summary":"Send storefront events","description":"Up to 50 events from one session: SESSION_STARTED, PAGE_VIEWED (with path), PRODUCT_VIEWED (with product_id), SEARCH_PERFORMED (with query), ADDED_TO_CART, CHECKOUT_STARTED. Ids are stored only as hashes. The visitor's IP address and user agent are read for country, device and bot filtering and never stored; a storefront server forwarding with its App key passes them in Shopemaa-Visitor-Ip and Shopemaa-Visitor-User-Agent. Without visitor_id and session_id the visitor is a daily hash. Events naming a product that isn't on sale here, and bots, are dropped. Paid orders come from checkout, not from events.","operationId":"trackStorefrontEvents","parameters":[{"name":"CF-IPCountry","in":"header","description":"Visitor's country as set by the edge (Cloudflare); used when the body has none","required":false,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqStorefrontEvents"}}},"required":true},"responses":{"202":{"description":"Accepted; says how many were stored and dropped","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResStorefrontEventsTracked"}}}},"400":{"description":"An invalid batch","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many events from this session or for this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/account":{"get":{"tags":["Shopper accounts"],"summary":"My account","description":"The signed-in shopper's profile.","operationId":"getStorefrontAccount","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCustomer"}}}},"401":{"description":"Not signed in (errors.code LOGIN_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]},"put":{"tags":["Shopper accounts"],"summary":"Update my account","description":"Replaces the profile. A new email is pending until verified (pending_email); the sign-in email stays until then.","operationId":"updateStorefrontAccount","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontAccountUpdate"}}},"required":true},"responses":{"200":{"description":"The profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCustomer"}}}},"400":{"description":"Invalid data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/addresses":{"get":{"tags":["Shopper accounts"],"summary":"My addresses","operationId":"listStorefrontAccountAddresses","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Saved addresses, oldest first","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontAddressList"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]},"post":{"tags":["Shopper accounts"],"summary":"Add an address","description":"The first one is the default; at most 20.","operationId":"createStorefrontAccountAddress","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqCustomerAddress"}}},"required":true},"responses":{"201":{"description":"The address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResCustomerAddress"}}}},"400":{"description":"Invalid data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Already 20 addresses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/addresses/{addressId}":{"put":{"tags":["Shopper accounts"],"summary":"Replace an address","operationId":"updateStorefrontAccountAddress","parameters":[{"name":"addressId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqCustomerAddress"}}},"required":true},"responses":{"200":{"description":"The address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResCustomerAddress"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's addresses","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]},"delete":{"tags":["Shopper accounts"],"summary":"Delete an address","operationId":"deleteStorefrontAccountAddress","parameters":[{"name":"addressId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Not signed in","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's addresses","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/library":{"get":{"tags":["Shopper accounts"],"summary":"My downloads","description":"Digital products from paid orders, each with access_status (ACTIVE, REVOKED, ORDER_NOT_PAID, EXPIRED, LIMIT_REACHED).","operationId":"listStorefrontAccountLibrary","parameters":[{"name":"page","in":"query","description":"Zero-based page index (0..N)","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"size","in":"query","description":"The size of the page to be returned","required":false,"schema":{"type":"integer","default":20,"minimum":1}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of library entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResCustomerLibraryList"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/library/{deliveryId}/link":{"post":{"tags":["Shopper accounts"],"summary":"Get a download link","description":"A new link for an ACTIVE delivery, returned once; the earlier (emailed) link stops working.","operationId":"createStorefrontDownloadLink","parameters":[{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontDownloadLink"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's deliveries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Revoked, unpaid, expired or used up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/orders":{"get":{"tags":["Shopper accounts"],"summary":"My orders","description":"Orders on the shopper's customer record, newest first by default; guest orders under their verified email included.","operationId":"listStorefrontAccountOrders","parameters":[{"name":"page","in":"query","description":"Zero-based page index (0..N)","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"size","in":"query","description":"The size of the page to be returned","required":false,"schema":{"type":"integer","default":20,"minimum":1}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","required":false,"schema":{"type":"array","default":["createdAt,DESC"],"items":{"type":"string"}}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResOrderList"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/orders/{orderId}":{"get":{"tags":["Shopper accounts"],"summary":"One of my orders","operationId":"getStorefrontAccountOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResOrder"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/reviewable-items":{"get":{"tags":["Reviews"],"summary":"Items I can review","description":"Lines of the shopper's paid orders that are delivered (digital: paid), not yet reviewed, and still within the store's review window.","operationId":"listStorefrontReviewableItems","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewableItems"}}}},"401":{"description":"Not signed in (errors.code LOGIN_REQUIRED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"Reviews off (REVIEWS_DISABLED), accounts off, or no storefront key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/reviews":{"get":{"tags":["Reviews"],"summary":"My reviews","description":"Every review the shopper wrote, whatever its status, newest first by default; editable_until is null once it can't be changed.","operationId":"listStorefrontAccountReviews","parameters":[{"name":"page","in":"query","description":"Zero-based page index (0..N)","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"size","in":"query","description":"The size of the page to be returned","required":false,"schema":{"type":"integer","default":20,"minimum":1}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","required":false,"schema":{"type":"array","default":["createdAt,DESC"],"items":{"type":"string"}}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopperReviewList"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]},"post":{"tags":["Reviews"],"summary":"Review an item I bought","description":"One review per order line. With the store's manual moderation it waits for approval (PENDING); otherwise it is published at once.","operationId":"createStorefrontReview","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewCreateRequest"}}},"required":true},"responses":{"201":{"description":"The review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopperReview"}}}},"400":{"description":"Invalid rating or text too long","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"Reviews off (REVIEWS_DISABLED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's order lines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Already reviewed, not arrived yet, or the time to review has passed; the message says which","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many review changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/reviews/{reviewId}":{"put":{"tags":["Reviews"],"summary":"Change my review","description":"Replaces rating and text while the review window is open. With manual moderation, or after staff rejected or hid it, it waits for approval again.","operationId":"updateStorefrontReview","parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewEditRequest"}}},"required":true},"responses":{"200":{"description":"The review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopperReview"}}}},"400":{"description":"Invalid rating or text too long","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"Reviews off (REVIEWS_DISABLED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"The time to change it has passed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]},"delete":{"tags":["Reviews"],"summary":"Delete my review","description":"Allowed at any time; the item can then be reviewed again while its window is open.","operationId":"deleteStorefrontReview","parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Not signed in","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's reviews","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/reviews/{reviewId}/media":{"post":{"tags":["Reviews"],"summary":"Add a photo or video to my review","description":"Returns where to PUT the file (exactly required_headers; the size and type are signed), valid 15 minutes. Then call .../complete. The file is processed (metadata removed, videos transcoded) and shown only after the store approves it.","operationId":"createStorefrontReviewMediaUpload","parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewMediaUploadRequest"}}},"required":true},"responses":{"201":{"description":"The upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewMediaUpload"}}}},"400":{"description":"Type not accepted or file too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Too many files of that kind, the store's allowance is used up, or the review can't be changed any more","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/reviews/{reviewId}/media/{mediaId}":{"delete":{"tags":["Reviews"],"summary":"Remove a file from my review","operationId":"deleteStorefrontReviewMedia","parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"mediaId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"204":{"description":"Removed"},"401":{"description":"Not signed in","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's files","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/account/reviews/{reviewId}/media/{mediaId}/complete":{"post":{"tags":["Reviews"],"summary":"Finish uploading a review file","description":"Checks the stored file's size and starts processing; status becomes PROCESSING, then READY or FAILED (failure_code). Calling it again returns the file as it is.","operationId":"completeStorefrontReviewMediaUpload","parameters":[{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"mediaId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewMedia"}}}},"401":{"description":"Not signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Not one of the shopper's files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Nothing uploaded yet, or the upload expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/cart/quote":{"post":{"tags":["Catalogue"],"summary":"Quote a bag","description":"Prices a bag exactly as checkout would now: sale prices (for a signed-in shopper's audience with Customer-Token, else sales for everyone), the discount code, shipping options for the destination and local pickup. Advisory: nothing is reserved. Lines that can't be bought, a refused code or a destination without rates come back as problems, not errors. At most 50 lines and 999 of each; rate limited per client.","operationId":"quoteStorefrontCart","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartQuoteRequest"}}},"required":true},"responses":{"200":{"description":"The quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCartQuote"}}}},"400":{"description":"Invalid bag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many quotes from this client or for this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"customerToken":[]},{"appKey":[]},{"appKey":[],"customerToken":[]}]}},"/storefront/v1/categories":{"get":{"tags":["Catalogue"],"summary":"List categories","description":"The store's categories by name, each with the number of products the storefront lists in it. Their products: GET /products?category=\u003cslug\u003e.","operationId":"listStorefrontCategories","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCategoryList"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/categories/{slug}":{"get":{"tags":["Catalogue"],"summary":"Get a category","description":"A category by slug, with the number of products the storefront lists in it.","operationId":"getStorefrontCategory","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCategory"}}}},"404":{"description":"No store here, or no such category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/checkout":{"post":{"tags":["Checkout"],"summary":"Check out","description":"Places the order and starts payment: redirect the shopper to checkout_url (Stripe), which returns them to the store's /checkout/success?order_id=... or /cart. With Customer-Token it is the shopper's order; without, a guest order (email required) if the store allows guest checkout. Sold in the store currency, through the same checkout as every channel (stock, discount codes, policies, shipping). Keep order_token server-side to show the order later. Idempotency-Key is required: a retry with the same key and cart returns the same order (and a new order_token) with Idempotent-Replayed: true.","operationId":"createStorefrontCheckout","parameters":[{"name":"Idempotency-Key","in":"header","description":"A new key per checkout attempt (e.g. a UUID), the same on retries; 1-255 printable ASCII characters","required":true,"schema":{"type":"string","maxLength":255,"minLength":1,"pattern":"^[\\x21-\\x7E]+$"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCheckoutRequest"}}},"required":true},"responses":{"201":{"description":"The order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCheckout"}}}},"400":{"description":"Invalid cart, address, code (errors.discount_code_reason) or missing Idempotency-Key / guest email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"401":{"description":"Customer-Token doesn't work (LOGIN_REQUIRED), or guest checkout is off (GUEST_CHECKOUT_DISABLED), or the store password is missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"Customer accounts are off (ACCOUNTS_DISABLED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Out of stock, store closed or can't take payments, policies changed, or the Idempotency-Key was used for another cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"502":{"description":"The payment provider failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[]},{"appKey":[],"customerToken":[]}]}},"/storefront/v1/checkout-handoffs/{handoffId}":{"get":{"tags":["Checkout"],"summary":"Open a checkout link","description":"A cart an AI assistant built (ADR 55), for the storefront to put in the shopper's cart: the lines, a discount code and the assistant. Needs a valid Shopemaa-App-Key; an unknown, expired or other store's link is a 404. Prices come from the cart quote.","operationId":"getStorefrontCheckoutHandoff","parameters":[{"name":"handoffId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResCheckoutHandoff"}}}},"403":{"description":"No or wrong storefront key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No such link, or it expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/collections":{"get":{"tags":["Catalogue"],"summary":"List collections","description":"The store's collections by title, each with the number of products the storefront lists in it. Their products: GET /products?collection=\u003cslug\u003e.","operationId":"listStorefrontCollections","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The collections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCollectionList"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/collections/{slug}":{"get":{"tags":["Catalogue"],"summary":"Get a collection","description":"A collection by slug.","operationId":"getStorefrontCollection","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontCollection"}}}},"404":{"description":"No store here, or no such collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/customers/login":{"post":{"tags":["Shopper accounts"],"summary":"Sign in","description":"Returns a session token to send as the Customer-Token header.","operationId":"logInStorefrontCustomer","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontLoginRequest"}}},"required":true},"responses":{"200":{"description":"Signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontSession"}}}},"401":{"description":"Wrong email or password (INVALID_CREDENTIALS), or the email isn't verified yet (EMAIL_NOT_VERIFIED; a new link was sent)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"}},"security":[{"appKey":[]}]}},"/storefront/v1/customers/logout":{"post":{"tags":["Shopper accounts"],"summary":"Sign out","description":"Ends the Customer-Token's session; 204 even if it had ended.","operationId":"logOutStorefrontCustomer","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"204":{"description":"Signed out"},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{"appKey":[],"customerToken":[]}]}},"/storefront/v1/customers/password/forgot":{"post":{"tags":["Shopper accounts"],"summary":"Forgot password","description":"Always 202 with the same body; a verified account gets a reset link (valid one hour), an unverified one a new verification link.","operationId":"requestStorefrontPasswordReset","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPasswordForgotRequest"}}},"required":true},"responses":{"202":{"description":"If the email has an account, a link was sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontAccepted"}}}},"429":{"description":"Too many requests from this client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{"appKey":[]}]}},"/storefront/v1/customers/password/reset":{"post":{"tags":["Shopper accounts"],"summary":"Reset password","description":"Sets a new password from a reset link; every session of the account ends.","operationId":"resetStorefrontPassword","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPasswordResetRequest"}}},"required":true},"responses":{"204":{"description":"Password changed; sign in again"},"400":{"description":"Invalid password, or unknown, used or expired link (errors.code INVALID_TOKEN)","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{"appKey":[]}]}},"/storefront/v1/customers/signup":{"post":{"tags":["Shopper accounts"],"summary":"Sign up","description":"Always 202 with the same body, whether or not the email has an account (a verified account's owner gets a reset email instead). The account works once the email is verified (POST /customers/verify).","operationId":"signUpStorefrontCustomer","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontSignupRequest"}}},"required":true},"responses":{"202":{"description":"Check your inbox","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontAccepted"}}}},"400":{"description":"Invalid email or password too short/long","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"Customer accounts are off (errors.code ACCOUNTS_DISABLED)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many requests from this client","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{"appKey":[]}]}},"/storefront/v1/customers/verify":{"post":{"tags":["Shopper accounts"],"summary":"Verify an email","description":"Uses the token from the verification link (sign-up or a new email) together with the account's password, and signs the shopper in. A wrong password leaves the link usable until it expires.","operationId":"verifyStorefrontCustomer","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontVerifyRequest"}}},"required":true},"responses":{"200":{"description":"Verified and signed in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontSession"}}}},"400":{"description":"Unknown, used or expired link (errors.code INVALID_TOKEN)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"401":{"description":"Wrong password (errors.code INVALID_CREDENTIALS)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many attempts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Another account or customer record has this email","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"}},"security":[{"appKey":[]}]}},"/storefront/v1/orders/{orderId}":{"get":{"tags":["Checkout"],"summary":"Order status","description":"One order, for whoever placed it: send the Order-Token its checkout returned, or the owner's Customer-Token. Anything else is a 404.","operationId":"getStorefrontOrder","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Order-Token","in":"header","description":"The order_token from checkout","required":false,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResOrder"}}}},"401":{"description":"A Customer-Token was sent but doesn't work","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No such order for this caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"}},"security":[{"appKey":[]},{"appKey":[],"customerToken":[]}]}},"/storefront/v1/products":{"get":{"tags":["Catalogue"],"summary":"List products","description":"ACTIVE products of the store as cards, priced for an anonymous visitor (sales for everyone). Sold-out products are left out when the store's out-of-stock display is HIDE. Paging: page (0-based) and size (1-100).","operationId":"listStorefrontProducts","parameters":[{"name":"collection","in":"query","description":"Only products in the collection with this slug","required":false,"schema":{"type":"string","maxLength":255,"minLength":0}},{"name":"category","in":"query","description":"Only products in the category with this slug (ADR 58)","required":false,"schema":{"type":"string","maxLength":255,"minLength":0}},{"name":"q","in":"query","description":"Words the title contains","required":false,"schema":{"type":"string","maxLength":100,"minLength":0}},{"name":"sort","in":"query","description":"NEWEST (default), BEST_SELLERS, PRICE_ASC, PRICE_DESC or TITLE","required":false,"schema":{"type":"string","enum":["NEWEST","BEST_SELLERS","PRICE_ASC","PRICE_DESC","TITLE"]}},{"name":"kind","in":"query","description":"Only digital products of this kind: DOWNLOAD or TEMPLATE (ADR 73)","required":false,"schema":{"type":"string","enum":["DOWNLOAD","TEMPLATE"]}},{"name":"made_for","in":"query","description":"Only templates made for this, e.g. WEBSITE_THEME","required":false,"schema":{"type":"string","enum":["CODE_PROJECT","FIGMA_FILE","NOTION_TEMPLATE","WEBSITE_THEME","SPREADSHEET","OTHER"]}},{"name":"works_with","in":"query","description":"Only digital products that work with this tag, ignoring case","required":false,"schema":{"type":"string","maxLength":40,"minLength":0}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0,"maximum":10000,"minimum":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":24,"maximum":100,"minimum":1}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontProductList"}}}},"400":{"description":"Invalid sort, paging or search","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store here, or no collection or category with this slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/products/{slug}":{"get":{"tags":["Catalogue"],"summary":"Get a product","description":"An ACTIVE product by slug, with media, options, variants (availability only, never stock counts), licences for digital products and a running sale for everyone. Drafts, archived, deleted and other stores' products are 404.","operationId":"getStorefrontProduct","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontProduct"}}}},"404":{"description":"No store here, or no such product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/products/{slug}/reviews":{"get":{"tags":["Reviews"],"summary":"A product's reviews","description":"Published reviews of an ACTIVE product with its rating. sort: NEWEST (default), HIGHEST, LOWEST; rating: only reviews with that many stars. Paging: page (0-based) and size (1-50).","operationId":"listStorefrontProductReviews","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","maxLength":200,"minLength":0}},{"name":"sort","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ReviewSort"}},{"name":"rating","in":"query","required":false,"schema":{"type":"integer","format":"int32","maximum":5,"minimum":1}},{"name":"with_media","in":"query","required":false,"schema":{"type":"boolean","default":false}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":0,"maximum":10000,"minimum":0}},{"name":"size","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":10,"maximum":50,"minimum":1}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontReviewList"}}}},"403":{"description":"The store has reviews off (errors.code REVIEWS_DISABLED), or a password is needed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No such product on sale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/products/{slug}/reviews/media":{"get":{"tags":["Reviews"],"summary":"Customers' photos and videos of a product","description":"Approved, processed files of its published reviews, newest review first, at most 30.","operationId":"getStorefrontReviewGallery","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","maxLength":200,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The gallery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontReviewGallery"}}}},"403":{"description":"Reviews off (REVIEWS_DISABLED), or a password is needed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No such product on sale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/review-requests/current":{"get":{"tags":["Review requests"],"summary":"Open a review link","description":"The order's items still open for review and the reviews already written for it.","operationId":"getStorefrontReviewRequest","parameters":[{"name":"Review-Token","in":"header","required":false,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The link's order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewRequest"}}}},"403":{"description":"Reviews off (REVIEWS_DISABLED) or no storefront key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Unknown or expired link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/review-requests/current/reviews":{"post":{"tags":["Review requests"],"summary":"Review an item from a review link","description":"As POST /account/reviews, for an item of the link's order.","operationId":"createStorefrontLinkReview","parameters":[{"name":"Review-Token","in":"header","required":false,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewCreateRequest"}}},"required":true},"responses":{"201":{"description":"The review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopperReview"}}}},"400":{"description":"Invalid review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"Unknown link, or not an item of its order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Already reviewed, or no longer reviewable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many review changes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/review-requests/current/reviews/{reviewId}":{"put":{"tags":["Review requests"],"summary":"Change a review from a review link","operationId":"updateStorefrontLinkReview","parameters":[{"name":"Review-Token","in":"header","required":false,"schema":{"type":"string"}},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewEditRequest"}}},"required":true},"responses":{"200":{"description":"The review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopperReview"}}}},"404":{"description":"Unknown link, or not a review of its order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"No longer changeable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/review-requests/current/reviews/{reviewId}/media":{"post":{"tags":["Review requests"],"summary":"Add a photo or video from a review link","description":"As POST /account/reviews/{id}/media.","operationId":"createStorefrontLinkReviewMediaUpload","parameters":[{"name":"Review-Token","in":"header","required":false,"schema":{"type":"string"}},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewMediaUploadRequest"}}},"required":true},"responses":{"201":{"description":"The upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewMediaUpload"}}}},"404":{"description":"Unknown link, or not a review of its order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Too many files, or the allowance is used up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/review-requests/current/reviews/{reviewId}/media/{mediaId}":{"delete":{"tags":["Review requests"],"summary":"Remove a file from a review link","operationId":"deleteStorefrontLinkReviewMedia","parameters":[{"name":"Review-Token","in":"header","required":false,"schema":{"type":"string"}},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"mediaId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"204":{"description":"Removed"},"404":{"description":"Unknown link or file","content":{"*/*":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/review-requests/current/reviews/{reviewId}/media/{mediaId}/complete":{"post":{"tags":["Review requests"],"summary":"Finish uploading a file from a review link","operationId":"completeStorefrontLinkReviewMediaUpload","parameters":[{"name":"Review-Token","in":"header","required":false,"schema":{"type":"string"}},{"name":"reviewId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"mediaId","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewMedia"}}}},"404":{"description":"Unknown link or file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"Nothing uploaded yet, or the upload expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/search":{"get":{"tags":["Catalogue"],"summary":"Search the store","description":"Up to 8 products, 5 pages and 5 posts whose title contains the words.","operationId":"searchStorefront","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":100,"minLength":0}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"What was found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontSearch"}}}},"400":{"description":"Missing, blank or longer than 100 characters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/sections/products":{"get":{"tags":["Catalogue"],"summary":"Products for a theme section","description":"A dynamic section's products (ADR 29): NEWEST, BEST_SELLERS, COLLECTION (collection_id) or PRODUCTS (product_ids, in that order). A deleted collection or product shows nothing rather than an error.","operationId":"listStorefrontSectionProducts","parameters":[{"name":"source","in":"query","required":true,"schema":{"type":"string","enum":["NEWEST","BEST_SELLERS","COLLECTION","PRODUCTS"]}},{"name":"collection_id","in":"query","required":false,"schema":{"type":"string","maxLength":255,"minLength":0}},{"name":"product_ids","in":"query","description":"Comma-separated or repeated; at most 24","required":false,"schema":{"type":"array","items":{"type":"string"},"maxItems":24,"minItems":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","format":"int32","default":8,"maximum":24,"minimum":1}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontSectionProducts"}}}},"400":{"description":"Missing source, collection_id or product_ids; or a limit outside 1-24","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/shipping/pickup-points":{"get":{"tags":["Catalogue"],"summary":"List pickup points","description":"For a cart quote's shipping option with requires_pickup_point: the carrier's pickup points in the country. Send the chosen one's id as pickup_point_id with the checkout.","operationId":"listStorefrontPickupPoints","parameters":[{"name":"option_id","in":"query","description":"The shipping option's id from the cart quote","required":true,"schema":{"type":"string"}},{"name":"country","in":"query","description":"The destination country (ISO 3166-1 alpha-2)","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The pickup points (may be empty)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorefrontPickupPoints"}}}},"400":{"description":"Not a pickup point option, or an unknown country","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"502":{"description":"Montonio couldn't be reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}}},"security":[]}},"/storefront/v1/store":{"get":{"tags":["Store"],"summary":"Resolve the store for a host","description":"Finds the store by the Storefront-Host header (the host the visitor opened; else the request's Host): \u003chandle\u003e.\u003cbase domain\u003e, an old handle still reserved (redirect = true), or an ACTIVE custom domain. Locally, Organization-Id is accepted as a fallback. Works for password-protected and closed stores, so the storefront can show those pages.","operationId":"getStorefrontStore","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResStorefrontStore"}}}},"404":{"description":"No store at this address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/storefront/v1/store/password":{"post":{"tags":["Store"],"summary":"Enter the store password","description":"Returns a short-lived signed token for a password-protected store; send it as the Storefront-Token header. Changing the password invalidates it.","operationId":"verifyStorefrontPassword","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReqStorefrontPassword"}}},"required":true},"responses":{"200":{"description":"The access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResStorefrontAccessToken"}}}},"400":{"description":"Password missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"401":{"description":"Wrong password","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"409":{"description":"The store isn't password protected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"429":{"description":"Too many attempts from this client or for this store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"}},"security":[{},{"appKey":[]}]}},"/v1/storefront/blog-posts":{"get":{"tags":["Content"],"summary":"The blog","description":"Posts whose publish time has passed, newest first.","operationId":"listStorefrontBlogPosts","parameters":[{"name":"tag","in":"query","description":"Only posts with this tag (ignoring case)","required":false,"schema":{"type":"string","maxLength":50,"minLength":0}},{"name":"page","in":"query","description":"Zero-based page index (0..N)","required":false,"schema":{"type":"integer","default":0,"minimum":0}},{"name":"size","in":"query","description":"The size of the page to be returned","required":false,"schema":{"type":"integer","default":10,"minimum":1}},{"name":"sort","in":"query","description":"Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.","required":false,"schema":{"type":"array","items":{"type":"string"}}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"A page of posts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResStorefrontBlogPostList"}}}},"400":{"description":"Invalid paging","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/v1/storefront/blog-posts/{slug}":{"get":{"tags":["Content"],"summary":"A live blog post by slug","operationId":"getStorefrontBlogPost","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The post","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResStorefrontBlogPost"}}}},"404":{"description":"No live post with this slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/v1/storefront/menus/{menu}":{"get":{"tags":["Content"],"summary":"A navigation menu","description":"header or footer: only items the storefront can open, each with its href.","operationId":"getStorefrontMenu","parameters":[{"name":"menu","in":"path","required":true,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The menu","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResNavigationMenu"}}}},"404":{"description":"Not header or footer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/v1/storefront/pages/{slug}":{"get":{"tags":["Content"],"summary":"A published page by slug","operationId":"getStorefrontPage","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResStorefrontPage"}}}},"404":{"description":"No published page with this slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/v1/storefront/policies":{"get":{"tags":["Content"],"summary":"The store's current policies","description":"Without text; show them at checkout and send them back as accepted_policies.","operationId":"listStorefrontPolicies","parameters":[{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The policies","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PolicyRef"}}}}},"404":{"description":"No store at this address (or not found)"},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}},"/v1/storefront/policies/{slug}":{"get":{"tags":["Content"],"summary":"A store policy","description":"By slug (terms-of-sale) or kind; the current version, or ?version=n for the one an order was placed under (also after the policy was removed).","operationId":"getStorefrontPolicy","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","required":false,"schema":{"type":"integer","format":"int32","minimum":1}},{"name":"Storefront-Host","in":"header","description":"The host the visitor opened (a store's subdomain or custom domain); else Host","required":false,"schema":{"type":"string"}},{"name":"Storefront-Token","in":"header","description":"Access token from POST /storefront/v1/store/password, for a password-protected store","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResStorePolicy"}}}},"400":{"description":"Invalid version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"404":{"description":"No such policy or version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FailureApiResponse"}}}},"403":{"description":"The App key belongs to no store, or Organization-Id isn't the key's store"},"429":{"description":"Too many wrong App keys from this client"},"401":{"description":"The store is password protected and the Storefront-Token is missing or expired"}},"security":[{},{"appKey":[]}]}}},"components":{"schemas":{"ReviewEditRequest":{"description":"Replaces the shopper's review: omitted text is removed","properties":{"rating":{"type":"integer","format":"int32","maximum":5,"minimum":1},"title":{"type":"string","maxLength":120,"minLength":0},"body":{"type":"string","maxLength":5000,"minLength":0}},"required":["rating"]},"ReviewMedia":{"description":"A photo or video on a review, as its writer and staff see it; url and poster_url only once READY","properties":{"id":{"type":"string"},"kind":{"$ref":"#/components/schemas/ReviewMediaKind"},"status":{"$ref":"#/components/schemas/ReviewMediaStatus"},"failure_code":{"$ref":"#/components/schemas/ReviewMediaFailure"},"moderation":{"$ref":"#/components/schemas/ReviewMediaModeration"},"moderation_reason":{"$ref":"#/components/schemas/ReviewStatusReason"},"url":{"type":"string"},"poster_url":{"type":"string","description":"A video's still image; null for photos"},"width":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"duration_ms":{"type":"integer","format":"int32"},"position":{"type":"integer","format":"int32"}}},"ReviewMediaFailure":{"type":"string","description":"TOO_LONG (video over the store's limit), UNSUPPORTED (not a photo or video we accept), TOO_LARGE (file or picture size), UNREADABLE (damaged, or it couldn't be processed)","enum":["TOO_LONG","UNSUPPORTED","TOO_LARGE","UNREADABLE"]},"ReviewMediaKind":{"type":"string","description":"PHOTO or VIDEO","enum":["PHOTO","VIDEO"]},"ReviewMediaModeration":{"type":"string","description":"PENDING, APPROVED (shown with the published review) or HIDDEN","enum":["PENDING","APPROVED","HIDDEN"]},"ReviewMediaStatus":{"type":"string","description":"UPLOADING (waiting for the upload), PROCESSING, READY or FAILED","enum":["UPLOADING","PROCESSING","READY","FAILED"]},"ReviewProduct":{"description":"The reviewed product; slug null when it is no longer on sale","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}}},"ReviewStatus":{"type":"string","description":"PENDING (awaiting approval), PUBLISHED, REJECTED (never shown) or HIDDEN (taken down after publishing)","enum":["PENDING","PUBLISHED","REJECTED","HIDDEN"]},"ReviewStatusReason":{"type":"string","description":"Why a review was rejected or hidden: SPAM, OFFENSIVE, OFF_TOPIC, PRIVATE_INFORMATION or NOT_ABOUT_PRODUCT","enum":["SPAM","OFFENSIVE","OFF_TOPIC","PRIVATE_INFORMATION","NOT_ABOUT_PRODUCT"]},"ShopperReview":{"description":"One of the signed-in shopper's own reviews","properties":{"id":{"type":"string"},"order_id":{"type":"string"},"order_item_id":{"type":"string"},"product":{"$ref":"#/components/schemas/ReviewProduct"},"variant_label":{"type":"string"},"rating":{"type":"integer","format":"int32"},"title":{"type":"string"},"body":{"type":"string"},"status":{"$ref":"#/components/schemas/ReviewStatus"},"status_reason":{"$ref":"#/components/schemas/ReviewStatusReason"},"merchant_reply":{"type":"string"},"replied_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"edited_at":{"type":"string","format":"date-time"},"published_at":{"type":"string","format":"date-time"},"editable_until":{"type":"string","format":"date-time","description":"Until when it can be edited; null when the window has closed"},"media":{"type":"array","description":"Its photos and videos, whatever their status","items":{"$ref":"#/components/schemas/ReviewMedia"}}}},"ErrorResponse":{"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"error_code":{"type":"string"},"error_message":{"type":"string"}}},"FailureApiResponse":{"type":"object","properties":{"data":{"type":"object","writeOnly":true},"error":{"$ref":"#/components/schemas/ErrorResponse"}}},"StorefrontAccountUpdate":{"description":"The shopper's profile, replaced whole","properties":{"first_name":{"type":"string","maxLength":100,"minLength":0},"last_name":{"type":"string","maxLength":100,"minLength":0},"phone":{"type":"string","maxLength":50,"minLength":0},"email":{"type":"string","description":"A different address is not used until it is verified: it is returned as pending_email and a verification email goes to it","maxLength":254,"minLength":0},"accepts_marketing":{"type":"boolean","description":"True subscribes to email marketing; false unsubscribes (no change if never subscribed)"}},"required":["accepts_marketing"]},"StorefrontCustomer":{"type":"object","description":"The signed-in shopper","properties":{"id":{"type":"string","description":"The store's customer record id"},"email":{"type":"string","description":"The verified sign-in email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_marketing":{"type":"boolean","description":"Subscribed to email marketing"},"pending_email":{"type":"string","description":"A new address waiting for verification; null without one"},"created_at":{"type":"string","format":"date-time"}}},"ReqCustomerAddress":{"description":"A customer's saved address","properties":{"label":{"type":"string","description":"e.g. Home, Studio","maxLength":50,"minLength":0},"name":{"type":"string","maxLength":200,"minLength":0},"line1":{"type":"string","maxLength":200,"minLength":0},"line2":{"type":"string","maxLength":200,"minLength":0},"city":{"type":"string","maxLength":100,"minLength":0},"region":{"type":"string","maxLength":100,"minLength":0},"postal_code":{"type":"string","maxLength":20,"minLength":0},"country":{"type":"string","minLength":1,"pattern":"^[A-Za-z]{2}$"},"phone":{"type":"string","maxLength":50,"minLength":0},"is_default":{"type":"boolean","description":"Make this the default address; the previous default stops being one. A customer's first address is always the default."}},"required":["is_default"]},"ResCustomerAddress":{"description":"A customer's saved address","properties":{"id":{"type":"string"},"label":{"type":"string"},"name":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"},"phone":{"type":"string"},"is_default":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ReviewModeration":{"type":"string","description":"MANUAL: new and edited reviews wait for staff approval; AUTO: they are published at once","enum":["MANUAL","AUTO"]},"ResStorePolicy":{"type":"object","description":"A store policy at one version","properties":{"kind":{"type":"string","enum":["TERMS_OF_SALE","PRIVACY","REFUNDS_AND_RETURNS","SHIPPING"]},"slug":{"type":"string","description":"Fixed per kind, e.g. terms-of-sale"},"path":{"type":"string","description":"Storefront path, /policies/\u003cslug\u003e"},"title":{"type":"string"},"body":{"type":"string","description":"Markdown"},"version":{"type":"integer","format":"int32","description":"Goes up by one on every change of title or body"},"updated_at":{"type":"string","format":"date-time","description":"When this version was written"}}},"NavigationMenuEntry":{"description":"A menu entry and where it leads","properties":{"id":{"type":"string"},"label":{"type":"string"},"target_type":{"type":"string","enum":["PAGE","COLLECTION","PRODUCT","POLICY","ALL_PRODUCTS","BLOG","URL"]},"target_id":{"type":"string","description":"Page, collection or product id; null for other types"},"policy_kind":{"type":"string","enum":["TERMS_OF_SALE","PRIVACY","REFUNDS_AND_RETURNS","SHIPPING"]},"url":{"type":"string","description":"The link for URL items"},"href":{"type":"string","description":"Storefront path (/pages/about, /collections/x, /products/x, /policies/x, /products, /blog) or the URL"},"target_title":{"type":"string","description":"The target's current title (page, collection, product or policy)"},"target_available":{"type":"boolean","description":"False when the target is a draft page, a product not on sale or a removed product; such items are hidden on the storefront"}}},"ResNavigationMenu":{"type":"object","description":"A store menu, in order","properties":{"menu":{"type":"string","enum":["HEADER","FOOTER"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/NavigationMenuEntry"}}}},"ReqStorefrontPassword":{"properties":{"password":{"type":"string","maxLength":200,"minLength":0}}},"ResStorefrontAccessToken":{"type":"object","properties":{"token":{"type":"string","description":"Send as the Storefront-Token header (or keep in a cookie) to browse the store; changing the password invalidates it"},"expires_at":{"type":"string","format":"date-time"}}},"ReviewCreateRequest":{"description":"A review of one item the shopper bought","properties":{"order_item_id":{"type":"string","description":"The order line being reviewed (GET /account/reviewable-items)","maxLength":64,"minLength":0},"rating":{"type":"integer","format":"int32","maximum":5,"minimum":1},"title":{"type":"string","maxLength":120,"minLength":0},"body":{"type":"string","description":"Plain text; line breaks are kept","maxLength":5000,"minLength":0}},"required":["rating"]},"ReviewMediaUploadRequest":{"description":"A photo or video the shopper is about to upload","properties":{"kind":{"$ref":"#/components/schemas/ReviewMediaKind"},"content_type":{"type":"string","description":"image/jpeg, image/png, image/webp, image/heic, image/heif, video/mp4, video/quicktime or video/webm; the upload must be sent with exactly this Content-Type","maxLength":64,"minLength":0},"size_bytes":{"type":"integer","format":"int64","description":"The file's exact size in bytes; the upload must be exactly this long"}},"required":["kind","size_bytes"]},"ReviewMediaUpload":{"type":"object","description":"Where to PUT the file: send exactly required_headers, then POST .../complete","properties":{"media":{"$ref":"#/components/schemas/ReviewMedia"},"upload_url":{"type":"string"},"required_headers":{"type":"object","additionalProperties":{"type":"string"}},"expires_at":{"type":"string","format":"date-time"}}},"StorefrontCheckoutAddress":{"description":"A postal address","properties":{"name":{"type":"string","description":"Recipient; defaults to the customer's first and last name","maxLength":200,"minLength":0},"line1":{"type":"string","maxLength":200,"minLength":0},"line2":{"type":"string","maxLength":200,"minLength":0},"city":{"type":"string","maxLength":100,"minLength":0},"region":{"type":"string","maxLength":100,"minLength":0},"postal_code":{"type":"string","maxLength":20,"minLength":0},"country":{"type":"string","minLength":1,"pattern":"^[A-Za-z]{2}$"},"phone":{"type":"string","maxLength":30,"minLength":0}}},"StorefrontCheckoutCustomer":{"description":"Who is buying","properties":{"first_name":{"type":"string","maxLength":100,"minLength":0},"last_name":{"type":"string","maxLength":100,"minLength":0},"phone":{"type":"string","maxLength":30,"minLength":0}}},"StorefrontCheckoutLine":{"description":"A variant to buy; for a digital product, its licence","properties":{"variant_id":{"type":"string","description":"The variant; for a digital product it may be left out when licence_id is given","maxLength":64,"minLength":0},"licence_id":{"type":"string","description":"A digital product's licence (each licence sells as its own variant)","maxLength":64,"minLength":0},"quantity":{"type":"integer","format":"int32","maximum":999,"minimum":1}}},"StorefrontCheckout":{"type":"object","description":"The order placed; send the shopper to checkout_url to pay","properties":{"order_id":{"type":"string"},"order_number":{"type":"integer","format":"int64","description":"Per-store order number, e.g. 1042 for #1042"},"status":{"type":"string","description":"PENDING until paid; CONFIRMED for a free order","enum":["PENDING","CONFIRMED","COMPLETED","CANCELLED"]},"payment_status":{"type":"string","enum":["PENDING","PAID","FAILED","REFUNDED","CANCELLED","EXPIRED","DUE"]},"checkout_url":{"type":"string","description":"Stripe's payment page; null when nothing is due"},"order_token":{"type":"string","description":"Secret for GET /storefront/v1/orders/{id} (Order-Token header); keep it server-side"}}},"StorefrontCartQuoteDestination":{"description":"Where the bag would be shipped","properties":{"country":{"type":"string","minLength":1,"pattern":"^[A-Za-z]{2}$"},"region":{"type":"string","description":"Not used for rates yet (zones are by country)","maxLength":100,"minLength":0},"postal_code":{"type":"string","description":"Not used for rates yet (zones are by country)","maxLength":20,"minLength":0}}},"StorefrontCartQuoteRequest":{"description":"A storefront bag to price","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCartQuoteRequestLine"},"maxItems":50,"minItems":0},"discount_code":{"type":"string","description":"A discount code as the shopper typed it; a refused code is reported in discount, not as an error","maxLength":64,"minLength":0},"destination":{"$ref":"#/components/schemas/StorefrontCartQuoteDestination"},"delivery":{"type":"string","description":"SHIP (default) or PICKUP","enum":["SHIP","PICKUP"]},"shipping_option_id":{"type":"string","description":"The shipping option the shopper picked; the cheapest one when omitted or no longer offered","maxLength":255,"minLength":0}}},"StorefrontCartQuoteRequestLine":{"description":"A line of the bag","properties":{"variant_id":{"type":"string","maxLength":255,"minLength":0},"licence_id":{"type":"string","description":"Digital products: the licence the shopper chose; must be the variant's licence","maxLength":255,"minLength":0},"quantity":{"type":"integer","format":"int32","maximum":999,"minimum":1}},"required":["quantity"]},"PaymentOption":{"description":"A way to pay online. Send payment_method, and montonio_method for Montonio, with the checkout","properties":{"id":{"type":"string","description":"Stable id: stripe, or montonio:\u003cmethod\u003e"},"payment_method":{"type":"string","description":"STRIPE or MONTONIO: the checkout's payment_method"},"montonio_method":{"type":"string","description":"MONTONIO only: the checkout's montonio_method (paymentInitiation, cardPayments, ...)"},"label":{"type":"string","description":"What to call it"},"test":{"type":"boolean","description":"Montonio in sandbox mode: only test banks and cards work"},"banks":{"type":"array","description":"Bank payments only: the banks a customer may pick (montonio_bank); may be empty, then Montonio asks","items":{"$ref":"#/components/schemas/PaymentOptionBank"}}}},"PaymentOptionBank":{"description":"A bank for a Montonio bank payment","properties":{"code":{"type":"string","description":"The checkout's montonio_bank"},"name":{"type":"string"},"country":{"type":"string","description":"The country it is offered in (ISO 3166-1 alpha-2)"},"logo_url":{"type":"string"}}},"StorefrontCartQuote":{"type":"object","description":"A priced storefront bag; advisory, nothing is reserved","properties":{"currency":{"type":"string","description":"The store currency; null until the merchant sets it (problem CURRENCY_NOT_SET)"},"lines":{"type":"array","description":"One per requested line, in order","items":{"$ref":"#/components/schemas/StorefrontCartQuoteLine"}},"subtotal":{"type":"integer","format":"int64","description":"Lines that can be bought, after sale prices, before the code"},"discount_total":{"type":"integer","format":"int64","description":"What the code takes off the lines and shipping"},"shipping_options":{"type":"array","description":"Rates for the destination, cheapest first, with the code's shipping discount taken off; empty without a destination or nothing to ship","items":{"$ref":"#/components/schemas/StorefrontShippingOption"}},"selected_shipping_option_id":{"type":"string","description":"The option shipping_total is for; null when nothing is shipped"},"pickup":{"$ref":"#/components/schemas/StorefrontCartQuotePickup"},"requires_shipping":{"type":"boolean","description":"Some line is physical"},"shipping_total":{"type":"integer","format":"int64","description":"The selected option's price (before the code), 0 for pickup or nothing to ship"},"tax_total":{"type":"integer","format":"int64","description":"Always 0: prices are charged as entered"},"grand_total":{"type":"integer","format":"int64"},"discount":{"$ref":"#/components/schemas/StorefrontCartQuoteDiscount"},"problems":{"type":"array","description":"Everything that would stop checkout, lines' problems included; empty when it can go ahead","items":{"$ref":"#/components/schemas/StorefrontCartQuoteProblem"}},"payment_options":{"type":"array","description":"How the shopper can pay online (ADR 105): Stripe and the store's Montonio methods. Empty when the store can't take online payments; free orders need none","items":{"$ref":"#/components/schemas/PaymentOption"}}}},"StorefrontCartQuoteDiscount":{"description":"The discount code the shopper typed","properties":{"code":{"type":"string"},"summary":{"type":"string","description":"The sentence to show: what the code does, or why it was refused"},"refused_reason":{"type":"string","description":"Why the code doesn't apply; null when it does. Totals are then without it","enum":["NOT_FOUND","DISABLED","NOT_STARTED","EXPIRED","USED_UP","ALREADY_USED","CURRENCY","MINIMUM_NOT_MET","NOT_ELIGIBLE","NOT_APPLICABLE","ON_SALE","NO_SHIPPING","SHIPPING_ZONE"]}}},"StorefrontCartQuoteLine":{"description":"A priced line of the bag","properties":{"variant_id":{"type":"string"},"licence_id":{"type":"string","description":"The licence a digital line sells; null otherwise"},"product_id":{"type":"string","description":"Null when the variant isn't the store's"},"slug":{"type":"string"},"title":{"type":"string"},"variant_title":{"type":"string","description":"Option values joined or the licence name; null for a product's only variant"},"image_url":{"type":"string","description":"The variant's image, else the product's primary image; null without one"},"quantity":{"type":"integer","format":"int32"},"unit_price":{"type":"integer","format":"int64","description":"What one unit costs this shopper (after a sale); 0 when not available"},"list_unit_price":{"type":"integer","format":"int64","description":"One unit before the sale"},"line_total":{"type":"integer","format":"int64","description":"unit_price x quantity"},"discount_amount":{"type":"integer","format":"int64","description":"This line's share of the code's discount"},"available":{"type":"boolean","description":"Can be bought as asked"},"problem":{"type":"string","description":"Why not; null when available","enum":["NOT_FOUND","UNAVAILABLE","LICENCE_MISMATCH","OUT_OF_STOCK","NOT_ENOUGH_STOCK","CURRENCY_NOT_SET","DESTINATION_NEEDED","NO_SHIPPING_TO_DESTINATION","SHIPPING_OPTION_UNAVAILABLE","PICKUP_UNAVAILABLE","DISCOUNT_REFUSED","ORDER_TOO_LARGE"]}}},"StorefrontCartQuotePickup":{"description":"Free local pickup","properties":{"available":{"type":"boolean","description":"Every physical product allows pickup and the store has a pickup address"},"address":{"type":"string","description":"Always null here: the pickup address is shown once the order is paid (ADR 19)"}}},"StorefrontCartQuoteProblem":{"description":"Something that would stop checkout","properties":{"code":{"type":"string","enum":["NOT_FOUND","UNAVAILABLE","LICENCE_MISMATCH","OUT_OF_STOCK","NOT_ENOUGH_STOCK","CURRENCY_NOT_SET","DESTINATION_NEEDED","NO_SHIPPING_TO_DESTINATION","SHIPPING_OPTION_UNAVAILABLE","PICKUP_UNAVAILABLE","DISCOUNT_REFUSED","ORDER_TOO_LARGE"]},"message":{"type":"string"},"variant_id":{"type":"string","description":"The line's variant, for a line's problem"}}},"StorefrontShippingOption":{"description":"A shipping option for the bag","properties":{"id":{"type":"string"},"name":{"type":"string"},"amount":{"type":"integer","format":"int64","description":"The price after the code's shipping discount"},"estimate":{"type":"string","description":"Delivery estimate; null until rates carry one"},"carrier_code":{"type":"string","description":"The Montonio carrier (omniva, dpd, ...) for a carrier rate (ADR 105); null otherwise"},"requires_pickup_point":{"type":"boolean","description":"The customer must pick a pickup point (GET /storefront/v1/shipping/pickup-points) and send its id as pickup_point_id with the checkout"}}},"StorefrontVerifyRequest":{"description":"The token from a verification link and the account's password","properties":{"token":{"type":"string","maxLength":128,"minLength":0},"password":{"type":"string","description":"The password chosen at sign-up (for an email change: the account's password)","maxLength":200,"minLength":0}}},"StorefrontSession":{"type":"object","description":"A sign-in session: send token as the Customer-Token header","properties":{"token":{"type":"string","description":"Opaque; keep it server-side (an httpOnly cookie), never in browser storage"},"expires_at":{"type":"string","format":"date-time","description":"The latest the session lasts; it also ends after a week without use, or on sign-out"},"customer":{"$ref":"#/components/schemas/StorefrontCustomer"}}},"StorefrontSignupRequest":{"description":"A new shopper account; the email must be verified to use it","properties":{"email":{"type":"string","maxLength":254,"minLength":0},"password":{"type":"string","description":"At least 8 characters, at most 72 bytes","maxLength":200,"minLength":0},"first_name":{"type":"string","maxLength":100,"minLength":0},"last_name":{"type":"string","maxLength":100,"minLength":0},"accepts_marketing":{"type":"boolean","description":"Email me news and offers; recorded as marketing consent once the email is verified"}}},"StorefrontAccepted":{"type":"object","description":"The request was taken; the same answer whether or not the email has an account","properties":{"message":{"type":"string"}}},"StorefrontPasswordResetRequest":{"description":"The token from a reset link and the new password","properties":{"token":{"type":"string","maxLength":128,"minLength":0},"password":{"type":"string","description":"At least 8 characters, at most 72 bytes","maxLength":200,"minLength":0}}},"StorefrontPasswordForgotRequest":{"description":"The account's email","properties":{"email":{"type":"string","maxLength":254,"minLength":0}}},"StorefrontLoginRequest":{"description":"Sign in with email and password","properties":{"email":{"type":"string","maxLength":254,"minLength":0},"password":{"type":"string","maxLength":200,"minLength":0}}},"AcceptedPolicyInput":{"description":"A store policy version shown to the customer","properties":{"kind":{"type":"string","enum":["TERMS_OF_SALE","PRIVACY","REFUNDS_AND_RETURNS","SHIPPING"]},"version":{"type":"integer","format":"int32","minimum":1}},"required":["kind","version"]},"StorefrontCheckoutRequest":{"description":"A storefront checkout, by a signed-in shopper or a guest","properties":{"lines":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCheckoutLine"},"maxItems":100,"minItems":0},"email":{"type":"string","description":"Guests only (required then); a signed-in shopper's order goes to their verified email","maxLength":254,"minLength":0},"customer":{"$ref":"#/components/schemas/StorefrontCheckoutCustomer"},"shipping_address":{"$ref":"#/components/schemas/StorefrontCheckoutAddress"},"billing_address":{"$ref":"#/components/schemas/StorefrontCheckoutAddress"},"delivery":{"type":"string","description":"SHIP (default) or PICKUP, for carts with physical products","enum":["SHIP","PICKUP"]},"payment_method":{"type":"string","description":"STRIPE or MONTONIO: a payment_method from the cart quote's payment_options (ADR 105). Omitted: Stripe, or the store's Montonio when Stripe can't take payments","enum":["STRIPE","MONTONIO"]},"montonio_method":{"type":"string","description":"MONTONIO only, and then required: the option's montonio_method","example":"paymentInitiation","maxLength":32,"minLength":0},"montonio_bank":{"type":"string","description":"MONTONIO bank payments only, optional: a bank code from the option's banks","maxLength":32,"minLength":0},"pickup_point_id":{"type":"string","description":"For a shipping option with requires_pickup_point (ADR 105), and then required: the pickup point the shopper chose, from GET /storefront/v1/shipping/pickup-points","maxLength":64,"minLength":0},"shipping_option_id":{"type":"string","description":"An id from the cart quote's shipping_options; required to ship physical products","maxLength":255,"minLength":0},"discount_code":{"type":"string","maxLength":64,"minLength":0},"accepts_marketing":{"type":"boolean","description":"Email me news and offers"},"note":{"type":"string","maxLength":1000,"minLength":0},"agent_source":{"type":"string","description":"The AI assistant that sent the shopper (ADR 54), from the storefront's own attribution (utm_source or referrer); omitted otherwise","enum":["CHATGPT","GEMINI","PERPLEXITY","COPILOT","CLAUDE","OTHER"]},"link_id":{"type":"string","description":"The Linkly page the shopper came from (the storefront's link=\u003cid\u003e query parameter, ADR 57). Recorded on the order when it is one of the store's pages, and the order's channel is then LINKLY; anything else is ignored, never an error","maxLength":255,"minLength":0},"analytics_visitor_id":{"type":"string","description":"The analytics visitor id the storefront sends with its events (ADR 87); stored only as a hash, never refuses the checkout. Send it with analytics_session_id, or neither: without them the order is tied to the day's cookieless visitor from Shopemaa-Visitor-Ip and -User-Agent.","maxLength":64,"minLength":0},"analytics_session_id":{"type":"string","description":"The analytics session id, sent with analytics_visitor_id","maxLength":64,"minLength":0},"accepted_policies":{"type":"array","description":"The policy versions the storefront showed; omitted: the current ones are recorded","items":{"$ref":"#/components/schemas/AcceptedPolicyInput"},"maxItems":10,"minItems":0}}},"StorefrontDownloadLink":{"type":"object","description":"A download link; any earlier link stops working","properties":{"download_url":{"type":"string"}}},"PolicyRef":{"description":"A store policy at one version, without its text","properties":{"kind":{"type":"string","enum":["TERMS_OF_SALE","PRIVACY","REFUNDS_AND_RETURNS","SHIPPING"]},"title":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","description":"Storefront path of this version, /policies/\u003cslug\u003e?version=\u003cn\u003e; the text is at GET /v1/storefront/policies/\u003cslug\u003e?version=\u003cn\u003e"},"version":{"type":"integer","format":"int32"}}},"OrderLine":{"description":"A line of an order, snapshotted at checkout","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_variant_id":{"type":"string"},"product_name":{"type":"string"},"sku":{"type":"string"},"fulfilment_type":{"type":"string","enum":["PHYSICAL","DIGITAL"]},"unit_price":{"type":"integer","format":"int64","description":"Price charged per unit, after any sale"},"list_unit_price":{"type":"integer","format":"int64","description":"Price per unit before any sale; equals unit_price without one"},"quantity":{"type":"integer","format":"int32"},"line_total":{"type":"integer","format":"int64"},"discount_amount":{"type":"integer","format":"int64","description":"This line's share of the discount code; the line cost line_total - discount_amount"},"backordered_quantity":{"type":"integer","format":"int32","description":"Units sold beyond the stock available at checkout (to send once restocked)"},"options":{"type":"array","items":{"$ref":"#/components/schemas/OrderLineOption"}},"licence":{"$ref":"#/components/schemas/OrderLineLicence"},"digital_version_id":{"type":"string","description":"Digital lines: the product's current version at checkout"}}},"OrderLineLicence":{"description":"The licence revision an order line bought, for the receipt","properties":{"licence_id":{"type":"string"},"revision_id":{"type":"string"},"revision":{"type":"integer","format":"int32"},"name":{"type":"string"},"seats":{"type":"integer","format":"int32"},"updates":{"type":"string","enum":["ALL_FUTURE","TWELVE_MONTHS","THIS_VERSION"]},"summary":{"type":"string"}}},"OrderLineOption":{"description":"An option selected for an order line","properties":{"option_group_id":{"type":"string"},"option_value_id":{"type":"string"},"group_name":{"type":"string"},"selected_value":{"type":"string"},"price_delta":{"type":"integer","format":"int64"}}},"OrderShippingAddress":{"description":"Delivery address snapshotted at checkout","properties":{"name":{"type":"string"},"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"region":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"},"phone":{"type":"string"}}},"ResOrder":{"type":"object","properties":{"id":{"type":"string"},"order_number":{"type":"integer","format":"int64","description":"Per-store order number shown to people, e.g. 1042 for #1042"},"currency":{"type":"string"},"subtotal":{"type":"integer","format":"int64"},"discount_total":{"type":"integer","format":"int64","description":"What the discount code took off: the lines' discount_amount plus shipping_discount. grand_total = subtotal + shipping_total + tax_total - discount_total"},"shipping_discount":{"type":"integer","format":"int64","description":"The shipping part of discount_total"},"discount_code":{"type":"string","description":"The discount code used at checkout (upper case); null without one"},"discount_kind":{"type":"string","enum":["PERCENTAGE","FIXED","PERCENTAGE_CAPPED","FREE_SHIPPING"]},"tax_total":{"type":"integer","format":"int64"},"shipping_total":{"type":"integer","format":"int64"},"grand_total":{"type":"integer","format":"int64"},"order_status":{"type":"string","enum":["PENDING","CONFIRMED","COMPLETED","CANCELLED"]},"payment_status":{"type":"string","enum":["PENDING","PAID","FAILED","REFUNDED","CANCELLED","EXPIRED","DUE"]},"payment_method":{"type":"string","description":"STRIPE (paid online), PAY_LATER (the customer pays the store later, ADR 34) or IN_PERSON (paid to staff at the point of sale, ADR 100)","enum":["STRIPE","PAY_LATER","IN_PERSON","MONTONIO"]},"in_person_tender":{"type":"string","description":"IN_PERSON: how staff were paid (CASH, CARD on the store's own terminal, OTHER); null otherwise","enum":["CASH","CARD","OTHER"]},"in_person_reference":{"type":"string","description":"IN_PERSON: staff's reference for the payment; null without one"},"cash_received":{"type":"integer","format":"int64","description":"CASH sales at the point of sale: the cash the customer handed over; null when not recorded"},"change_given":{"type":"integer","format":"int64","description":"CASH sales: the change given back, cash_received - grand_total; null when no cash was recorded"},"placed_by":{"type":"string","description":"The staff member (user id) who placed the order at the point of sale; null for orders customers placed themselves"},"payment_due_at":{"type":"string","format":"date-time","description":"Pay later: when the order must be paid by; null without payment terms"},"amount_received":{"type":"integer","format":"int64","description":"Pay later: money staff recorded against the order so far; 0 for Stripe orders"},"balance_due":{"type":"integer","format":"int64","description":"What the order still owes (payment_status DUE); 0 otherwise"},"overdue":{"type":"boolean","description":"Pay later: still owed after its due date"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time"},"cancelled_at":{"type":"string","format":"date-time"},"cancellation_reason":{"type":"string"},"customer_id":{"type":"string"},"store_customer_id":{"type":"string","description":"The store's customer record (GET /customers/{id}); null on orders without one"},"customer_email":{"type":"string","description":"Customer email as known at checkout; null on older orders"},"customer_name":{"type":"string","description":"Customer name from the shipping address; null for digital-only and older orders"},"customer_note":{"type":"string","description":"The note the customer left at checkout; null without one"},"fulfilment_status":{"type":"string","enum":["NOT_REQUIRED","UNFULFILLED","SHIPPED","DELIVERED"]},"sales_channel":{"type":"string","description":"Where the order was placed: ONLINE_STORE, CHECKOUT_EMBED, LINKLY, API or POS (the point of sale, ADR 100)","enum":["ONLINE_STORE","CHECKOUT_EMBED","LINKLY","API","POS"]},"agent_source":{"type":"string","description":"The AI assistant that sent the shopper (ADR 54); null otherwise","enum":["CHATGPT","GEMINI","PERPLEXITY","COPILOT","CLAUDE","OTHER"]},"delivery_method":{"type":"string","description":"SHIPPING, PICKUP or IN_STORE (handed over at the point of sale); null for digital-only orders","enum":["SHIPPING","PICKUP","IN_STORE"]},"pickup_address":{"type":"string","description":"Where to collect a PICKUP order; null until the order is paid (or confirmed to pay later)"},"shipping_method":{"type":"string"},"shipping_address":{"$ref":"#/components/schemas/OrderShippingAddress"},"carrier":{"type":"string"},"tracking_number":{"type":"string"},"tracking_link":{"type":"string","description":"The carrier's tracking page, once a Montonio shipment has one (ADR 105)"},"shipping_carrier_code":{"type":"string","description":"The Montonio carrier of the order's shipping rate (omniva, dpd, ...); null for a plain rate"},"shipping_carrier_method":{"type":"string","description":"PICKUP_POINT or COURIER; null for a plain rate","enum":["PICKUP_POINT","COURIER"]},"pickup_point_name":{"type":"string","description":"The pickup point the customer chose; null otherwise"},"pickup_point_address":{"type":"string"},"shipped_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderLine"}},"policies":{"type":"array","description":"The store policy versions the order was placed under (accepted at checkout); empty on orders placed before policies were recorded","items":{"$ref":"#/components/schemas/PolicyRef"}}}},"CustomerLibraryEntry":{"description":"A digital product the customer bought and its download link","properties":{"delivery_id":{"type":"string"},"order_id":{"type":"string"},"order_number":{"type":"integer","format":"int64","description":"Per-store order number, e.g. 1042 for #1042"},"ordered_at":{"type":"string","format":"date-time","description":"When the order was placed"},"paid_at":{"type":"string","format":"date-time"},"order_item_id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","description":"Product name as bought"},"customer_email":{"type":"string","description":"Address the link was issued to"},"version_label":{"type":"string","description":"Version current when the customer bought it (ADR 18), e.g. 2.1; null for orders placed before versions existed"},"licence_name":{"type":"string","description":"Licence the customer bought, with the revision of its terms when later than the first, e.g. \"Studio (revision 2)\"; null for orders placed before licences existed"},"files":{"type":"array","items":{"$ref":"#/components/schemas/CustomerLibraryFile"}},"download_count":{"type":"integer","format":"int32"},"download_limit":{"type":"integer","format":"int32","description":"Downloads allowed; null is unlimited"},"downloads_remaining":{"type":"integer","format":"int32","description":"Downloads left; null is unlimited"},"expires_at":{"type":"string","format":"date-time","description":"End of the access period; null never expires"},"revoked":{"type":"boolean"},"revoked_at":{"type":"string","format":"date-time"},"revoked_by":{"type":"string","description":"Staff user who revoked the link"},"email_sent_at":{"type":"string","format":"date-time","description":"When an email with the link was last queued for the customer (ADR 32)"},"link_reissued_at":{"type":"string","format":"date-time","description":"When staff last re-issued the link (older links stopped working then)"},"issued_at":{"type":"string","format":"date-time","description":"When the link was first issued"},"access_status":{"type":"string","description":"Whether the link works now, and if not, why","enum":["ACTIVE","REVOKED","ORDER_NOT_PAID","EXPIRED","LIMIT_REACHED"]}}},"CustomerLibraryFile":{"description":"A file in a customer's digital delivery","properties":{"id":{"type":"string"},"name":{"type":"string"},"file_name":{"type":"string"},"content_type":{"type":"string"},"file_size":{"type":"integer","format":"int64"}}},"ReqStorefrontEvents":{"description":"Storefront events from one visitor's session","properties":{"visitor_id":{"type":"string","description":"Random id the storefront keeps for this browser once the visitor accepted analytics storage; stored only as a hash. Send it with session_id, or neither: without them the visitor is a daily hash of the address and browser (ADR 86).","pattern":"^[A-Za-z0-9_-]{8,64}$"},"session_id":{"type":"string","description":"Random id for this visit; stored only as a hash. Sent together with visitor_id.","pattern":"^[A-Za-z0-9_-]{8,64}$"},"channel":{"type":"string","description":"ONLINE_STORE (default), CHECKOUT_EMBED or LINKLY; API has no storefront","enum":["ONLINE_STORE","CHECKOUT_EMBED","LINKLY","API","POS"]},"country":{"type":"string","description":"Visitor's country, ISO 3166-1 alpha-2; used when the address can't be located","pattern":"^[A-Za-z]{2}$"},"referrer":{"type":"string","description":"document.referrer; only its host is kept","maxLength":2048,"minLength":0},"utm_source":{"type":"string","description":"utm_source of the landing page; kept lower case","maxLength":255,"minLength":0},"utm_medium":{"type":"string","description":"utm_medium of the landing page; kept lower case","maxLength":255,"minLength":0},"utm_campaign":{"type":"string","description":"utm_campaign of the landing page","maxLength":255,"minLength":0},"events":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontEventRequest"},"maxItems":50,"minItems":0}}},"StorefrontEventRequest":{"description":"One storefront event","properties":{"type":{"type":"string","enum":["SESSION_STARTED","PRODUCT_VIEWED","ADDED_TO_CART","CHECKOUT_STARTED","PAGE_VIEWED","SEARCH_PERFORMED","ORDER_PLACED","LINK_PAGE_VISITED","LINK_BLOCK_CLICKED"]},"product_id":{"type":"string","description":"Required for PRODUCT_VIEWED, optional for ADDED_TO_CART, not allowed otherwise. Events naming a product that isn't on sale in this store are dropped.","maxLength":255,"minLength":0},"path":{"type":"string","description":"The page's path; required for PAGE_VIEWED. Only the path is kept, never the query string or fragment.","maxLength":2048,"minLength":0,"pattern":"^/.*"},"query":{"type":"string","description":"What the visitor searched for; required for SEARCH_PERFORMED, not allowed otherwise","maxLength":200,"minLength":0}},"required":["type"]},"ResStorefrontEventsTracked":{"type":"object","description":"What happened to a batch of storefront events","properties":{"accepted":{"type":"integer","format":"int32","description":"Events stored"},"dropped":{"type":"integer","format":"int32","description":"Events dropped: unknown or unavailable products, or a store with nothing on sale"}}},"ResStorefrontPage":{"type":"object","description":"A published page for the storefront","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","description":"Markdown; render it on the storefront"},"seo_title":{"type":"string"},"seo_description":{"type":"string"},"cover_image_url":{"type":"string"},"published_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ResStorefrontBlogPostList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontBlogPostListItem"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"total_elements":{"type":"integer","format":"int64"},"total_pages":{"type":"integer","format":"int32"},"first":{"type":"boolean"},"last":{"type":"boolean"}}},"StorefrontBlogPostListItem":{"description":"A published post in the blog list: no body","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"excerpt":{"type":"string"},"cover_image_url":{"type":"string"},"author_name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time"}}},"ResStorefrontBlogPost":{"type":"object","description":"A published blog post for the storefront","properties":{"id":{"type":"string"},"title":{"type":"string"},"slug":{"type":"string"},"excerpt":{"type":"string"},"body":{"type":"string","description":"Markdown; render it on the storefront"},"seo_title":{"type":"string"},"seo_description":{"type":"string"},"cover_image_url":{"type":"string"},"author_name":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time"}}},"ResStorefrontStore":{"type":"object","description":"What a storefront needs to render a store, resolved from the host it was opened on","properties":{"organization_id":{"type":"string","description":"The store's id (its organization id); send it as Organization-Id where an endpoint still asks for it"},"handle":{"type":"string"},"store_name":{"type":"string"},"status":{"type":"string","enum":["OPEN","CLOSED"]},"password_protected":{"type":"boolean","description":"Visitors must enter the password first (POST /storefront/v1/store/password)"},"default_language":{"type":"string"},"enabled_languages":{"type":"array","items":{"type":"string"}},"price_display":{"type":"string","enum":["INCLUDING_VAT","EXCLUDING_VAT"]},"out_of_stock_display":{"type":"string","enum":["SHOW_NOTIFY_ME","HIDE"]},"customer_accounts_enabled":{"type":"boolean"},"guest_checkout_enabled":{"type":"boolean","description":"Stored only: checkout still requires a signed-in customer"},"announcement_text":{"type":"string"},"announcement_link":{"type":"string"},"seo_title":{"type":"string"},"seo_description":{"type":"string"},"sharing_image_url":{"type":"string"},"logo_url":{"type":"string","description":"The store's logo; null: show the store name (ADR 69)"},"favicon_url":{"type":"string","description":"The store's browser tab icon; null: the theme's own (ADR 69)"},"primary_host":{"type":"string","description":"The store's canonical host"},"requested_host":{"type":"string","description":"The host that was resolved; null when matched by the Organization-Id fallback"},"matched_by":{"type":"string","description":"How the host matched","enum":["SUBDOMAIN","RETIRED_HANDLE","CUSTOM_DOMAIN","ORGANIZATION_HEADER","APP_KEY","FEED_TOKEN","CHECKOUT_EMBED","LINKLY_PAGE"]},"redirect":{"type":"boolean","description":"The storefront should redirect (301) to primary_host: the host is an old handle, or the subdomain while a custom domain is primary"},"reviews":{"$ref":"#/components/schemas/StorefrontReviewPolicy"}}},"StorefrontReviewMediaLimits":{"description":"What a review may carry; photos and videos are always checked before they appear","properties":{"max_photos":{"type":"integer","format":"int32"},"max_videos":{"type":"integer","format":"int32"},"max_video_seconds":{"type":"integer","format":"int32"},"max_photo_bytes":{"type":"integer","format":"int64"},"max_video_bytes":{"type":"integer","format":"int64"}}},"StorefrontReviewPolicy":{"description":"Whether the store shows reviews and how they are checked","properties":{"enabled":{"type":"boolean"},"moderation":{"$ref":"#/components/schemas/ReviewModeration"},"verification":{"type":"string","description":"VERIFIED_BUYERS: only people who bought and paid for the item can review it"},"media":{"$ref":"#/components/schemas/StorefrontReviewMediaLimits"}}},"StorefrontPickupPoint":{"description":"A parcel locker, parcel shop or post office","properties":{"id":{"type":"string","description":"The checkout's pickup_point_id"},"name":{"type":"string"},"type":{"type":"string","description":"parcelMachine, parcelShop or postOffice"},"street_address":{"type":"string"},"locality":{"type":"string"},"postal_code":{"type":"string"},"address":{"type":"string","description":"One line: street, postal code and place"}}},"StorefrontPickupPoints":{"type":"object","description":"Pickup points of a shipping option","properties":{"pickup_points":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontPickupPoint"}}}},"ProductRating":{"description":"A product's rating from its published reviews; each buyer's latest review counts once","properties":{"average":{"type":"number","description":"Average stars, 1-5, two decimals","example":4.67},"count":{"type":"integer","format":"int32","description":"Reviews counted"},"distribution":{"$ref":"#/components/schemas/RatingDistribution"}}},"RatingDistribution":{"description":"Counted reviews per number of stars","properties":{"one":{"type":"integer","format":"int32"},"two":{"type":"integer","format":"int32"},"three":{"type":"integer","format":"int32"},"four":{"type":"integer","format":"int32"},"five":{"type":"integer","format":"int32"}}},"StorefrontImage":{"description":"A public image with its alt text and pixel size","properties":{"url":{"type":"string"},"alt":{"type":"string","description":"Alt text; null when the merchant gave none"},"width":{"type":"integer","format":"int32","description":"Pixels; null when unknown"},"height":{"type":"integer","format":"int32"}}},"StorefrontProductCard":{"description":"A product in a storefront list","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","description":"PHYSICAL or DIGITAL","enum":["PHYSICAL","DIGITAL"]},"image":{"$ref":"#/components/schemas/StorefrontImage"},"price":{"type":"integer","format":"int64","description":"The cheapest variant's price now, after a sale for everyone; 0 when nothing is on offer"},"list_price":{"type":"integer","format":"int64","description":"That variant's price before the sale; equal to price without a sale"},"currency":{"type":"string","description":"The store currency; null until the merchant sets it"},"price_varies":{"type":"boolean","description":"Variants have different prices: show \"from\""},"available":{"type":"boolean","description":"Some variant can be bought (in stock, untracked or on backorder)"},"badges":{"type":"array","description":"SALE, then at most one of SOLD_OUT, LOW_STOCK or BACKORDER","items":{"type":"string","description":"SALE, then at most one of SOLD_OUT, LOW_STOCK or BACKORDER","enum":["SALE","SOLD_OUT","LOW_STOCK","BACKORDER"]}},"digital_kind":{"type":"string","description":"Digital products: DOWNLOAD or TEMPLATE (ADR 73); null for physical ones","enum":["DOWNLOAD","TEMPLATE"]},"rating":{"$ref":"#/components/schemas/ProductRating"}}},"StorefrontSectionProducts":{"type":"object","description":"The products of a theme's dynamic section, in order","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductCard"}}}},"StorefrontSearch":{"type":"object","description":"Search results: a few products, pages, posts and policies","properties":{"query":{"type":"string"},"products":{"type":"array","description":"Products whose title contains the words, newest first","items":{"$ref":"#/components/schemas/StorefrontProductCard"}},"pages":{"type":"array","description":"Published pages whose title or slug contains them","items":{"$ref":"#/components/schemas/StorefrontSearchPage"}},"posts":{"type":"array","description":"Live blog posts whose title or slug contains them, newest first","items":{"$ref":"#/components/schemas/StorefrontSearchPost"}},"policies":{"type":"array","description":"Store policies that match (only with semantic search)","items":{"$ref":"#/components/schemas/StorefrontSearchPolicy"}},"semantic":{"type":"boolean","description":"True when the store search index ranked these by meaning (ADR 76); false for the title match, in which every list is ordered as described"}}},"StorefrontSearchPage":{"description":"A published page found by a search","properties":{"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"type":"string","description":"The passage that matched; null for the title match"}}},"StorefrontSearchPolicy":{"description":"A store policy found by a search","properties":{"slug":{"type":"string","description":"Its storefront path is /policies/\u003cslug\u003e"},"title":{"type":"string"},"excerpt":{"type":"string","description":"The passage that matched"}}},"StorefrontSearchPost":{"description":"A live blog post found by a search","properties":{"slug":{"type":"string"},"title":{"type":"string"},"excerpt":{"type":"string"},"published_at":{"type":"string","format":"date-time"}}},"ReviewRequest":{"type":"object","description":"What a review link opens: the order's items still open for review and the reviews already written for it","properties":{"order_number":{"type":"integer","format":"int64"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ReviewableItem"}},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/ShopperReview"}},"expires_at":{"type":"string","format":"date-time","description":"The link stops working then"}}},"ReviewableItem":{"properties":{"order_item_id":{"type":"string"},"order_id":{"type":"string"},"order_number":{"type":"integer","format":"int64"},"product_id":{"type":"string"},"product_slug":{"type":"string","description":"Null when the product is no longer on sale"},"product_name":{"type":"string"},"variant_label":{"type":"string"},"image_url":{"type":"string","description":"The product's primary image; null without one"},"bought_at":{"type":"string","format":"date-time"},"review_by":{"type":"string","format":"date-time","description":"The last moment it can be reviewed"}}},"StorefrontProductList":{"type":"object","description":"A page of storefront products","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontProductCard"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"total_elements":{"type":"integer","format":"int64"},"total_pages":{"type":"integer","format":"int32"},"first":{"type":"boolean"},"last":{"type":"boolean"}}},"StorefrontCategoryRef":{"description":"The category the product is in","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"}}},"StorefrontCollectionRef":{"description":"A collection the product is in","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"}}},"StorefrontDigitalDetails":{"description":"What a digital product is: a download or a template","properties":{"kind":{"type":"string","description":"DOWNLOAD or TEMPLATE","enum":["DOWNLOAD","TEMPLATE"]},"made_for":{"type":"string","description":"TEMPLATE only: what it is made for; null otherwise","enum":["CODE_PROJECT","FIGMA_FILE","NOTION_TEMPLATE","WEBSITE_THEME","SPREADSHEET","OTHER"]},"works_with":{"type":"array","description":"What it works with, e.g. \"Next.js 15\"","items":{"type":"string","description":"What it works with, e.g. \"Next.js 15\""}},"demo_url":{"type":"string","description":"A live demo (https) the merchant chose to show; null otherwise. Link to it with rel=\"noopener noreferrer\""}}},"StorefrontLicence":{"description":"A licence of a digital product","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string","description":"Plain-English summary of the rights"},"price":{"type":"integer","format":"int64"},"list_price":{"type":"integer","format":"int64"},"is_default":{"type":"boolean"}}},"StorefrontProduct":{"type":"object","description":"A product page on the storefront","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"type":{"type":"string","description":"PHYSICAL or DIGITAL","enum":["PHYSICAL","DIGITAL"]},"description":{"type":"string","description":"Markdown as the merchant wrote it; render it safely"},"currency":{"type":"string","description":"The store currency; null until the merchant sets it"},"price":{"type":"integer","format":"int64","description":"The cheapest variant's price now"},"list_price":{"type":"integer","format":"int64"},"price_varies":{"type":"boolean"},"available":{"type":"boolean"},"badges":{"type":"array","items":{"type":"string","enum":["SALE","SOLD_OUT","LOW_STOCK","BACKORDER"]}},"media":{"type":"array","description":"Images and videos in display order; the first image is the primary one","items":{"$ref":"#/components/schemas/StorefrontProductMedia"}},"options":{"type":"array","description":"The options variants differ by, e.g. Size: S, M, L, in the order they first appear","items":{"$ref":"#/components/schemas/StorefrontProductOption"}},"variants":{"type":"array","description":"Variants on offer, sold-out ones included (OUT_OF_STOCK); for a digital product, one per ACTIVE licence","items":{"$ref":"#/components/schemas/StorefrontProductVariant"}},"licences":{"type":"array","description":"Digital products: the ACTIVE licences in the merchant's order; empty otherwise","items":{"$ref":"#/components/schemas/StorefrontLicence"}},"sale":{"$ref":"#/components/schemas/StorefrontSale"},"collections":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCollectionRef"}},"seo":{"$ref":"#/components/schemas/StorefrontSeo"},"pickup_available":{"type":"boolean","description":"Free local pickup can be chosen for it (a physical product that allows it, in a store with a pickup address)"},"brand":{"type":"string","description":"The brand (ADR 54); null when not set"},"condition":{"type":"string","description":"NEW, REFURBISHED or USED (ADR 54)","enum":["NEW","REFURBISHED","USED"]},"category":{"$ref":"#/components/schemas/StorefrontCategoryRef"},"digital":{"$ref":"#/components/schemas/StorefrontDigitalDetails"},"rating":{"$ref":"#/components/schemas/ProductRating"}}},"StorefrontProductMedia":{"description":"An image or video of a product","properties":{"id":{"type":"string"},"type":{"type":"string","description":"IMAGE or VIDEO","enum":["IMAGE","VIDEO","DOCUMENT"]},"url":{"type":"string"},"alt":{"type":"string"},"width":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"}}},"StorefrontProductOption":{"description":"An option variants differ by, with its values","properties":{"name":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}}},"StorefrontProductVariant":{"description":"A variant a shopper can choose","properties":{"id":{"type":"string"},"sku":{"type":"string"},"title":{"type":"string","description":"Its option values joined, or the licence name; null for a product's only variant"},"options":{"type":"object","additionalProperties":{"type":"string","description":"Option name to value, e.g. {\"Size\": \"M\"}"},"description":"Option name to value, e.g. {\"Size\": \"M\"}"},"price":{"type":"integer","format":"int64"},"list_price":{"type":"integer","format":"int64"},"availability":{"type":"string","enum":["IN_STOCK","LOW_STOCK","OUT_OF_STOCK","BACKORDER"]},"image_media_id":{"type":"string","description":"The variant's own image (one of media); null shows the primary image"},"image_url":{"type":"string"},"licence_id":{"type":"string","description":"The licence this variant sells (digital); null otherwise"},"gtin":{"type":"string","description":"GTIN (EAN/UPC/ISBN) for structured data (ADR 54); null when not set"},"mpn":{"type":"string","description":"Manufacturer part number (ADR 54); null when not set"}}},"StorefrontSale":{"description":"A sale for everyone running now","properties":{"mode":{"type":"string","enum":["NONE","PERCENT","FIXED","BOTH"]},"percent_off":{"type":"integer","format":"int32"},"amount_off":{"type":"integer","format":"int64","description":"Minor units off each unit (FIXED), or the cap (BOTH)"},"ends_at":{"type":"string","format":"date-time","description":"When it ends; null when it doesn't"}}},"StorefrontSeo":{"description":"Title and description for search engines","properties":{"title":{"type":"string"},"description":{"type":"string"}}},"ReviewSort":{"type":"string","description":"NEWEST (default), HIGHEST or LOWEST rating first","enum":["NEWEST","HIGHEST","LOWEST"]},"StorefrontReview":{"description":"A published review; text is plain and must be escaped","properties":{"id":{"type":"string"},"rating":{"type":"integer","format":"int32"},"title":{"type":"string"},"body":{"type":"string"},"author_name":{"type":"string","description":"First name and last initial"},"variant_label":{"type":"string","description":"What was bought, e.g. \"M / Blue\"; null without options"},"verified_purchase":{"type":"boolean","description":"Always true: every review comes from a paid order line"},"published_at":{"type":"string","format":"date-time"},"edited":{"type":"boolean","description":"The reviewer changed it after writing"},"reply":{"$ref":"#/components/schemas/StorefrontReviewReply"},"media":{"type":"array","description":"Approved photos and videos, in the writer's order","items":{"$ref":"#/components/schemas/StorefrontReviewMedia"}}}},"StorefrontReviewList":{"type":"object","description":"A page of a product's published reviews with its rating","properties":{"rating":{"$ref":"#/components/schemas/ProductRating"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontReview"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"total_elements":{"type":"integer","format":"int64"},"total_pages":{"type":"integer","format":"int32"},"first":{"type":"boolean"},"last":{"type":"boolean"}}},"StorefrontReviewMedia":{"description":"An approved photo or video of a published review","properties":{"id":{"type":"string"},"kind":{"$ref":"#/components/schemas/ReviewMediaKind"},"url":{"type":"string"},"poster_url":{"type":"string","description":"A video's still image, for its player's poster; null for photos"},"width":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"duration_ms":{"type":"integer","format":"int32","description":"A video's length; null for photos"}}},"StorefrontReviewReply":{"description":"The store's public reply; null without one","properties":{"text":{"type":"string"},"replied_at":{"type":"string","format":"date-time"}}},"StorefrontReviewGallery":{"type":"object","description":"Customers' approved photos and videos of a product, newest review first","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontReviewGalleryItem"}}}},"StorefrontReviewGalleryItem":{"properties":{"review_id":{"type":"string"},"rating":{"type":"integer","format":"int32"},"author_name":{"type":"string"},"media":{"$ref":"#/components/schemas/StorefrontReviewMedia"}}},"StorefrontCollection":{"type":"object","description":"A store collection","properties":{"id":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","description":"As the merchant wrote it; null without one"},"product_count":{"type":"integer","format":"int64","description":"Products the storefront lists in it (ACTIVE; without sold-out ones when the store hides them)"}}},"StorefrontCollectionList":{"type":"object","description":"The store's collections by title","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCollection"}}}},"CheckoutHandoffLine":{"description":"A cart line: a variant and/or a digital licence","properties":{"variant_id":{"type":"string"},"licence_id":{"type":"string"},"quantity":{"type":"integer","format":"int32"}}},"ResCheckoutHandoff":{"type":"object","description":"A cart an AI assistant built (ADR 55): put these lines in the shopper's cart and show it. Prices and availability come from the cart quote, never from here.","properties":{"id":{"type":"string"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutHandoffLine"}},"discount_code":{"type":"string","description":"A discount code to apply; null without one"},"agent_source":{"type":"string","description":"The assistant that built the cart, for attribution; null when unknown","enum":["CHATGPT","GEMINI","PERPLEXITY","COPILOT","CLAUDE","OTHER"]},"expires_at":{"type":"string","format":"date-time"}}},"StorefrontCategory":{"type":"object","description":"A store category","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"product_count":{"type":"integer","format":"int64","description":"Products the storefront lists in it (ACTIVE; without sold-out ones when the store hides them)"}}},"StorefrontCategoryList":{"type":"object","description":"The store's categories by name","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/StorefrontCategory"}}}},"ShopperReviewList":{"type":"object","description":"A page of the shopper's own reviews","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ShopperReview"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"total_elements":{"type":"integer","format":"int64"},"total_pages":{"type":"integer","format":"int32"},"first":{"type":"boolean"},"last":{"type":"boolean"}}},"ReviewableItems":{"type":"object","description":"Items the shopper bought that can be reviewed now, newest first","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ReviewableItem"}}}},"OrderSummary":{"description":"An order in a list","properties":{"id":{"type":"string"},"order_number":{"type":"integer","format":"int64","description":"Per-store order number shown to people, e.g. 1042 for #1042"},"customer_id":{"type":"string"},"customer_email":{"type":"string","description":"Customer email as known at checkout; null on older orders"},"customer_name":{"type":"string","description":"Customer name from the shipping address; null for digital-only and older orders"},"currency":{"type":"string"},"grand_total":{"type":"integer","format":"int64"},"total_items":{"type":"integer","format":"int32","description":"Total quantity across all order lines"},"order_status":{"type":"string","enum":["PENDING","CONFIRMED","COMPLETED","CANCELLED"]},"payment_status":{"type":"string","enum":["PENDING","PAID","FAILED","REFUNDED","CANCELLED","EXPIRED","DUE"]},"payment_method":{"type":"string","description":"STRIPE, PAY_LATER or IN_PERSON (paid at the point of sale, ADR 100)","enum":["STRIPE","PAY_LATER","IN_PERSON","MONTONIO"]},"sales_channel":{"type":"string","description":"Where the order was placed: ONLINE_STORE, CHECKOUT_EMBED, LINKLY, API or POS","enum":["ONLINE_STORE","CHECKOUT_EMBED","LINKLY","API","POS"]},"balance_due":{"type":"integer","format":"int64","description":"What the order still owes (pay later, payment_status DUE); 0 otherwise"},"overdue":{"type":"boolean","description":"Pay later: owed past its due date"},"fulfilment_status":{"type":"string","enum":["NOT_REQUIRED","UNFULFILLED","SHIPPED","DELIVERED"]},"created_at":{"type":"string","format":"date-time"},"paid_at":{"type":"string","format":"date-time"}}},"ResOrderList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"total_pages":{"type":"integer","format":"int32"},"total_elements":{"type":"integer","format":"int64"},"first":{"type":"boolean"},"last":{"type":"boolean"}}},"ResCustomerLibraryList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CustomerLibraryEntry"}},"page":{"type":"integer","format":"int32"},"size":{"type":"integer","format":"int32"},"total_pages":{"type":"integer","format":"int32"},"total_elements":{"type":"integer","format":"int64"},"first":{"type":"boolean"},"last":{"type":"boolean"}}},"StorefrontAddressList":{"type":"object","description":"The shopper's saved addresses","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ResCustomerAddress"}}}}},"securitySchemes":{"appKey":{"type":"apiKey","in":"header","name":"Shopemaa-App-Key","description":"The storefront's App key, or a storefront API key from Settings › Developers. A server-side secret that selects the key's store whatever the host. Required for checkout, order status and shopper accounts."},"customerToken":{"type":"apiKey","in":"header","name":"Customer-Token","description":"A signed-in shopper's session token, from POST /storefront/v1/customers/login. Omit it for a guest."}}}}