{"openapi":"3.1.0","info":{"title":"Storeware API","version":"1","description":"The API Storeware apps call with the token a shop gave them. Each call needs every permission it lists under `x-storeware-scopes`; a `:write` permission covers its `:read`. A call marked `x-storeware-app-only` is one an app makes about itself, and answers only an app’s token."},"servers":[{"url":"https://api.storeware.ai"}],"security":[{"bearer":[]}],"tags":[{"name":"Products","description":"The catalogue: products, their media and their fields."},{"name":"Variants","description":"The versions of a product a shopper buys, and their options."},{"name":"Collections","description":"Groups of products, set by hand or by rules."},{"name":"Inventory","description":"Stock at each location, and the locations themselves."},{"name":"Shipping","description":"The groups a shop sorts its goods into for delivery."},{"name":"Orders","description":"Orders, their payments, fulfillments, refunds and changes."},{"name":"Payments","description":"What the shop holds, and the money sent to its bank."},{"name":"Customers","description":"The shop’s customers and what is kept about them."},{"name":"Metafields","description":"The typed fields a shop and its apps keep on records."},{"name":"App billing","description":"What a shop pays your app: plans, one time charges and use."},{"name":"App settings","description":"What a merchant set for your app, and pictures your components show."},{"name":"App automations","description":"Triggers your app fires into a shop’s automations, and the menu they are built from."}],"paths":{"/api/v1/stores/{storeId}/products":{"get":{"operationId":"listProducts","summary":"List products","description":"A page of the catalogue, newest first unless `sort` says otherwise. Archived products are left out unless `status` asks for them or `ids` names them. `meta.total` counts every match.","tags":["Products"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only products in this state.","schema":{"type":"string","enum":["draft","active","archived"]}},{"name":"search","in":"query","required":false,"description":"Words in the title, handle or vendor, or a SKU.","schema":{"type":"string"}},{"name":"ids","in":"query","required":false,"description":"Comma separated product ids, 100 at most: these and no others, in any state.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Newest first when not given. An order it does not know is ignored.","schema":{"type":"string","enum":["created_desc","created_asc","updated_desc","updated_asc","title_asc","title_desc"]}},{"name":"limit","in":"query","required":false,"description":"How many to return, up to 250. Fifty when not given, or every product `ids` names.","schema":{"type":"integer","minimum":1,"maximum":250}},{"name":"offset","in":"query","required":false,"description":"How many to skip, for the next page.","schema":{"type":"integer","minimum":0}},{"name":"filter","in":"query","required":false,"description":"Only the products one figure counts: `out_of_stock`, `never_read`, or `sold_30d` (needs `analytics:read`). One it does not know is ignored.","schema":{"type":"string","enum":["out_of_stock","never_read","sold_30d"]}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductRow"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"How many match, across every page."}},"required":["total"]}},"required":["data","meta"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createProduct","summary":"Create a product","description":"Makes a variant for every combination of the options, or one variant when there are none, and gives each the `price`. It is a draft unless `status` says otherwise, and its handle comes from the title when none is given. Up to 3 options and 200 variants (`too_many_variants`).","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"handle":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-z0-9][a-z0-9-]*$"},"description":{"type":"string","maxLength":50000},"status":{"default":"draft","type":"string","enum":["draft","active","archived"]},"productType":{"type":"string","maxLength":200},"vendor":{"type":"string","maxLength":200},"tags":{"default":[],"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"options":{"default":[],"maxItems":3,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"values":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}}},"required":["name","values"]}},"price":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]}},"required":["title"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/figures":{"get":{"operationId":"getProductFigures","summary":"Count the catalogue","description":"Four figures over the catalogue, leaving out archived products: drafts, out of stock, never read by the shop, and sold in the last thirty days. Each but the first counts what the list’s matching `filter` returns.","tags":["Products"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductFigures"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/{productId}":{"get":{"operationId":"getProduct","summary":"Get a product","description":"The product with its options, its variants and each variant’s prices.","tags":["Products"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateProduct","summary":"Update a product","description":"Changes only the fields sent, and a null empties a field that may be empty. A new `handle` leaves a redirect from the old address. Variants, options and images have calls of their own.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"handle":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[a-z0-9][a-z0-9-]*$"},"description":{"anyOf":[{"type":"string","maxLength":50000},{"type":"null"}]},"status":{"type":"string","enum":["draft","active","archived"]},"productType":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"vendor":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"tags":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"seoTitle":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"seoDescription":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"isGiftCard":{"type":"boolean"},"pinnedCopy":{"maxItems":1,"type":"array","items":{"type":"string","enum":["description"]}}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"archiveProduct","summary":"Archive a product","description":"Archives the product rather than deleting it, so past orders still point at it. Its `status` becomes `archived` and lists leave it out. Archiving it again answers `product_not_found`.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"responses":{"204":{"description":"Done, with nothing to send back."},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/{productId}/sales":{"get":{"operationId":"getProductSales","summary":"Get a product’s sales by day","description":"Units of this product ordered on each of the last 30 days, oldest first and today last, counting orders that are still sales.","tags":["Products"],"x-storeware-scopes":["products:read","analytics:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductSales"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/{productId}/duplicate":{"post":{"operationId":"duplicateProduct","summary":"Copy a product","description":"Makes a draft copy with the same words, options, variants, prices, pictures, custom data, translations and manual collections. SKUs and barcodes are left empty and stock starts at zero. Reviews, sales history, subscription plans and download files stay with the original. Send an `Idempotency-Key` so that a retry makes one copy.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/{productId}/media":{"get":{"operationId":"listProductMedia","summary":"List a product’s images","description":"The product’s gallery in order, each image with its address. The first is the cover.","tags":["Products"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductMedia"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addProductMedia","summary":"Add an image to a product","description":"Puts an image already uploaded to the shop at the end of the product’s gallery, and answers with the whole gallery. Adding one already there changes nothing.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"type":"string","format":"uuid","description":"An image uploaded to the shop."}},"required":["mediaId"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductMedia"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/{productId}/media/order":{"post":{"operationId":"reorderProductMedia","summary":"Reorder a product’s images","description":"Takes the whole gallery as a list of image ids, the cover first. Ids not on the product are ignored, and images left out keep their order behind the rest.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Every image, in the order wanted."}},"required":["mediaIds"]}}}},"responses":{"204":{"description":"Done, with nothing to send back."},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/{productId}/options":{"post":{"operationId":"addProductOption","summary":"Add an option to a product","description":"Adds an option such as Colour, with the value every existing variant takes: each variant’s title gains that value and nothing else changes. Add more values with `addOptionValue`. Refused with `option_name_taken` for a name the product already has, and `option_not_addable` when it has 3 options.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"description":"The option, such as `Colour`."},"value":{"type":"string","minLength":1,"maxLength":200,"description":"What every variant the product already has is in it: `Navy`."}},"required":["name","value"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/options/{optionId}":{"patch":{"operationId":"renameOption","summary":"Rename an option","description":"Changes an option’s name. Variant titles are made of values alone, so none of them change. Answers with the whole product.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"optionId","in":"path","required":true,"description":"The option.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80}},"required":["name"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addOptionValue","summary":"Add a value to an option","description":"Adds the value, and a variant for it with each combination of the other options. The new variants copy their prices from the variant that differs only in this option, and start with no stock. Up to 50 values and 200 variants. Answers with the whole product.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"optionId","in":"path","required":true,"description":"The option.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":200,"description":"Such as `XL`."}},"required":["value"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/option-values/{optionValueId}":{"patch":{"operationId":"renameOptionValue","summary":"Rename an option value","description":"Changes a value’s wording and retitles the variants that carry it, except one whose title was set by hand. Answers with the whole product.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"optionValueId","in":"path","required":true,"description":"The option value.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":200}},"required":["value"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeOptionValue","summary":"Remove an option value","description":"Deletes the value and every variant that carries it, stock included. Refused with `option_value_sold` when any of those variants is on an order, and `last_option_value` for an option’s only value. Answers with the whole product.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"optionValueId","in":"path","required":true,"description":"The option value.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/listings":{"get":{"operationId":"listListings","summary":"Get several listings","description":"Up to 24 products by id, in the order asked, each with its price in the shop’s currency and its first pictures. An id that is not one of the shop’s products is left out rather than refused, and with no `ids` the list is empty.","tags":["Products"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"ids","in":"query","required":false,"description":"Comma separated product ids, 24 at most.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createListing","summary":"Create a listing","description":"Makes a product with one variant, its pictures, a price and a count, then puts it on sale last when `status` is `active`, so a shopper never meets it half made. Refused before anything is written with `listing_needs_price` (on sale with no price) or `listing_needs_shelf` (a count in a shop with no location of its own).","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":50000},"productType":{"type":"string","maxLength":200},"mediaIds":{"default":[],"maxItems":30,"type":"array","items":{"type":"string","format":"uuid"}},"price":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"stock":{"anyOf":[{"type":"object","properties":{"onHand":{"type":"integer","minimum":0,"maximum":10000000}},"required":["onHand"]},{"type":"object","properties":{"madeToOrder":{"type":"boolean","const":true}},"required":["madeToOrder"]}]},"status":{"default":"draft","type":"string","enum":["draft","active"]}},"required":["title"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductDetail"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/prices":{"post":{"operationId":"changeProductPrices","summary":"Change many prices at once","description":"One rule across up to 250 products, in the shop’s own currency: a new price, a percentage up or down, or an amount up or down, with an optional `endIn` (99 for .99). Without `apply` nothing is written and every variant’s price before and after comes back. With `apply: true` they are written together, each kept in the variant’s price history as a bulk change. A \"was\" price the new price reaches is removed. Refused whole, with nothing written, when any price would come to nothing or less (`bulk_price_refused`).","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productIds":{"minItems":1,"maxItems":250,"type":"array","items":{"type":"string","format":"uuid"}},"rule":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"set"},"amount":{"type":"integer","exclusiveMinimum":0}},"required":["kind","amount"]},{"type":"object","properties":{"kind":{"type":"string","const":"percent"},"by":{"type":"number","minimum":-95,"maximum":1000}},"required":["kind","by"]},{"type":"object","properties":{"kind":{"type":"string","const":"amount"},"by":{"type":"integer"}},"required":["kind","by"]}]},"endIn":{"type":"integer","minimum":0},"apply":{"default":false,"type":"boolean"}},"required":["productIds","rule"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"currency":{"type":"string"},"changed":{"type":"integer","description":"How many prices moved, or would."},"applied":{"type":"boolean"},"rows":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string"},"productId":{"type":"string"},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"before":{"type":"integer"},"after":{"type":"integer"},"compareAtBefore":{"anyOf":[{"type":"integer"},{"type":"null"}]},"compareAtAfter":{"anyOf":[{"type":"integer"},{"type":"null"}]},"refused":{"type":"string","enum":["not_positive"]}},"required":["variantId","productId","productTitle","variantTitle","before","after","compareAtBefore","compareAtAfter"]}}},"required":["currency","changed","applied","rows"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/listings/settle":{"post":{"operationId":"settleListings","summary":"Price and publish several listings","description":"Names, prices and counts up to 24 products of one variant each, and puts on sale those marked `publish`. Each entry is done on its own and one refusal does not stop the rest, so read every outcome rather than taking a 200 as all done. An entry is refused with `listing_needs_price`, `listing_needs_shelf` or `listing_has_options`.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"minItems":1,"maxItems":24,"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"title":{"type":"string","minLength":1,"maxLength":300},"price":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},"stock":{"anyOf":[{"type":"object","properties":{"onHand":{"type":"integer","minimum":0,"maximum":10000000}},"required":["onHand"]},{"type":"object","properties":{"madeToOrder":{"type":"boolean","const":true}},"required":["madeToOrder"]}]},"publish":{"default":false,"type":"boolean"}},"required":["productId"]}}},"required":["entries"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","format":"uuid"},"status":{"anyOf":[{"type":"string","enum":["draft","active","archived"]},{"type":"null"}],"description":"What it is now, whether or not everything asked was done. Null if never read."},"ok":{"type":"boolean"},"error":{"description":"Why not, when `ok` is false.","type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["productId","status","ok"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/search/as-ai-shopper":{"post":{"operationId":"searchAsAiShopper","summary":"Search as an AI shopper","description":"Answers a question the way the shop answers an AI shopper: only live products, in the order one is given them, with what the shop understood the question to mean. Nothing is recorded as a question the shop was asked. Each shop may try 10 questions a minute and 60 an hour, counted together for everybody on it. Past that it answers 429 `rate_limited`, with `Retry-After` saying how many seconds to wait.","tags":["Products"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":300,"description":"The question, as an AI shopper might ask it."},"limit":{"description":"How many products. 8 unless said.","type":"integer","minimum":1,"maximum":12}},"required":["query"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer","description":"1 for the first product an AI shopper is shown."},"productId":{"type":"string"},"title":{"type":"string"},"handle":{"type":"string"},"price":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"In minor units, read live."},"currency":{"type":"string"},"available":{"type":"integer","description":"How many can be bought now."},"purchasable":{"type":"boolean"},"image":{"anyOf":[{"type":"object","properties":{"url":{"type":"string"},"alt":{"type":["string","null"]}},"required":["url","alt"]},{"type":"null"}]}},"required":["rank","productId","title","handle","price","currency","available","purchasable","image"]}},"understood":{"type":"object","properties":{"query":{"type":"string","description":"The need, with the parts read as filters taken out."},"maxPrice":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"A ceiling it read, in minor units."},"minPrice":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"A floor it read, in minor units."},"requiredAttributes":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]}}},"required":["query","maxPrice","minPrice","requiredAttributes"]},"currency":{"type":"string"},"filtered":{"type":"integer","description":"Found and then left out, usually for price or stock."},"degraded":{"type":"boolean","description":"True when the question could not be read and this is a plain match."}},"required":["results","understood","currency","filtered","degraded"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/{productId}/metafields":{"get":{"operationId":"listProductMetafields","summary":"List a product’s metafields","description":"Every metafield value set on a product, each with its definition.","tags":["Products"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setProductMetafields","summary":"Set a product’s metafields","description":"Sets up to 25 values in one call. A null value clears its field; keys not named are left alone. An app may set only the fields its manifest declares.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"minItems":1,"maxItems":25,"type":"array","items":{"type":"object","properties":{"namespace":{"default":"custom","type":"string"},"key":{"type":"string"},"value":{}},"required":["key"]}}},"required":["metafields"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/{productId}/translations":{"get":{"operationId":"listProductTranslations","summary":"List a product’s translations","description":"Every translated field, by locale.","tags":["Products"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"description":"Locale, then field, then the translated text."}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setProductTranslations","summary":"Set a product’s translations","description":"Sets translated fields for one locale. Fields not named are left alone, and a null clears one.","tags":["Products"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Z]{2})?$"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","null"]}}},"required":["locale","fields"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"The locale’s fields after the change."}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/products/{productId}/variant-extras":{"get":{"operationId":"getVariantExtras","summary":"Read what every variant of a product holds","description":"Stock, downloads, own pictures and custom data for each variant of one product, in one call. A variant with nothing recorded comes back with empty lists, so each variant has an entry, in the order the product lists them.","tags":["Variants"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VariantExtras"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/variants/{variantId}":{"patch":{"operationId":"updateVariant","summary":"Update a variant","description":"Changes only the fields sent, and a null clears a field that may be empty. A digital variant cannot also require shipping, so send `isDigital` true with `requiresShipping` false. Refused with `variant_sku_taken` for a SKU another variant has. Price, cost and back orders have calls of their own.","tags":["Variants"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"sku":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"barcode":{"anyOf":[{"type":"string","minLength":1,"maxLength":120},{"type":"null"}]},"lowStockThreshold":{"anyOf":[{"type":"integer","minimum":0,"maximum":100000},{"type":"null"}]},"weightGrams":{"anyOf":[{"type":"integer","minimum":0,"maximum":1000000},{"type":"null"}]},"hsCode":{"anyOf":[{"type":"string","pattern":"^\\d{4}(\\.?\\d{2}){1,3}$"},{"type":"null"}]},"countryOfOrigin":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}]},"requiresShipping":{"type":"boolean"},"isDigital":{"type":"boolean"},"position":{"type":"integer","minimum":0,"maximum":10000},"orderMinimum":{"anyOf":[{"type":"integer","minimum":1,"maximum":10000},{"type":"null"}]},"orderMaximum":{"anyOf":[{"type":"integer","minimum":1,"maximum":10000},{"type":"null"}]},"orderIncrement":{"anyOf":[{"type":"integer","minimum":1,"maximum":10000},{"type":"null"}]},"taxClassId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"shippingClassId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Variant"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/variants/{variantId}/price":{"post":{"operationId":"setVariantPrice","summary":"Set a variant’s price","description":"Sets or replaces the price in one currency, in minor units. A `compareAtAmount` is shown struck through and must be higher than the price (`invalid_compare_at_price`); leaving it out removes one already set. Every change is kept in the price history.","tags":["Variants"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"compareAtAmount":{"type":"integer","exclusiveMinimum":0}},"required":["amount","currency"]}}}},"responses":{"204":{"description":"Done, with nothing to send back."},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/variants/{variantId}/price/history":{"get":{"operationId":"listVariantPriceHistory","summary":"List a variant’s price changes","description":"Every price the variant has had, newest first, each with the one before it.","tags":["Variants"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many to return, up to 200. Twenty when not given.","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"currency","in":"query","required":false,"description":"Only changes in this currency, such as `GBP`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceChange"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/variants/{variantId}/price/revert":{"post":{"operationId":"revertVariantPrice","summary":"Put a price back","description":"Restores the price, and its compare-at price, from before one change in the price history. The revert is a change of its own and appears in the history. Refused with `nothing_to_revert` for a variant’s first price.","tags":["Variants"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"historyId":{"type":"integer","description":"The `id` of the change to undo, from the history."}},"required":["historyId"]}}}},"responses":{"204":{"description":"Done, with nothing to send back."},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/variants/{variantId}/cost":{"post":{"operationId":"setVariantCost","summary":"Set what a variant cost to buy","description":"Sets the cost of one, in minor units, or clears it with a body of `null`, which means unknown. Shoppers never see it and no webhook carries it; it is read back as each variant’s `cost` on the product.","tags":["Variants"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["amount","currency"]},{"type":"null"}]}}}},"responses":{"204":{"description":"Done, with nothing to send back."},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/variants/{variantId}/backorder":{"post":{"operationId":"setVariantBackorder","summary":"Set whether a variant sells with no stock","description":"With `allow` true the variant keeps selling once its stock reaches zero; with false it stops there.","tags":["Variants"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"allow":{"type":"boolean"}},"required":["allow"]}}}},"responses":{"204":{"description":"Done, with nothing to send back."},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/variants/{variantId}/media":{"get":{"operationId":"listVariantMedia","summary":"List a variant’s images","description":"The images shown when a shopper picks this variant, in order. A variant with none shows the product’s gallery.","tags":["Variants"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductMedia"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addVariantMedia","summary":"Show an image for a variant","description":"Adds an image already uploaded to the shop, usually one in the product’s gallery, to the variant’s own images. It is not added to the gallery. Adding one already there changes nothing.","tags":["Variants"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mediaId":{"type":"string","format":"uuid","description":"An image uploaded to the shop."}},"required":["mediaId"]}}}},"responses":{"204":{"description":"Done, with nothing to send back."},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeVariantMedia","summary":"Take an image off a variant","description":"Takes the image off the variant’s own images and leaves the image itself alone. The id goes in the query string.","tags":["Variants"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}},{"name":"mediaId","in":"query","required":true,"description":"The image to take off.","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Done, with nothing to send back."},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/variants/{variantId}/digital-assets":{"get":{"operationId":"listVariantDigitalAssets","summary":"List a variant’s downloads","description":"The files a buyer of this variant may download, oldest first.","tags":["Variants"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"attachVariantDigitalAsset","summary":"Attach a download to a variant","description":"Records a file uploaded with a ticket from `POST /digital-assets/upload-url`, by its `storagePath`, so every later buyer of the variant may download it. It does not make the variant digital: a book with a bonus file is still posted. When the file is all a buyer gets, set `isDigital` with `updateVariant`.","tags":["Variants"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"storagePath":{"type":"string","minLength":1,"maxLength":500},"fileName":{"type":"string","minLength":1,"maxLength":255},"sizeBytes":{"type":"integer","exclusiveMinimum":0,"maximum":524288000},"downloadLimit":{"type":"integer","exclusiveMinimum":0,"maximum":1000}},"required":["storagePath","fileName"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DigitalAsset"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/variants/{variantId}/metafields":{"get":{"operationId":"listVariantMetafields","summary":"List a variant’s metafields","description":"Every metafield value set on a variant, each with its definition.","tags":["Variants"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setVariantMetafields","summary":"Set a variant’s metafields","description":"Sets up to 25 values in one call. A null value clears its field; keys not named are left alone. An app may set only the fields its manifest declares.","tags":["Variants"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"minItems":1,"maxItems":25,"type":"array","items":{"type":"object","properties":{"namespace":{"default":"custom","type":"string"},"key":{"type":"string"},"value":{}},"required":["key"]}}},"required":["metafields"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/collections":{"get":{"operationId":"listCollections","summary":"List collections","description":"Every collection, or a page of them when any of `search`, `kind`, `sort`, `limit` or `offset` is given. A page carries `meta.total` and, in `meta.counts`, how many products each collection on it holds.","tags":["Collections"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Words in the title or handle.","schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["manual","automatic"]}},{"name":"sort","in":"query","required":false,"description":"By title unless `updated_desc`, most recently changed first. Any other value is ignored.","schema":{"type":"string","enum":["title_asc","updated_desc"]}},{"name":"limit","in":"query","required":false,"description":"How many to return. Fifty when not given.","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","required":false,"description":"How many to skip, for the next page.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"description":"Only on a page.","type":"object","properties":{"total":{"type":"integer"},"counts":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"integer"},"description":"Products in each collection on this page, by id."}},"required":["total","counts"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCollection","summary":"Create a collection","tags":["Collections"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"handle":{"type":"string","maxLength":128,"pattern":"^[a-z0-9][a-z0-9-]*$"},"description":{"type":"string","maxLength":50000},"parentId":{"type":"string","format":"uuid"},"seoTitle":{"type":"string","maxLength":300},"seoDescription":{"type":"string","maxLength":1000},"kind":{"default":"manual","type":"string","enum":["manual","automatic"]},"rules":{"default":[],"maxItems":10,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["title","product_type","vendor","tag","price"]},"operator":{"type":"string","enum":["equals","not_equals","contains","starts_with","ends_with","greater_than","less_than"]},"value":{"type":"string","minLength":1,"maxLength":200},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["field","operator","value"]}},"sortOrder":{"default":"manual","type":"string","enum":["manual","title_asc","title_desc","created_desc","price_asc","price_desc"]},"filterable":{"type":"boolean"}},"required":["title"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/collections/{collectionId}":{"get":{"operationId":"getCollection","summary":"Get a collection","tags":["Collections"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateCollection","summary":"Update a collection","description":"Changes only the fields sent.","tags":["Collections"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"handle":{"type":"string","maxLength":128,"pattern":"^[a-z0-9][a-z0-9-]*$"},"description":{"type":"string","maxLength":50000},"seoTitle":{"type":"string","maxLength":300},"seoDescription":{"type":"string","maxLength":1000},"rules":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["title","product_type","vendor","tag","price"]},"operator":{"type":"string","enum":["equals","not_equals","contains","starts_with","ends_with","greater_than","less_than"]},"value":{"type":"string","minLength":1,"maxLength":200},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["field","operator","value"]}},"sortOrder":{"type":"string","enum":["manual","title_asc","title_desc","created_desc","price_asc","price_desc"]},"filterable":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Collection"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteCollection","summary":"Delete a collection","description":"Deletes the collection and says what it touched. Its products are kept, and its children move to the top level.","tags":["Collections"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"handle":{"type":"string"},"productsUnlinked":{"type":"integer","description":"Products that were in it. The products are untouched."},"childrenPromoted":{"type":"integer","description":"Child collections moved to the top level."},"menuItemsRemoved":{"type":"integer","description":"Menu entries that pointed at it."},"discountTargetsRemoved":{"type":"integer","description":"Discounts that named it, which now apply to less."}},"required":["id","title","handle","productsUnlinked","childrenPromoted","menuItemsRemoved","discountTargetsRemoved"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/collections/{collectionId}/products":{"get":{"operationId":"listCollectionProducts","summary":"List a collection’s products","description":"A page of the products in the collection, in its own order. Pass `meta.next` back as `after` for the next page.","tags":["Collections"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Words in a product’s title.","schema":{"type":"string"}},{"name":"ids","in":"query","required":false,"description":"Comma separated product ids: which of these are in it.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many to return. Fifty when not given.","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"after","in":"query","required":false,"description":"The `meta.next` of the page before.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Members the search and ids match."},"held":{"type":"integer","description":"Every product in the collection."},"next":{"description":"Pass back as `after`. Null on the last page.","type":["string","null"]},"truncated":{"type":"boolean","description":"True when a price sort was cut short at its cap."}},"required":["total","held","next","truncated"]}},"required":["data","meta"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addProductsToCollection","summary":"Add products to a collection","description":"Adds products to a manual collection. Products already in it are left where they are.","tags":["Collections"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"productIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"The products to add."}},"required":["productIds"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"added":{"type":"integer"}},"required":["added"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/collections/{collectionId}/products/{productId}":{"delete":{"operationId":"removeProductFromCollection","summary":"Remove a product from a collection","tags":["Collections"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}},{"name":"productId","in":"path","required":true,"description":"The product.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"boolean","const":true}},"required":["removed"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/collections/{collectionId}/metafields":{"get":{"operationId":"listCollectionMetafields","summary":"List a collection’s metafields","description":"Every metafield value set on a collection, each with its definition.","tags":["Collections"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setCollectionMetafields","summary":"Set a collection’s metafields","description":"Sets up to 25 values in one call. A null value clears its field; keys not named are left alone. An app may set only the fields its manifest declares.","tags":["Collections"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"minItems":1,"maxItems":25,"type":"array","items":{"type":"object","properties":{"namespace":{"default":"custom","type":"string"},"key":{"type":"string"},"value":{}},"required":["key"]}}},"required":["metafields"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/collections/{collectionId}/translations":{"get":{"operationId":"listCollectionTranslations","summary":"List a collection’s translations","description":"Every translated field, by locale.","tags":["Collections"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"description":"Locale, then field, then the translated text."}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setCollectionTranslations","summary":"Set a collection’s translations","description":"Sets translated fields for one locale. Fields not named are left alone, and a null clears one.","tags":["Collections"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"collectionId","in":"path","required":true,"description":"The collection.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"type":"string","pattern":"^[a-z]{2,3}(-[A-Z]{2})?$"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","null"]}}},"required":["locale","fields"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"},"description":"The locale’s fields after the change."}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/inventory":{"get":{"operationId":"listStock","summary":"List stock","description":"One row per variant of every product not archived, with what is on hand, held and left to sell, added up across locations or read for one. `low` is five or fewer left; a variant that is not tracked is never low or out. `meta.counts` says how many of each there are under the same search.","tags":["Inventory"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"filter","in":"query","required":false,"description":"`all` when not given.","schema":{"type":"string","enum":["all","low","out"]}},{"name":"search","in":"query","required":false,"description":"Words in a product’s name, a variant’s name or a SKU.","schema":{"type":"string"}},{"name":"locationId","in":"query","required":false,"description":"One location. Every location added up when not given.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","required":false,"description":"How many to return, up to 250. Fifty when not given.","schema":{"type":"integer","minimum":1,"maximum":250}},{"name":"offset","in":"query","required":false,"description":"How many to skip, for the next page.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"productId":{"type":"string","format":"uuid"},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"sku":{"type":["string","null"]},"tracked":{"type":"boolean","description":"False for a variant that carries on selling when it runs out, or is a download."},"onHand":{"type":"integer"},"reserved":{"type":"integer","description":"Held for orders placed and not yet sent."},"available":{"type":"integer","description":"On hand less reserved."}},"required":["variantId","productId","productTitle","variantTitle","sku","tracked","onHand","reserved","available"]}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"How many match the filter and search, across every page."},"counts":{"type":"object","properties":{"all":{"type":"integer"},"low":{"type":"integer"},"out":{"type":"integer"}},"required":["all","low","out"],"description":"How many of each `filter` there are under the same search."}},"required":["total","counts"]}},"required":["data","meta"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/inventory/incoming":{"get":{"operationId":"listIncomingStock","summary":"List stock on its way","description":"For each variant named, what is on order from vendors and what is in transit between the shop’s locations. None of it is stock that can be sold. Every variant asked about is answered, with zeros when nothing is coming.","tags":["Inventory"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantIds","in":"query","required":true,"description":"Comma separated variant ids, up to 500.","schema":{"type":"string"}},{"name":"locationId","in":"query","required":false,"description":"Only what is coming to this location.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"onOrder":{"type":"integer","description":"Asked of a vendor and not yet delivered."},"inTransit":{"type":"integer","description":"Sent from another of the shop’s locations and not yet arrived."},"incoming":{"type":"integer","description":"The two together."}},"required":["variantId","onOrder","inTransit","incoming"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/inventory/{variantId}":{"get":{"operationId":"getInventory","summary":"Get a variant’s stock levels","description":"The variant’s level at each location that has one. A location that has never held it has no row: see `getVariantStock` for every location.","tags":["Inventory"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLevel"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"changeInventory","summary":"Change stock at a location","description":"Send `delta` to add or take away, or `onHand` to set the shelf to a count, never both. Stock cannot fall below zero, nor below what is held for orders. A location kept by a supplier cannot be changed. A delta sent twice is applied twice, so send an `Idempotency-Key` header to make a retry safe.","tags":["Inventory"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"locationId":{"type":"string","format":"uuid","description":"The location whose shelf changes."},"delta":{"description":"How many to add, or take away when negative.","type":"integer"},"onHand":{"description":"What was counted on the shelf.","type":"integer","minimum":0,"maximum":10000000},"reason":{"description":"Why, for the stock history.","type":"string","maxLength":200}},"required":["locationId"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InventoryLevel"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/inventory/{variantId}/movements":{"get":{"operationId":"listStockMovements","summary":"List a variant’s stock history","description":"Every change to the variant’s stock, newest first: what changed, by how much, what it left, and why where somebody said. Pass `meta.next` back as `before` for the next page.","tags":["Inventory"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many to return, up to 200. Fifty when not given.","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"before","in":"query","required":false,"description":"The `meta.next` of the page before.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"A 64 bit number, sent as a string."},"storeId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"locationId":{"type":"string","format":"uuid"},"kind":{"type":"string","description":"opening, adjustment, count, reserved, released, shipped, received, returned, transfer_out or transfer_in."},"onHandDelta":{"type":"number"},"reservedDelta":{"type":"number"},"onHandAfter":{"type":"number"},"reservedAfter":{"type":"number"},"reason":{"type":["string","null"]},"referenceType":{"description":"What it was for, such as an order or a transfer.","type":["string","null"]},"referenceId":{"type":["string","null"]},"actorType":{"description":"`staff`, `customer`, `plugin`, `agent` or `system`, where known.","type":["string","null"]},"actorId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"locationName":{"type":["string","null"]}},"required":["id","storeId","variantId","locationId","kind","onHandDelta","reservedDelta","onHandAfter","reservedAfter","reason","referenceType","referenceId","actorType","actorId","createdAt","locationName"]}},"meta":{"type":"object","properties":{"next":{"description":"Pass back as `before`. Null on the last page.","type":["string","null"]}},"required":["next"]}},"required":["data","meta"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/inventory/{variantId}/stock":{"get":{"operationId":"getVariantStock","summary":"Get a variant’s stock at every location","description":"The variant, and a row for each of the shop’s locations, including those that hold none of it, default first.","tags":["Inventory"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"variantId","in":"path","required":true,"description":"The variant.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"variant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"productId":{"type":"string","format":"uuid"},"productTitle":{"type":"string"},"variantTitle":{"type":"string"},"sku":{"type":["string","null"]},"tracked":{"type":"boolean","description":"False for a variant that carries on selling when it runs out, or is a download."}},"required":["id","productId","productTitle","variantTitle","sku","tracked"]},"levels":{"type":"array","items":{"type":"object","properties":{"locationId":{"type":"string","format":"uuid"},"locationName":{"type":"string"},"kind":{"type":"string","enum":["own","supplier"],"description":"`supplier` stock is refreshed from the supplier and cannot be changed here."},"onHand":{"type":"integer"},"reserved":{"type":"integer"},"available":{"type":"integer"}},"required":["locationId","locationName","kind","onHand","reserved","available"]}}},"required":["variant","levels"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/locations":{"get":{"operationId":"listLocations","summary":"List locations","description":"Every place the shop keeps stock.","tags":["Inventory"],"x-storeware-scopes":["products:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createLocation","summary":"Create a location","description":"With `isDefault`, the new location becomes the one orders take their stock from, in place of the old default.","tags":["Inventory"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"isDefault":{"type":"boolean"}},"required":["name"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Location"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/locations/{locationId}":{"patch":{"operationId":"updateLocation","summary":"Update a location","description":"Renames it, or makes it the default, which moves where every later order takes its stock from. The default cannot be turned off, only moved.","tags":["Inventory"],"x-storeware-scopes":["products:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"locationId","in":"path","required":true,"description":"The stock location.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"isDefault":{"type":"boolean","const":true}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Location"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/shipping-classes":{"get":{"operationId":"listShippingClasses","summary":"List shipping classes","description":"Every class the shop has, oldest first. A class holds variants that cost the same to send, and a delivery rate can name classes to depend on. `meta.gaps` lists the delivery zones with no rate for a class that has variants in it, because a basket holding one of those cannot be checked out to that zone.","tags":["Shipping"],"x-storeware-scopes":["stores:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingClassRow"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"gaps":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string","format":"uuid"}},"description":"Class id to the ids of the zones with no rate for it."}},"required":["total","gaps"]}},"required":["data","meta"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createShippingClass","summary":"Create a shipping class","description":"Answers with the class already holding that name, unchanged, if there is one. Refused with `shipping_class_name_invalid` for a name with no letter or number in it. Send `Idempotency-Key` to make a retry safe.","tags":["Shipping"],"x-storeware-scopes":["stores:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"default":null,"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":["name"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ShippingClass"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/shipping-classes/{classId}":{"patch":{"operationId":"updateShippingClass","summary":"Update a shipping class","description":"Changes only the fields sent. Renaming a class keeps its slug. Refused with `shipping_class_not_found` for a class this shop does not have.","tags":["Shipping"],"x-storeware-scopes":["stores:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"classId","in":"path","required":true,"description":"The class.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ShippingClass"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteShippingClass","summary":"Delete a shipping class","description":"The variants in it are left in no class. Refused with `shipping_class_in_use` while a delivery rate names it, because the rate would then be offered to the wrong baskets.","tags":["Shipping"],"x-storeware-scopes":["stores:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"classId","in":"path","required":true,"description":"The class.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"variantsCleared":{"type":"integer","description":"How many variants were left in no class."}},"required":["variantsCleared"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders":{"get":{"operationId":"listOrders","summary":"List orders","description":"A page of orders, newest first unless `sort` says otherwise. `meta.units` says, for each order on the page, how many units were ordered and how many have been sent; `meta.labelled` names the ones with a postage label bought.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["created","confirmed","manual_review","processing","shipped","delivered","canceled"]}},{"name":"queue","in":"query","required":false,"description":"`to_send`: paid for and not all sent, and not on hold. `on_hold`: kept back by the shop.","schema":{"type":"string","enum":["to_send","on_hold"]}},{"name":"search","in":"query","required":false,"description":"An order number, with or without the `#`, matched exactly; or words in the buyer’s email or name.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Placed on or after this day, `YYYY-MM-DD`, in the shop’s own time.","schema":{"type":"string"}},{"name":"to","in":"query","required":false,"description":"Placed on or before this day, `YYYY-MM-DD`, in the shop’s own time.","schema":{"type":"string"}},{"name":"payment","in":"query","required":false,"description":"How it was paid, in the words of the export’s Financial Status column.","schema":{"type":"string","enum":["pending","paid","partially_refunded","refunded","voided"]}},{"name":"origin","in":"query","required":false,"description":"Which door placed it.","schema":{"type":"string","enum":["storefront","agent","admin","plugin","imported","subscription"]}},{"name":"tags","in":"query","required":false,"description":"Carrying any of these tags, separated by commas.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Newest first (`placed_desc`) when not given.","schema":{"type":"string","enum":["placed_desc","placed_asc","total_desc","total_asc"]}},{"name":"limit","in":"query","required":false,"description":"How many to return, up to 250. Fifty when not given.","schema":{"type":"integer","minimum":1,"maximum":250}},{"name":"offset","in":"query","required":false,"description":"How many to skip, for the next page.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"How many match, across every page."},"units":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"ordered":{"type":"integer"},"shipped":{"type":"integer"}},"required":["ordered","shipped"]},"description":"Units ordered and sent, by order id, for the orders on this page."},"labelled":{"type":"array","items":{"type":"string"},"description":"The orders on this page with a bought, unvoided label going out."}},"required":["total","units","labelled"]}},"required":["data","meta"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}":{"get":{"operationId":"getOrder","summary":"Get an order","description":"The order with its lines and its adjustments. With `format=acp`, the same order in the Agentic Commerce Protocol’s shape instead.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"`acp` for the Agentic Commerce Protocol’s shape.","schema":{"type":"string","enum":["acp"]}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/OrderLineItem"}},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/OrderAdjustment"},"description":"Refunds, store credit, returns and disputes, newest first."},"invoicePaid":{"description":"On an order placed on account, whether the money has arrived.","type":"boolean"},"refundWays":{"anyOf":[{"type":"object","properties":{"cardLeft":{"type":"integer","description":"What a refund still sends back the way it was paid."},"creditLeft":{"type":"integer","description":"What goes back to store credit after that."}},"required":["cardLeft","creditLeft"]},{"type":"null"}],"description":"For an order store credit or a gift card paid some of. Null for any other order."}},"required":["order","lineItems","adjustments","refundWays"]},{"type":"object","properties":{"type":{"type":"string","const":"order"},"id":{"type":"string","format":"uuid"},"checkout_session_id":{"type":"string","description":"Empty when no checkout session placed it."},"permalink_url":{"type":"string","description":"The order’s page at the shop."},"order_number":{"type":"string"},"status":{"type":"string","enum":["created","confirmed","manual_review","processing","shipped","completed","canceled"]},"line_items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","description":"The product’s title, and the variant’s in parentheses."},"product_id":{"type":"string","format":"uuid"},"image_url":{"type":"string"},"quantity":{"type":"object","properties":{"ordered":{"type":"integer"},"current":{"type":"integer","description":"Ordered, less what came back."},"fulfilled":{"type":"integer"}},"required":["ordered","current","fulfilled"]},"unit_price":{"type":"integer","description":"Minor units."},"subtotal":{"type":"integer","description":"Minor units."},"status":{"type":"string","enum":["processing","partial","fulfilled","removed"]}},"required":["id","title","quantity","unit_price","subtotal","status"]}},"totals":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["items_base_amount","items_discount","subtotal","discount","fulfillment","tax","fee","gift_wrap","tip","store_credit","total","amount_refunded"]},"display_text":{"type":"string"},"amount":{"type":"integer","description":"Minor units."}},"required":["type","display_text","amount"]}}},"required":["type","id","checkout_session_id","permalink_url","order_number","status","line_items","totals"],"description":"With `format=acp`: the order in the Agentic Commerce Protocol’s shape."}]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelOrder","summary":"Cancel an order","description":"Cancels the order and puts back the stock not yet sent. It refunds nothing: refund it separately. Cancelling an order already cancelled changes nothing. Emits `order.canceled.v1`.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"description":"Why, kept on the order’s history.","type":"string"}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateOrderDetails","summary":"Correct an order’s contact details or address","description":"Corrects the buyer’s email, name or phone, or the delivery address. Never moves money: tax stays as charged, and a difference in delivery is settled by editing the order. Refused for an order wholly sent, one with a live label or a supplier, and for a paid order moving to another country. Changing the email does not change whose order it is, and the old address is told.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyerEmail":{"type":"string","maxLength":320,"format":"email"},"buyerFirstName":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"buyerLastName":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"buyerPhone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"shippingAddress":{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"line_one":{"type":"string","minLength":1,"maxLength":200},"line_two":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":120},"state":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"postal_code":{"type":"string","minLength":1,"maxLength":32}},"required":["line_one","city","country","postal_code"],"additionalProperties":false},"acknowledged":{"type":"string","minLength":64,"maxLength":64}},"additionalProperties":false}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"string"},"description":"Which fields would change, by name."},"notices":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["tax_stays","delivery_differs","delivery_unquoted"]},"charged":{"description":"What was charged for delivery, in minor units.","type":"integer"},"quoted":{"description":"What this address would come to, in minor units.","type":"integer"}},"required":["kind"]}},"digest":{"type":"string","description":"Pass this as `acknowledged` when there are notices."}},"required":["fields","notices","digest"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/authentications":{"get":{"operationId":"listPendingPaymentAuthentications","summary":"List orders waiting on a card check","description":"Orders whose payment is held for a card issuer’s check (such as 3D Secure) that the buyer has not finished, the link soonest to expire first. The links themselves are never listed.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many to return. Fifty when not given.","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sessionId":{"type":"string","format":"uuid","description":"The checkout session. Renew its link with this id."},"orderId":{"type":"string","format":"uuid"},"orderNumber":{"type":"string"},"buyerEmail":{"type":"string"},"totalAmount":{"type":"integer","description":"Minor units."},"currency":{"type":"string"},"origin":{"type":"string","description":"Which door placed the order."},"expiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When the link stops working. Null once it is opened."},"state":{"type":"string","enum":["outstanding","expired","opened"],"description":"`outstanding`: nobody has opened the link. `expired`: nobody opened it in time. `opened`: the buyer is answering the challenge now."},"createdAt":{"type":"string","format":"date-time"}},"required":["sessionId","orderId","orderNumber","buyerEmail","totalAmount","currency","origin","expiresAt","state","createdAt"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/authentications/{sessionId}":{"post":{"operationId":"renewPaymentAuthenticationLink","summary":"Renew a card check link","description":"Makes a new link for a buyer to finish their card check, and answers with it. The new link replaces the old one, which stops working. Whoever holds the link can pay for and then read the order, so send it only to the buyer and do not store it. Refused for a checkout that is not waiting on a check.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"sessionId","in":"path","required":true,"description":"The session.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","description":"The link, shown this once."},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","expiresAt"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/approval":{"post":{"operationId":"decideOrderApproval","summary":"Approve or reject a held order","description":"Answers an order an AI agent placed above the shop’s approval limit, which waits in `manual_review`. Approving takes the payment, which is the first time money moves, so it can fail as any payment can; it answers the order and anything the payment still needs. Rejecting cancels the order, puts its stock back and emits `order.canceled.v1`; it answers the order.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","reject"]},"reason":{"description":"Why it was rejected. Read only when rejecting.","type":"string"}},"required":["decision"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"order":{"$ref":"#/components/schemas/Order"},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/OrderLineItem"}},"payment":{"description":"Present when the payment is waiting on a browser.","type":"object","properties":{"clientSecret":{"type":["string","null"]},"status":{"type":"string","enum":["requires_payment_method","requires_action"]},"stripeAccountId":{"type":["string","null"]},"keepsCard":{"type":"boolean"},"amount":{"type":"integer","description":"What the card is asked for, in minor units."}},"required":["clientSecret","status","stripeAccountId","keepsCard","amount"]},"authentication":{"description":"Present when the card issuer wants the buyer, and a link must be sent to them.","type":"object","properties":{"url":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","expiresAt"]}},"required":["order","lineItems"]},{"$ref":"#/components/schemas/Order"}]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/changes":{"get":{"operationId":"listOrderChanges","summary":"List an order’s changes","description":"Every change proposed or made to the order since it was placed, oldest first.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderChange"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"openOrderChange","summary":"Open an order change","description":"Opens an empty change to an order, to edit what it holds. Add lines to it, then confirm it. Nothing moves until it is confirmed.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"default":"edit","type":"string","enum":["edit","return","exchange","claim"]},"reason":{"type":"string","maxLength":500},"note":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderChange"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}":{"get":{"operationId":"getOrderChange","summary":"Get an order change","description":"The change, its lines, and in `delta` what it would cost if confirmed now.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"changeId","in":"path","required":true,"description":"The change.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"change":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["edit","return","exchange","claim"]},"status":{"type":"string","enum":["pending","confirmed","declined","canceled"]},"reason":{"type":["string","null"]},"note":{"type":["string","null"]},"deltaSubtotalAmount":{"type":"number"},"deltaDiscountAmount":{"type":"number"},"deltaFulfillmentAmount":{"type":"number"},"deltaTaxAmount":{"type":"number"},"deltaTotalAmount":{"type":"number","description":"What the change came to, signed and in minor units: positive means the customer owes more. Zero until it is confirmed, as are the other deltas."},"currency":{"type":"string"},"adjustmentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The refund it made, when it gave money back."},"paymentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorType":{"anyOf":[{"type":"string","enum":["staff","customer","plugin","agent","system"]},{"type":"null"}]},"actorId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"confirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","storeId","orderId","kind","status","reason","note","deltaSubtotalAmount","deltaDiscountAmount","deltaFulfillmentAmount","deltaTaxAmount","deltaTotalAmount","currency","adjustmentId","paymentId","actorType","actorId","createdAt","updatedAt","confirmedAt","declinedAt","canceledAt"]},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"changeId":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["item_add","item_quantity","item_remove","shipping_add","shipping_remove"]},"lineItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"variantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"quantityDelta":{"type":"number","description":"Signed. Negative takes units off the line."},"unitAmount":{"type":"number","description":"Minor units."},"amount":{"type":"number","description":"Minor units."},"details":{},"createdAt":{"type":"string","format":"date-time"}},"required":["id","storeId","changeId","action","lineItemId","variantId","quantityDelta","unitAmount","amount","details","createdAt"]}},"delta":{"type":"object","properties":{"subtotalAmount":{"type":"integer"},"discountAmount":{"type":"integer"},"fulfillmentAmount":{"type":"integer"},"taxAmount":{"type":"integer"},"totalAmount":{"type":"integer"},"currency":{"type":"string"},"lines":{"type":"array","items":{"type":"object","properties":{"actionId":{"type":"string","format":"uuid"},"lineItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"title":{"type":"string"},"quantityDelta":{"type":"integer"},"unitAmount":{"type":"integer"},"amount":{"type":"integer"},"taxAmount":{"type":"integer"}},"required":["actionId","lineItemId","title","quantityDelta","unitAmount","amount","taxAmount"]}}},"required":["subtotalAmount","discountAmount","fulfillmentAmount","taxAmount","totalAmount","currency","lines"],"description":"What the change would cost if confirmed now, priced against the catalogue as it stands. Signed and in minor units: positive means the customer owes more."}},"required":["change","actions","delta"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"decideOrderChange","summary":"Confirm, decline or cancel an order change","description":"Settles a pending change. Confirming moves the stock and the money and emits `order.changed.v1`: a change that gives money back refunds it to the card, and one that leaves the customer owing more is recorded as owed, not charged. A change that would refund an order paid in stablecoins, imported from another platform, or not yet paid for is refused. Declining or cancelling closes it with nothing moved.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"changeId","in":"path","required":true,"description":"The change.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["confirm","decline","cancel"]},"reason":{"description":"Why. Read only when declining or cancelling.","type":"string"}},"required":["decision"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderChange"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}/actions":{"post":{"operationId":"addOrderChangeAction","summary":"Add a line to an order change","description":"Adds one action to a pending change: add a variant, change a line’s quantity, remove a line, or add or take off delivery. Checked against the order as it stands now. Amounts are in minor units.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"changeId","in":"path","required":true,"description":"The change.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"action":{"type":"string","const":"item_add"},"variantId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["action","variantId","quantity"]},{"type":"object","properties":{"action":{"type":"string","const":"item_quantity"},"lineItemId":{"type":"string","format":"uuid"},"quantityDelta":{"type":"integer"}},"required":["action","lineItemId","quantityDelta"]},{"type":"object","properties":{"action":{"type":"string","const":"item_remove"},"lineItemId":{"type":"string","format":"uuid"}},"required":["action","lineItemId"]},{"type":"object","properties":{"action":{"type":"string","const":"shipping_add"},"amount":{"type":"integer","exclusiveMinimum":0},"description":{"type":"string","maxLength":200}},"required":["action","amount","description"]},{"type":"object","properties":{"action":{"type":"string","const":"shipping_remove"},"amount":{"type":"integer","exclusiveMinimum":0},"description":{"type":"string","maxLength":200}},"required":["action","amount"]}]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderChange"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/changes/{changeId}/actions/{actionId}":{"delete":{"operationId":"removeOrderChangeAction","summary":"Remove a line from an order change","description":"Takes an action off a change nobody has confirmed yet.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"changeId","in":"path","required":true,"description":"The change.","schema":{"type":"string"}},{"name":"actionId","in":"path","required":true,"description":"The action.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderChange"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/downloads":{"get":{"operationId":"listOrderDownloads","summary":"List an order’s downloads","description":"Every file the order bought, with how many times it has been downloaded and how many more it may be. An unpaid, cancelled or refunded order is listed too, with `available` false and the reason.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DownloadGrant"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"setOrderDownloadAllowance","summary":"Set a download allowance","description":"Sets how many times one line of the order may download one file. It cannot be set below the downloads already taken; set it to that count to stop further downloads.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"assetId":{"type":"string","format":"uuid","description":"The file."},"downloadLimit":{"anyOf":[{"type":"integer","minimum":1,"maximum":1000},{"type":"null"}],"description":"How many downloads in all. Null for unlimited."}},"required":["lineItemId","assetId","downloadLimit"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DownloadGrant"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/fulfillments":{"get":{"operationId":"listFulfillments","summary":"List an order’s fulfillments","description":"Every despatch of the order, with its tracking events and the lines it carries.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createFulfillment","summary":"Create a fulfillment","description":"Records a despatch of some or all of an order’s lines, and takes the stock off the shelf. A line cannot be sent more times than is left of it. Emits `fulfillment.created.v1`. Send an `Idempotency-Key` header to make a retry safe: a second request with the same key answers what the first did.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["shipping","pickup","digital"]},"lineItems":{"minItems":1,"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["lineItemId","quantity"]}},"locationId":{"type":"string","format":"uuid"},"carrier":{"type":"string","maxLength":120},"trackingNumber":{"type":"string","maxLength":120},"trackingUrl":{"type":"string","maxLength":2000,"format":"uri"},"estimatedDeliveryEarliest":{"description":"The earliest it should arrive.","type":"string","format":"date-time"},"estimatedDeliveryLatest":{"description":"The latest it should arrive.","type":"string","format":"date-time"},"digitalAccessUrl":{"type":"string","format":"uri"},"digitalLicenseKey":{"type":"string","maxLength":500},"notifyBuyer":{"default":true,"type":"boolean"}},"required":["type","lineItems"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Fulfillment"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}/events":{"post":{"operationId":"recordTrackingEvent","summary":"Record a tracking event","description":"Says where a despatch has got to, and moves its status and the order’s with it. `failed_attempt` leaves the status as it is; `returned` marks the despatch failed. Emits `fulfillment.updated.v1`, and `delivered` writes to the buyer. Send an `Idempotency-Key` header to make a retry safe: a second request with the same key answers what the first did.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"fulfillmentId","in":"path","required":true,"description":"The fulfillment.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["processing","shipped","in_transit","out_for_delivery","ready_for_pickup","delivered","failed_attempt","returned"]},"occurredAt":{"description":"When it happened. Now when not given.","type":"string","format":"date-time"},"description":{"type":"string","maxLength":500},"location":{"type":"string","maxLength":200}},"required":["type"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Fulfillment"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/label-quotes":{"get":{"operationId":"getShippingLabelStart","summary":"Get what a shipping label needs","description":"What a label for this order would start from: what is left to send and what it weighs, the shop’s boxes, and whether a card and a ship from address are in place. Asks no carrier.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"unavailable":{"anyOf":[{"type":"string","enum":["unconfigured","mode_mismatch","not_offered"]},{"type":"null"}],"description":"Why no label can be bought for this shop. Null when one can."},"mode":{"anyOf":[{"type":"string","enum":["test","live"]},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"title":{"type":"string"},"variantTitle":{"type":["string","null"]},"free":{"type":"integer","description":"Units not sent yet and not held by a label still being bought."},"weightGrams":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"One unit. Null when the product has no weight."}},"required":["lineItemId","title","variantTitle","free","weightGrams"]}},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"name":{"type":"string"},"lengthMm":{"type":"number"},"widthMm":{"type":"number"},"heightMm":{"type":"number"},"emptyWeightGrams":{"type":"number"},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","name","lengthMm","widthMm","heightMm","emptyWeightGrams","isDefault","createdAt","updatedAt"]},"description":"The boxes the shop keeps."},"hasShipFrom":{"type":"boolean","description":"Whether the shop has said where parcels leave from."},"card":{"anyOf":[{"type":"object","properties":{"brand":{"type":["string","null"]},"last4":{"type":["string","null"]}},"required":["brand","last4"]},{"type":"null"}],"description":"The card postage is charged to. Null when there is none."},"blocked":{"anyOf":[{"type":"string","enum":["postage_owed","dispute","review"]},{"type":"null"}],"description":"Why label buying is paused on the account, if it is."},"international":{"type":"boolean","description":"Whether the parcel crosses a border and needs customs."},"chosen":{"anyOf":[{"type":"object","properties":{"title":{"type":"string"},"amount":{"type":"integer","description":"Minor units."}},"required":["title","amount"]},{"type":"null"}],"description":"The delivery the shopper paid for, when they chose one."}},"required":["unavailable","mode","lines","packages","hasShipFrom","card","blocked","international","chosen"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"quoteShippingLabel","summary":"Quote a shipping label","description":"Asks the carrier what it would cost to send a parcel for this order, by every service it offers, and checks the address. Name one of: the lines the parcel carries, a despatch with no label yet, or a return to bring back. Buys nothing.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lines":{"minItems":1,"maxItems":250,"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["lineItemId","quantity"]}},"fulfillmentId":{"type":"string","format":"uuid"},"returnId":{"type":"string","format":"uuid"},"parcel":{"type":"object","properties":{"packageId":{"type":"string","format":"uuid"},"packageName":{"type":"string","maxLength":120},"lengthMm":{"type":"integer","minimum":1,"maximum":5000},"widthMm":{"type":"integer","minimum":1,"maximum":5000},"heightMm":{"type":"integer","minimum":1,"maximum":5000},"weightGrams":{"type":"integer","minimum":1,"maximum":1000000}},"required":["lengthMm","widthMm","heightMm","weightGrams"]},"options":{"default":{},"type":"object","properties":{"insuranceAmount":{"type":"integer","exclusiveMinimum":0,"maximum":100000000},"signature":{"type":"string","enum":["standard","adult"]}}}},"required":["parcel"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"shipmentId":{"type":"string","description":"Send it back, with a `rateId`, to buy."},"rates":{"type":"array","items":{"type":"object","properties":{"rateId":{"type":"string","description":"What a label is bought with."},"carrier":{"type":"string"},"carrierName":{"type":"string"},"serviceToken":{"type":"string"},"serviceName":{"type":"string"},"amount":{"type":"integer","description":"The carrier’s price, in minor units."},"currency":{"type":"string"},"estimatedDays":{"type":"integer"},"attributes":{"description":"The carrier’s own words: `CHEAPEST`, `FASTEST`, `BESTVALUE`.","type":"array","items":{"type":"string"}},"price":{"type":"object","properties":{"postage":{"type":"integer","description":"The carrier’s price, in minor units."},"fee":{"type":"integer","description":"Card processing on the whole charge, in minor units."},"total":{"type":"integer"}},"required":["postage","fee","total"],"description":"What the card would be charged."},"payOnUse":{"type":"boolean","description":"A return label charged only when a carrier first scans it."}},"required":["rateId","carrier","carrierName","serviceToken","serviceName","amount","currency","price","payOnUse"]}},"refusal":{"description":"Why the carrier offered nothing, when it did not.","type":["string","null"]},"chosenServiceToken":{"description":"The service the shopper paid for, when it is among the rates.","type":["string","null"]},"recipient":{"type":"object","properties":{"name":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}},"required":["line_one","city","country","postal_code"]},"addressCheck":{"type":"object","properties":{"checked":{"type":"boolean","description":"False when nobody was asked. That is not a verdict."},"valid":{"type":["boolean","null"]},"messages":{"type":"array","items":{"type":"string"},"description":"The carrier’s own sentences about the address."},"suggestion":{"description":"The address as the carrier writes it.","type":"object","properties":{"name":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}},"required":["line_one","city","country","postal_code"]}},"required":["checked","valid","messages"]},"shipFrom":{"type":"object","properties":{"locationName":{"type":"string"},"address":{"type":"object","properties":{"name":{"type":"string"},"company":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}},"required":["name","line_one","city","country","postal_code"]}},"required":["locationName","address"]},"parcel":{"type":"object","properties":{"packageId":{"type":"string","format":"uuid"},"packageName":{"type":"string"},"lengthMm":{"type":"integer"},"widthMm":{"type":"integer"},"heightMm":{"type":"integer"},"weightGrams":{"type":"integer"}},"required":["lengthMm","widthMm","heightMm","weightGrams"]},"customs":{"anyOf":[{"type":"object","properties":{"contentsType":{"type":"string","enum":["MERCHANDISE","GIFT","SAMPLE","RETURN_MERCHANDISE"]},"nonDeliveryOption":{"type":"string","enum":["RETURN","ABANDON"]},"certifySigner":{"type":"string"},"incoterm":{"type":"string","enum":["DDU","DDP"]},"items":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"quantity":{"type":"integer"},"netWeightGrams":{"type":"integer"},"valueAmount":{"type":"integer","description":"Minor units."},"valueCurrency":{"type":"string"},"originCountry":{"type":"string"},"tariffNumber":{"type":"string"}},"required":["description","quantity","netWeightGrams","valueAmount","valueCurrency","originCountry"]}}},"required":["contentsType","nonDeliveryOption","certifySigner","incoterm","items"]},{"type":"null"}],"description":"What the parcel declares to customs. Null when it crosses no border."}},"required":["shipmentId","rates","refusal","chosenServiceToken","recipient","addressCheck","shipFrom","parcel","customs"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/labels":{"get":{"operationId":"listShippingLabels","summary":"List an order’s shipping labels","description":"Every label the order has had, bought or not, newest first. At most fifty.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"buyShippingLabel","summary":"Buy a shipping label","description":"Buys a label at a rate from a quote and charges the account’s postage card. For lines, it also records the despatch with its tracking number. Answers 201 once the label is bought, and 202 while it is not yet: the bank wants the cardholder (`clientSecret` is set), or the carrier has not answered. Send the same `purchaseKey` again, or resume the label, to carry on; it never buys twice.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lines":{"minItems":1,"maxItems":250,"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["lineItemId","quantity"]}},"fulfillmentId":{"type":"string","format":"uuid"},"returnId":{"type":"string","format":"uuid"},"parcel":{"type":"object","properties":{"packageId":{"type":"string","format":"uuid"},"packageName":{"type":"string","maxLength":120},"lengthMm":{"type":"integer","minimum":1,"maximum":5000},"widthMm":{"type":"integer","minimum":1,"maximum":5000},"heightMm":{"type":"integer","minimum":1,"maximum":5000},"weightGrams":{"type":"integer","minimum":1,"maximum":1000000}},"required":["lengthMm","widthMm","heightMm","weightGrams"]},"options":{"default":{},"type":"object","properties":{"insuranceAmount":{"type":"integer","exclusiveMinimum":0,"maximum":100000000},"signature":{"type":"string","enum":["standard","adult"]}}},"purchaseKey":{"type":"string","minLength":8,"maxLength":200},"shipmentId":{"type":"string","minLength":1,"maxLength":100},"rateId":{"type":"string","minLength":1,"maxLength":100},"notifyBuyer":{"default":true,"type":"boolean"}},"required":["parcel","purchaseKey","shipmentId","rateId"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ShippingLabel"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/labels/{labelId}/resume":{"post":{"operationId":"resumeShippingLabel","summary":"Resume a shipping label purchase","description":"Carries an unfinished purchase on, once the bank’s check has been answered. Does nothing to a finished label, so it is safe to call any number of times. Answers 202 while the label is still not bought.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"labelId","in":"path","required":true,"description":"The label.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ShippingLabel"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/labels/{labelId}/void":{"post":{"operationId":"voidShippingLabel","summary":"Void a shipping label","description":"Asks the carrier to refund a label that has not been used. Usually answers 202 with the label `void_pending`: a carrier takes days to agree, and the postage goes back to the card when it does. The card processing is not returned. The despatch stays, with its tracking number cleared, so a new label can be bought for it. Asking twice is safe.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"labelId","in":"path","required":true,"description":"The label.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ShippingLabel"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/metafields":{"get":{"operationId":"listOrderMetafields","summary":"List an order’s metafields","description":"Every metafield value set on an order, each with its definition.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setOrderMetafields","summary":"Set an order’s metafields","description":"Sets up to 25 values in one call. A null value clears its field; keys not named are left alone. An app may set only the fields its manifest declares.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"minItems":1,"maxItems":25,"type":"array","items":{"type":"object","properties":{"namespace":{"default":"custom","type":"string"},"key":{"type":"string"},"value":{}},"required":["key"]}}},"required":["metafields"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/return-reasons":{"post":{"operationId":"createReturnReason","summary":"Add a return reason","description":"A reason of the shop’s own, in its own words. It goes last and is offered from the next return. `code` is one of the platform’s, because review rules read that and not the words.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["wrong_size","wrong_item_sent","damaged_in_transit","defective","not_as_described","looks_different_to_photo","quality_below_expectation","arrived_late","changed_mind","other"]},"label":{"type":"string","minLength":1,"maxLength":80},"refundsShipping":{"type":"boolean"},"waivesRestockingFee":{"type":"boolean"},"requiresReturn":{"type":"boolean"}},"required":["code","label"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"code":{"type":"string","enum":["wrong_size","wrong_item_sent","damaged_in_transit","defective","not_as_described","looks_different_to_photo","quality_below_expectation","arrived_late","changed_mind","other"]},"label":{"type":"string"},"refundsShipping":{"type":"boolean"},"waivesRestockingFee":{"type":"boolean"},"requiresReturn":{"type":"boolean"},"defaultDisposition":{"type":"string","enum":["restock","damaged","discard","quarantine","return_to_vendor"]},"position":{"type":"number"},"shopAdded":{"type":"boolean"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","code","label","refundsShipping","waivesRestockingFee","requiresReturn","defaultDisposition","position","shopAdded","archivedAt","createdAt","updatedAt"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/fulfillments/{fulfillmentId}":{"delete":{"operationId":"voidFulfillment","summary":"Take back a despatch","description":"For a parcel recorded and never really sent. Units go back to the shelves they came from, held for the order again, and the order steps back. Refused once a carrier has it, for a supplier’s or a digital despatch, for units refunded or returned, and while a label is live. The buyer is not emailed.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"fulfillmentId","in":"path","required":true,"description":"The fulfillment.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fulfillment":{"$ref":"#/components/schemas/Fulfillment"},"restocked":{"type":"integer","description":"Units that went back on a shelf."},"estimated":{"type":"boolean","description":"True when no shelf record exists and the despatch’s one location was used."}},"required":["fulfillment","restocked","estimated"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"correctFulfillmentTracking","summary":"Correct a despatch’s tracking","description":"Corrects a carrier or tracking number somebody typed. Refused for a label bought here, whose number belongs to the label, and for a cancelled despatch. No email is sent.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}},{"name":"fulfillmentId","in":"path","required":true,"description":"The fulfillment.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"carrier":{"type":"string","minLength":1,"maxLength":120},"trackingNumber":{"type":"string","minLength":1,"maxLength":120},"trackingUrl":{"anyOf":[{"type":"string","maxLength":2000,"format":"uri"},{"type":"null"}]}},"required":["carrier","trackingNumber"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Fulfillment"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/details/preview":{"post":{"operationId":"previewOrderDetails","summary":"See what correcting an order’s details would mean","description":"Says which fields would change, and whether tax or delivery is affected. Changes nothing. When it has notices, hand its `digest` to `updateOrderDetails` as `acknowledged`.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"buyerEmail":{"type":"string","maxLength":320,"format":"email"},"buyerFirstName":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"buyerLastName":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"buyerPhone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"shippingAddress":{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"line_one":{"type":"string","minLength":1,"maxLength":200},"line_two":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":120},"state":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"postal_code":{"type":"string","minLength":1,"maxLength":32}},"required":["line_one","city","country","postal_code"],"additionalProperties":false},"acknowledged":{"type":"string","minLength":64,"maxLength":64}},"additionalProperties":false}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"fields":{"type":"array","items":{"type":"string"},"description":"Which fields would change, by name."},"notices":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["tax_stays","delivery_differs","delivery_unquoted"]},"charged":{"description":"What was charged for delivery, in minor units.","type":"integer"},"quoted":{"description":"What this address would come to, in minor units.","type":"integer"}},"required":["kind"]}},"digest":{"type":"string","description":"Pass this as `acknowledged` when there are notices."}},"required":["fields","notices","digest"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/hold":{"post":{"operationId":"holdOrder","summary":"Keep an order back from being sent","description":"Stops a paid order being sent until it is released. Nothing else about it changes and the shopper is not told. An order already on hold keeps the reason it was first held for.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"held":{"type":"boolean"}},"required":["held"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"releaseOrderHold","summary":"Release an order kept back","description":"Lets the order be sent again. An order that was not held is left as it is.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"held":{"type":"boolean"}},"required":["held"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/facets":{"get":{"operationId":"listOrderFacets","summary":"List the tags a shop’s orders carry","description":"For the controls that narrow the list. The commonest first, at most a hundred.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}}},"required":["tags"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/tags":{"patch":{"operationId":"changeOrderTags","summary":"Change an order’s tags","description":"Puts tags on and takes them off by name, so two people labelling one order do not lose each other’s work. Sending the same change twice leaves the order as the first left it. Tags are the shop’s own and are never shown to a shopper.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"add":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"remove":{"default":[],"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"}}},"required":["tags"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/notes":{"get":{"operationId":"listOrderNotes","summary":"List an order’s notes","description":"What the shop has written about the order, oldest first.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderNote"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addOrderNote","summary":"Add a note to an order","description":"Adds a note for the shop’s staff. Notes cannot be edited or deleted; a correction is another note.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":5000,"description":"Trimmed of spaces before it is measured."}},"required":["body"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderNote"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/payments":{"post":{"operationId":"recordOrderPayment","summary":"Record an invoice payment","description":"Records that an order placed on account has been paid, by bank transfer, cheque or any other way outside the shop. Only for an order on payment terms, and only once. Emits `order.paid.v1`, so what follows a card payment follows this too.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","minimum":0},"method":{"type":"string","maxLength":80},"reference":{"type":"string","maxLength":200}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Order"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/refunds":{"get":{"operationId":"listOrderRefunds","summary":"List an order’s refunds","description":"Every adjustment to the order’s money, newest first: refunds, and store credit, returns, exchanges, cancellations and disputes.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderAdjustment"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"refundOrder","summary":"Refund an order","description":"Refunds all or part of an order, everything still refundable when `amount` is left out. A card payment is refunded to the card; an order on account or paid with credit is recorded as refunded with nothing sent. Refused for an order imported from another platform, one paid in stablecoins, one whose payment has not completed, and an amount past what is left. Emits `order.refunded.v1`. Send an `Idempotency-Key` header to make a retry safe: a second request with the same key answers what the first did.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0},"reason":{"type":"string","enum":["duplicate","fraudulent","requested_by_customer","other"]},"description":{"type":"string","maxLength":500},"lineItems":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0}},"required":["lineItemId","quantity"]}},"restock":{"default":false,"type":"boolean"},"valueOfLines":{"type":"boolean"}}}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"adjustment":{"$ref":"#/components/schemas/OrderAdjustment"},"refundedAmount":{"type":"integer","description":"Refunded on the order so far, this included."},"refundableAmount":{"type":"integer","description":"The total less what has been refunded."}},"required":["adjustment","refundedAmount","refundableAmount"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/orders/{orderId}/returns":{"get":{"operationId":"listOrderReturns","summary":"List an order’s returns","description":"The returns asked for on this order, and in `returnable` each line with what could still come back and why not. Also open to `returns:read`, a permission for the shop front.","tags":["Orders"],"x-storeware-scopes":["orders:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"returnable":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"variantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"productId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"title":{"type":"string"},"variantTitle":{"type":["string","null"]},"sku":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"quantityOrdered":{"type":"integer"},"quantityShipped":{"type":"integer"},"quantityReturned":{"type":"integer"},"returnable":{"type":"integer","description":"What could be asked to come back now."},"unitAmount":{"type":"integer","description":"Minor units."},"refundValue":{"type":"integer","description":"What those units are worth back, tax included, in minor units."},"taxValue":{"type":"integer","description":"The tax in `refundValue`."},"deliveredAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"windowClosesAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"eligible":{"type":"boolean"},"ineligibleReason":{"anyOf":[{"type":"string","enum":["window_closed","nothing_shipped","fully_returned"]},{"type":"null"}]}},"required":["lineItemId","variantId","productId","title","variantTitle","sku","imageUrl","quantityOrdered","quantityShipped","quantityReturned","returnable","unitAmount","refundValue","taxValue","deliveredAt","windowClosesAt","eligible","ineligibleReason"]}}},"required":["returns","returnable"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"requestReturn","summary":"Open a return","description":"Opens a return of some of an order’s sent lines. With `orders:write` a closed return window can be overridden. Approved at once when the shop’s policy approves returns on its own. Emits `return.requested.v1`. Also open to `returns:write`, a permission for the shop front.","tags":["Orders"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"orderId","in":"path","required":true,"description":"The order.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lines":{"minItems":1,"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer","exclusiveMinimum":0},"reasonId":{"type":"string","format":"uuid"},"note":{"type":"string","maxLength":500}},"required":["lineItemId","quantity"]}},"overrideWindow":{"default":false,"type":"boolean"},"origin":{"type":"string","enum":["storefront","agent","admin","plugin"]},"merchantNote":{"type":"string","maxLength":2000}},"required":["lines"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Return"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/payments/payouts":{"get":{"operationId":"getPayoutSummary","summary":"Read the shop’s balance and payouts","description":"What the shop holds, its last ten payouts to the bank, and any failure on record. Reading only: the bank account and the schedule are the owner’s to change in the admin.","tags":["Payments"],"x-storeware-scopes":["payments:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PayoutSummary"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers":{"get":{"operationId":"listCustomers","summary":"List customers","description":"A page of customers, newest first unless `sort` says otherwise, each with what they have bought. Archived customers are left out unless `archived` asks for them. Each narrowing takes some away, and a value that cannot be read is ignored. `meta.breakdown` counts every customer not archived; send `breakdown=0` to leave it out.","tags":["Customers"],"x-storeware-scopes":["customers:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"search","in":"query","required":false,"description":"Words in the email, first name or last name.","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["created_desc","created_asc","name_asc","name_desc"]}},{"name":"accountType","in":"query","required":false,"schema":{"type":"string","enum":["guest","registered","business"]}},{"name":"acceptsMarketing","in":"query","required":false,"description":"`1` for those who agreed to be emailed, `0` for those who did not.","schema":{"type":"string","enum":["0","1"]}},{"name":"archived","in":"query","required":false,"description":"`1` lists archived customers among the rest, `only` lists the archive alone.","schema":{"type":"string","enum":["1","only"]}},{"name":"tags","in":"query","required":false,"description":"Comma separated: carrying any of these, up to ten.","schema":{"type":"string"}},{"name":"orders","in":"query","required":false,"description":"`none` for those who never ordered, or a number: at least that many orders.","schema":{"type":"string"}},{"name":"spent","in":"query","required":false,"description":"Have spent at least this, in minor units, after refunds.","schema":{"type":"integer","minimum":1}},{"name":"recent","in":"query","required":false,"description":"Have ordered within this many days.","schema":{"type":"integer","minimum":1}},{"name":"quiet","in":"query","required":false,"description":"Have ordered, and not within this many days.","schema":{"type":"integer","minimum":1}},{"name":"country","in":"query","required":false,"description":"Two letters: they live there or have had an order sent there.","schema":{"type":"string"}},{"name":"bought","in":"query","required":false,"description":"Have bought this product.","schema":{"type":"string","format":"uuid"}},{"name":"breakdown","in":"query","required":false,"description":"`0` leaves `meta.breakdown` out.","schema":{"type":"string","enum":["0"]}},{"name":"limit","in":"query","required":false,"description":"How many to return, up to 250. Fifty when not given.","schema":{"type":"integer","minimum":1,"maximum":250}},{"name":"offset","in":"query","required":false,"description":"How many to skip, for the next page.","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerSummary"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"How many match, across every page."},"breakdown":{"description":"Every customer not archived, whatever the page asks. Left out with `breakdown=0`.","type":"object","properties":{"total":{"type":"integer"},"registered":{"type":"integer"},"withOrders":{"type":"integer","description":"Have at least one order not cancelled."},"acceptsMarketing":{"type":"integer"}},"required":["total","registered","withOrders","acceptsMarketing"]}},"required":["total"]}},"required":["data","meta"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCustomer","summary":"Create a customer","description":"Adds somebody who has not been through the checkout, as a guest. Marketing consent cannot be set here: a customer added this way starts without it. An email another customer of the shop holds, an archived one included, is a 409. Send an `Idempotency-Key` header to make a retry safe.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email"},"firstName":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"defaultAddress":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"line_one":{"type":"string","minLength":1,"maxLength":200},"line_two":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":120},"state":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"postal_code":{"type":"string","minLength":1,"maxLength":32}},"required":["line_one","city","country","postal_code"],"additionalProperties":false},{"type":"null"}]},"tags":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"taxExempt":{"type":"boolean"},"taxExemptionReference":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"acceptsMarketing":{"not":{}}},"required":["email"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/facets":{"get":{"operationId":"listCustomerFacets","summary":"List the tags and countries customers have","description":"The tags the shop’s customers carry and the countries they live in or have had orders sent to, the commonest first, counted over customers not archived. For offering the values `tags` and `country` can narrow `listCustomers` by.","tags":["Customers"],"x-storeware-scopes":["customers:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"string"},"description":"Up to 100."},"countries":{"type":"array","items":{"type":"string"},"description":"Two letter codes, up to 250."}},"required":["tags","countries"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}":{"get":{"operationId":"getCustomer","summary":"Get a customer","description":"The customer, with their 100 most recent orders in `meta.orders`.","tags":["Customers"],"x-storeware-scopes":["customers:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerSummary"},"meta":{"type":"object","properties":{"orders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"sessionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"customerId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"buyerProven":{"type":"boolean"},"orderNumber":{"type":"string"},"customerNote":{"type":["string","null"]},"status":{"type":"string","enum":["created","confirmed","manual_review","processing","shipped","delivered","canceled"]},"currency":{"type":"string"},"locale":{"type":["string","null"]},"buyerEmail":{"type":"string"},"buyerFirstName":{"type":["string","null"]},"buyerLastName":{"type":["string","null"]},"buyerPhone":{"type":["string","null"]},"shippingAddress":{"anyOf":[{},{"type":"null"}]},"billingAddress":{"anyOf":[{},{"type":"null"}]},"fulfillmentOption":{"anyOf":[{},{"type":"null"}]},"subtotalAmount":{"type":"number"},"discountAmount":{"type":"number"},"fulfillmentAmount":{"type":"number"},"taxAmount":{"type":"number"},"fulfillmentTaxAmount":{"type":"number"},"fulfillmentDiscountAmount":{"type":"number"},"companyId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"priceListId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"paymentTermsNetDays":{"type":["number","null"]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"purchaseOrderNumber":{"type":["string","null"]},"totalAmount":{"type":"number"},"refundedAmount":{"type":"number"},"changeAmount":{"type":"number"},"creditAppliedAmount":{"type":"number"},"taxCalculationId":{"type":["string","null"]},"taxTransactionId":{"type":["string","null"]},"discountId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"discountCode":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"heldAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"heldBy":{"type":["string","null"]},"holdReason":{"type":["string","null"]},"origin":{"type":"string","enum":["storefront","agent","admin","plugin","imported","subscription"]},"agentId":{"type":["string","null"]},"conversationId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"referralId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"adLinkId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"placedAt":{"type":"string","format":"date-time"},"canceledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"subscriptionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","sessionId","customerId","buyerProven","orderNumber","customerNote","status","currency","locale","buyerEmail","buyerFirstName","buyerLastName","buyerPhone","shippingAddress","billingAddress","fulfillmentOption","subtotalAmount","discountAmount","fulfillmentAmount","taxAmount","fulfillmentTaxAmount","fulfillmentDiscountAmount","companyId","priceListId","paymentTermsNetDays","dueAt","purchaseOrderNumber","totalAmount","refundedAmount","changeAmount","creditAppliedAmount","taxCalculationId","taxTransactionId","discountId","discountCode","tags","heldAt","heldBy","holdReason","origin","agentId","conversationId","referralId","adLinkId","placedAt","canceledAt","subscriptionId","createdAt","updatedAt"]},"description":"Newest first, up to 100."}},"required":["orders"]}},"required":["data","meta"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateCustomer","summary":"Update a customer","description":"Changes only the fields sent; a null empties one, and an address is replaced whole. Marketing consent cannot be set here. Changing the email to one another customer holds is a 409, and any new email counts as unverified until the customer signs in with it. `note` is the merchant’s own and is never shown to the customer. Send an `Idempotency-Key` header to make a retry safe.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email"},"firstName":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"defaultAddress":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"line_one":{"type":"string","minLength":1,"maxLength":200},"line_two":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":120},"state":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"postal_code":{"type":"string","minLength":1,"maxLength":32}},"required":["line_one","city","country","postal_code"],"additionalProperties":false},{"type":"null"}]},"tags":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":80}},"taxExempt":{"type":"boolean"},"taxExemptionReference":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"acceptsMarketing":{"not":{}},"note":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/addresses":{"get":{"operationId":"listCustomerAddresses","summary":"List a customer’s saved addresses","description":"The addresses a customer has besides their default, oldest first, up to 50. The default is `defaultAddress` on the customer and is not repeated here.","tags":["Customers"],"x-storeware-scopes":["customers:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerSavedAddress"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"How many match, across every page."}},"required":["total"]}},"required":["data","meta"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addCustomerAddress","summary":"Save an address for a customer","description":"Saves another address, whole. One the customer already has, their default included, is a 409, and so is one past the 50 a customer can keep. Send an `Idempotency-Key` header to make a retry safe.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"line_one":{"type":"string","minLength":1,"maxLength":200},"line_two":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":120},"state":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"postal_code":{"type":"string","minLength":1,"maxLength":32}},"required":["line_one","city","country","postal_code"],"additionalProperties":false}},"required":["address"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerSavedAddress"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/addresses/{addressId}":{"patch":{"operationId":"updateCustomerAddress","summary":"Correct a customer’s saved address","description":"Replaces the address whole. Sending what is already there changes nothing. Lines that match another address the customer has are a 409. Send an `Idempotency-Key` header to make a retry safe.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}},{"name":"addressId","in":"path","required":true,"description":"The address.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"line_one":{"type":"string","minLength":1,"maxLength":200},"line_two":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"type":"string","minLength":1,"maxLength":120},"state":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"postal_code":{"type":"string","minLength":1,"maxLength":32}},"required":["line_one","city","country","postal_code"],"additionalProperties":false}},"required":["address"],"additionalProperties":false}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerSavedAddress"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeCustomerAddress","summary":"Remove a customer’s saved address","description":"Removes one saved address. The default is not one and stays. Send an `Idempotency-Key` header to make a retry safe.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}},{"name":"addressId","in":"path","required":true,"description":"The address.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"removed":{"type":"boolean","const":true}},"required":["removed"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/addresses/{addressId}/default":{"post":{"operationId":"makeCustomerAddressDefault","summary":"Make a saved address the default","description":"Puts this address on the customer as `defaultAddress`, and saves the old default in its place, so no address is lost. Send an `Idempotency-Key` header to make a retry safe.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}},{"name":"addressId","in":"path","required":true,"description":"The address.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"madeDefault":{"type":"boolean","const":true}},"required":["madeDefault"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/archive":{"post":{"operationId":"archiveCustomer","summary":"Archive a customer","description":"Puts the customer away without deleting anything: their orders, credit and email stay theirs. They leave the lists and totals, and are signed out of their account on the shop until unarchived. Archiving one already archived changes nothing.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/unarchive":{"post":{"operationId":"unarchiveCustomer","summary":"Unarchive a customer","description":"Brings the customer back as they were. One not archived is answered as it is.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/marketing-consent":{"delete":{"operationId":"withdrawCustomerMarketingConsent","summary":"Withdraw a customer’s marketing consent","description":"Records that the customer asked not to be emailed, and sends `customer.consent_withdrawn.v1` with their email. Consent can only be withdrawn here, never given. A customer already off the list is answered as they are.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/metafields":{"get":{"operationId":"listCustomerMetafields","summary":"List a customer’s metafields","description":"Every metafield value set on a customer, each with its definition.","tags":["Customers"],"x-storeware-scopes":["customers:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setCustomerMetafields","summary":"Set a customer’s metafields","description":"Sets up to 25 values in one call. A null value clears its field; keys not named are left alone. An app may set only the fields its manifest declares.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"minItems":1,"maxItems":25,"type":"array","items":{"type":"object","properties":{"namespace":{"default":"custom","type":"string"},"key":{"type":"string"},"value":{}},"required":["key"]}}},"required":["metafields"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/companies":{"get":{"operationId":"listCustomerCompanies","summary":"List the trade accounts a customer buys for","description":"The companies the customer buys on behalf of, by name. At most one today.","tags":["Customers"],"x-storeware-scopes":["companies:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["pending","active","archived"],"description":"Only an `active` account gets its agreed prices."},"taxExempt":{"type":"boolean"},"taxExemptionReference":{"type":["string","null"]},"paymentTermsNetDays":{"description":"Days it has to pay an invoice. Null pays at the till; 0 is due on receipt.","type":["number","null"]},"creditLimitAmount":{"description":"The most it may owe at once, in minor units of `creditCurrency`. Null is no limit.","type":["number","null"]},"creditCurrency":{"type":["string","null"]},"priceListId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"note":{"description":"The merchant’s own note. Never shown to the buyer.","type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","name","slug","status","taxExempt","taxExemptionReference","paymentTermsNetDays","creditLimitAmount","creditCurrency","priceListId","note","createdAt","updatedAt"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/store-credit":{"get":{"operationId":"getCustomerStoreCredit","summary":"Get a customer’s store credit","description":"What the customer holds in each currency, and the entries behind it, newest first. `orders:read` will do in place of `customers:read`.","tags":["Customers"],"x-storeware-scopes":["customers:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many entries to return, up to 200. Fifty when not given.","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"balances":{"type":"array","items":{"type":"object","properties":{"accountId":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"currency":{"type":"string"},"balanceAmount":{"type":"integer","description":"In minor units."}},"required":["accountId","customerId","currency","balanceAmount"]},"description":"One for each currency they hold credit in."},"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"delta":{"type":"number","description":"In minor units. Positive puts credit on, negative spends it."},"currency":{"type":"string","description":"Credit is held per currency."},"balanceAfter":{"type":"number","description":"The balance after this entry, in minor units."},"reason":{"type":"string","enum":["return_refund","goodwill","order_payment","order_canceled","manual_adjustment","exchange_difference","gift_card"]},"note":{"type":["string","null"]},"orderId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"returnId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"adjustmentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"giftCardId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"idempotencyKey":{"type":["string","null"]},"actorType":{"type":["string","null"]},"actorId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","storeId","accountId","delta","currency","balanceAfter","reason","note","orderId","returnId","adjustmentId","giftCardId","sessionId","idempotencyKey","actorType","actorId","createdAt"]},"description":"Across every currency, newest first."}},"required":["balances","entries"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"issueCustomerStoreCredit","summary":"Give a customer store credit","description":"Puts credit on the customer’s account in one currency, for them to spend at checkout. `amount` is in minor units. It needs `orders:write`, as a refund does. An `idempotencyKey` already used is refused, so a retry cannot credit twice.","tags":["Customers"],"x-storeware-scopes":["orders:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0},"currency":{"type":"string","minLength":3,"maxLength":3},"reason":{"default":"goodwill","type":"string","enum":["return_refund","goodwill","order_payment","order_canceled","manual_adjustment","exchange_difference","gift_card"]},"note":{"type":"string","maxLength":500},"orderId":{"type":"string","format":"uuid"},"idempotencyKey":{"type":"string","maxLength":200}},"required":["amount","currency"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"accountId":{"type":"string","format":"uuid"},"delta":{"type":"number","description":"In minor units. Positive puts credit on, negative spends it."},"currency":{"type":"string","description":"Credit is held per currency."},"balanceAfter":{"type":"number","description":"The balance after this entry, in minor units."},"reason":{"type":"string","enum":["return_refund","goodwill","order_payment","order_canceled","manual_adjustment","exchange_difference","gift_card"]},"note":{"type":["string","null"]},"orderId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"returnId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"adjustmentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"giftCardId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"sessionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"idempotencyKey":{"type":["string","null"]},"actorType":{"type":["string","null"]},"actorId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","storeId","accountId","delta","currency","balanceAfter","reason","note","orderId","returnId","adjustmentId","giftCardId","sessionId","idempotencyKey","actorType","actorId","createdAt"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/customers/{customerId}/memory":{"get":{"operationId":"getCustomerMemory","summary":"Get what the shop remembers about a customer","description":"What the customer told the shop they want while shopping signed in (a budget, requirements, context), which the shop keeps to narrow and rank what it shows them.","tags":["Customers"],"x-storeware-scopes":["customers:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"profile":{"type":"object","properties":{"maxPrice":{"description":"The most they said they would pay, in whole units of the currency, not minor units.","type":["number","null"]},"minPrice":{"description":"The least, in the same units.","type":["number","null"]},"requiredAttributes":{"description":"What they said it must be, such as a colour or a size.","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]}},"context":{"description":"Who it is for, the occasion, the conditions. It ranks what they see and never hides anything.","type":"array","items":{"type":"string"}}}},"confirmedAt":{"type":"string","format":"date-time","description":"When they last said any of it."}},"required":["profile","confirmedAt"]},{"type":"null"}],"description":"Null when the shop keeps nothing about them."}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"forgetCustomerMemory","summary":"Make the shop forget what a customer told it","description":"Removes all of it, or one part. There is no default: a body that names nothing is a 400. Answers with what remains.","tags":["Customers"],"x-storeware-scopes":["customers:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"customerId","in":"path","required":true,"description":"The customer.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"forget":{"type":"string","enum":["all","budget","context","attribute"],"description":"What to forget. `attribute` forgets one requirement, named by `key`."},"key":{"description":"With `attribute`: the requirement’s key.","type":"string"}},"required":["forget"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"profile":{"type":"object","properties":{"maxPrice":{"description":"The most they said they would pay, in whole units of the currency, not minor units.","type":["number","null"]},"minPrice":{"description":"The least, in the same units.","type":["number","null"]},"requiredAttributes":{"description":"What they said it must be, such as a colour or a size.","type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"]}},"context":{"description":"Who it is for, the occasion, the conditions. It ranks what they see and never hides anything.","type":"array","items":{"type":"string"}}}},"confirmedAt":{"type":"string","format":"date-time","description":"When they last said any of it."}},"required":["profile","confirmedAt"]},{"type":"null"}],"description":"Null when the shop keeps nothing about them."}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/metafield-definitions":{"get":{"operationId":"listMetafieldDefinitions","summary":"List metafield definitions","description":"Every field the shop records, by kind of record and then position, the shop’s own and those its apps declare.","tags":["Metafields"],"x-storeware-scopes":["stores:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"ownerType","in":"query","required":false,"description":"Only the fields for this kind of record. Any other value is a 400.","schema":{"type":"string","enum":["product","variant","collection","customer","order","store"]}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MetafieldDefinition"}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/metafield-definitions/{definitionId}":{"get":{"operationId":"getMetafieldDefinition","summary":"Get a metafield definition","tags":["Metafields"],"x-storeware-scopes":["stores:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"definitionId","in":"path","required":true,"description":"The definition.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetafieldDefinition"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateMetafieldDefinition","summary":"Update a metafield definition","description":"Changes only the fields sent. The namespace, key, type and list flag cannot change. An app may change only the fields its manifest declared; any other answers 403 `metafield_definition_not_yours`.","tags":["Metafields"],"x-storeware-scopes":["stores:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"definitionId","in":"path","required":true,"description":"The definition.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"validations":{"default":{},"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"minLength":{"type":"integer","minimum":0},"maxLength":{"type":"integer","minimum":1},"choices":{"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"scale":{"type":"integer","minimum":0,"maximum":8}}},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MetafieldDefinition"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteMetafieldDefinition","summary":"Delete a metafield definition","description":"Refused while any record holds a value for it, unless `withValues=1` is sent, which deletes every value with it. An app may delete only the fields its manifest declared; any other answers 403 `metafield_definition_not_yours`.","tags":["Metafields"],"x-storeware-scopes":["stores:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}},{"name":"definitionId","in":"path","required":true,"description":"The definition.","schema":{"type":"string"}},{"name":"withValues","in":"query","required":false,"description":"`1` deletes the field’s values too.","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deletedValues":{"type":"integer","description":"How many values went with it."}},"required":["deletedValues"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/metafields":{"get":{"operationId":"listStoreMetafields","summary":"List the shop’s metafields","description":"Every metafield value set on the shop, each with its definition.","tags":["Metafields"],"x-storeware-scopes":["stores:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setStoreMetafields","summary":"Set the shop’s metafields","description":"Sets up to 25 values in one call. A null value clears its field; keys not named are left alone. An app may set only the fields its manifest declares.","tags":["Metafields"],"x-storeware-scopes":["stores:write"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"metafields":{"minItems":1,"maxItems":25,"type":"array","items":{"type":"object","properties":{"namespace":{"default":"custom","type":"string"},"key":{"type":"string"},"value":{}},"required":["key"]}}},"required":["metafields"]}}}},"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/app-billing":{"get":{"operationId":"getAppBilling","summary":"Get your app’s billing on this shop","description":"The plan in force, this period’s usage, a cheaper plan waiting to start, the charges waiting for the merchant, the one-time charges approved among your last 50, and the plans your installed release declares, priced in the shop’s currency.","tags":["App billing"],"x-storeware-scopes":[],"x-storeware-app-only":true,"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"currency":{"type":"string","enum":["usd","gbp","eur","inr"],"description":"The shop’s billing currency. Every amount here is in its minor unit: cents, pence, paise."},"subscription":{"anyOf":[{"$ref":"#/components/schemas/AppSubscription"},{"type":"null"}]},"usage":{"anyOf":[{"$ref":"#/components/schemas/AppUsage"},{"type":"null"}],"description":"Only on a plan that charges by use."},"scheduled":{"anyOf":[{"$ref":"#/components/schemas/AppSubscription"},{"type":"null"}],"description":"A cheaper plan the merchant approved, to start when this period ends."},"pending":{"type":"object","properties":{"subscriptions":{"type":"array","items":{"$ref":"#/components/schemas/AppSubscription"}},"purchases":{"type":"array","items":{"$ref":"#/components/schemas/AppPurchase"}}},"required":["subscriptions","purchases"]},"purchases":{"type":"array","items":{"$ref":"#/components/schemas/AppPurchase"},"description":"One-time charges approved, newest first."},"plans":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"interval":{"type":"string","enum":["month","year"]},"amountMinor":{"type":"integer","description":"Each period’s price in the shop’s currency."},"currency":{"type":"string","enum":["usd","gbp","eur","inr"],"description":"The shop’s billing currency. Every amount here is in its minor unit: cents, pence, paise."},"trialDays":{"type":"integer"},"features":{"type":"array","items":{"type":"string"}},"releaseId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The release that declares it."},"usageCapMinor":{"anyOf":[{"type":"integer"},{"type":"null"}]},"usageTerms":{"type":["string","null"]}},"required":["key","name","description","interval","amountMinor","currency","trialDays","features","releaseId"]}}},"required":["currency","subscription","usage","scheduled","pending","purchases","plans"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/app-billing/subscriptions":{"post":{"operationId":"requestAppSubscription","summary":"Ask the merchant to approve a plan","description":"Asks for one of the plans your installed release declares. Send the merchant to `confirmationUrl`: nothing is charged until they approve, and they have 48 hours to. `returnUrl` must be https on your app’s own address (its `app.url`, webhook URL or a redirect URI). Asking for the plan already in force answers with it and changes nothing. At most 5 charges may wait for an answer at once. Send the same `idempotencyKey` again and you are answered with the first result, so a retry never charges twice.","tags":["App billing"],"x-storeware-scopes":[],"x-storeware-app-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","minLength":1,"maxLength":32},"returnUrl":{"type":"string","maxLength":2000,"format":"uri"},"test":{"type":"boolean"},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200}},"required":["plan","returnUrl"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AppSubscription"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/app-billing/subscriptions/{subscriptionId}/cancel":{"post":{"operationId":"cancelAppSubscription","summary":"End your plan on this shop","description":"Ends the plan when the period the merchant has paid for ends. Until then it stays in force.","tags":["App billing"],"x-storeware-scopes":[],"x-storeware-app-only":true,"parameters":[{"name":"subscriptionId","in":"path","required":true,"description":"The subscription.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AppSubscription"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/app-billing/purchases":{"post":{"operationId":"requestAppPurchase","summary":"Ask the merchant to approve a one-time charge","description":"Give a price in every currency: the shop is charged in its own, and nothing is converted. Send the merchant to `confirmationUrl`; nothing is charged until they approve, and they have 48 hours to. `returnUrl` follows the same rule as for a plan. Send the same `idempotencyKey` again and you are answered with the first result, so a retry never charges twice.","tags":["App billing"],"x-storeware-scopes":[],"x-storeware-app-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"prices":{"type":"object","properties":{"usd":{"type":"integer","minimum":1,"maximum":10000000},"gbp":{"type":"integer","minimum":1,"maximum":10000000},"eur":{"type":"integer","minimum":1,"maximum":10000000},"inr":{"type":"integer","minimum":1,"maximum":10000000}},"required":["usd","gbp","eur","inr"],"additionalProperties":false},"returnUrl":{"type":"string","maxLength":2000,"format":"uri"},"test":{"type":"boolean"},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200}},"required":["name","prices","returnUrl"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AppPurchase"}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/app-billing/usage":{"post":{"operationId":"recordAppUsage","summary":"Report what the shop used","description":"Adds to this period’s usage, in the plan’s currency, on a plan that charges by use. It is billed when the period ends. Past the period’s cap it is refused with 402 `app_usage_cap_reached`, and on a plan with no usage with 409. Send the same `idempotencyKey` again and you are answered with the first result, so a retry never charges twice.","tags":["App billing"],"x-storeware-scopes":[],"x-storeware-app-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":1,"maximum":10000000},"description":{"type":"string","minLength":1,"maxLength":200},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200}},"required":["amountMinor","description"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amountMinor":{"type":"integer"},"currency":{"type":"string"},"description":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"usage":{"description":"The period’s usage after this record.","$ref":"#/components/schemas/AppUsage"}},"required":["id","amountMinor","currency","description","createdAt","usage"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/app-billing/credits":{"post":{"operationId":"creditAppShop","summary":"Credit the shop","description":"Takes an amount off the shop’s next statement, in its billing currency. A credit can come to no more than the shop paid your app in the last year, less what it has already been credited; past that it is refused with 409. Send the same `idempotencyKey` again and you are answered with the first result, so a retry never charges twice.","tags":["App billing"],"x-storeware-scopes":[],"x-storeware-app-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amountMinor":{"type":"integer","minimum":1,"maximum":10000000},"description":{"type":"string","minLength":1,"maxLength":200},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200}},"required":["amountMinor","description"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amountMinor":{"type":"integer"},"currency":{"type":"string"},"description":{"type":"string"},"test":{"type":"boolean","description":"True when no money moves."},"createdAt":{"type":"string","format":"date-time"}},"required":["id","amountMinor","currency","description","test","createdAt"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/app/settings":{"get":{"operationId":"getAppSettings","summary":"Get what the merchant set for your app","description":"Every field your installed release declares in `[[settings]]`, by its `key`: what the merchant saved, else its `default`, else null. A `secret` comes back in the clear, to your app alone. A key an older release declared and yours no longer does is left out. When the merchant saves, you are sent `app.settings_updated.v1` with the keys that changed.","tags":["App settings"],"x-storeware-scopes":[],"x-storeware-app-only":true,"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean","null"]}},"updatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When the merchant last saved, or null when they never have."}},"required":["values","updatedAt"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/app/assets":{"post":{"operationId":"uploadAppAsset","summary":"Put a picture on Storeware for your components","description":"Stores a PNG, JPEG, WebP, GIF or AVIF picture of at most 5 MB, for this shop, and answers with its address on `cdn.mystoreware.com`, the one host an image in your components may come from. Its bytes are checked, so the type you send must be the type it is; SVG is refused. Sending the same picture again gives the same address.","tags":["App settings"],"x-storeware-scopes":[],"x-storeware-app-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","minLength":1,"maxLength":6990508,"pattern":"^[A-Za-z0-9+/]+={0,2}$","description":"The picture’s bytes, as base64. At most 5 MB of picture."},"contentType":{"type":"string","enum":["image/png","image/jpeg","image/webp","image/gif","image/avif"],"description":"What the picture is. It must match the bytes, which are checked."}},"required":["data","contentType"]}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string","description":"Where the picture is served from. Use it in an image node."},"contentType":{"type":"string"},"sizeBytes":{"type":"integer"},"sha256":{"type":"string","description":"The hash of the bytes, which names the file."}},"required":["url","contentType","sizeBytes","sha256"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/app/events":{"post":{"operationId":"fireAppTrigger","summary":"Fire one of your automation triggers","description":"Tells the shop that something your app declares under `[[automations.triggers]]` happened, so every automation the merchant built on it runs. `trigger` is the trigger's `key` in your installed release. `data` carries its declared fields: a field you did not declare is dropped, a declared field of the wrong type is refused with 400, and the whole may be at most 16 KB. Answered 202, before the automations run. At most 60 a minute and 1000 an hour for each installation; past that, 429 with `Retry-After`. The event is not sent to any app's webhooks, yours included.","tags":["App automations"],"x-storeware-scopes":[],"x-storeware-app-only":true,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trigger":{"type":"string","pattern":"^[a-z][a-z_]{1,31}$","description":"The trigger’s `key`."},"data":{"description":"The trigger’s fields, by `key`. A null or missing field is read as unknown.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean","null"]}}},"required":["trigger"]}}}},"responses":{"202":{"description":"Accepted, and finished later.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"trigger":{"type":"string","description":"The trigger as a merchant’s rule names it: `app:<slug>:<key>`."},"data":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":["string","number","boolean"]},"description":"What was kept, after undeclared fields were dropped."}},"required":["trigger","data"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/stores/{storeId}/automations/vocabulary":{"get":{"operationId":"getAutomationVocabulary","summary":"Get what this shop’s automations may be made of","description":"The platform’s triggers with the fields each carries, its steps and its exits, and the triggers and actions the shop’s installed apps add, each under the app’s name. An app’s trigger is named `app:<slug>:<key>`; a rule names it as `{ \"kind\": \"app\", \"app\": \"<slug>\", \"trigger\": \"<key>\" }` and an action as a step of type `app_action`.","tags":["App automations"],"x-storeware-scopes":["automations:read"],"parameters":[{"name":"storeId","in":"path","required":true,"description":"The shop.","schema":{"type":"string"}}],"responses":{"200":{"description":"Done.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"triggers":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"event"},"id":{"type":"string","description":"The topic, such as `order.paid.v1`."},"label":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"What a condition names: `order.total`, or `data.<key>` for an app."},"label":{"type":"string"},"holds":{"type":"string","enum":["money","number","string","boolean","enum"]},"ops":{"type":"array","items":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","not_in","contains","exists","missing"]}},"values":{"type":"array","items":{"type":"string"}}},"required":["field","label","holds","ops"]}}},"required":["kind","id","label","fields"]},{"type":"object","properties":{"kind":{"type":"string","const":"app"},"id":{"type":"string","description":"`app:<slug>:<key>`."},"app":{"type":"string"},"appName":{"type":"string","description":"The app’s name, as the merchant sees it."},"key":{"type":"string"},"label":{"type":"string"},"description":{"type":["string","null"]},"fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","description":"What a condition names: `order.total`, or `data.<key>` for an app."},"label":{"type":"string"},"holds":{"type":"string","enum":["money","number","string","boolean","enum"]},"ops":{"type":"array","items":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","not_in","contains","exists","missing"]}},"values":{"type":"array","items":{"type":"string"}},"key":{"type":"string"},"type":{"type":"string","enum":["text","number","boolean","date","url"]}},"required":["field","label","holds","ops","key","type"]}}},"required":["kind","id","app","appName","key","label","description","fields"]}]}},"steps":{"type":"array","items":{"type":"object","properties":{"step":{"type":"string"},"does":{"type":"string"}},"required":["step","does"]}},"actions":{"type":"array","items":{"type":"object","properties":{"app":{"type":"string"},"appName":{"type":"string","description":"The app’s name, as the merchant sees it."},"key":{"type":"string"},"label":{"type":"string"},"description":{"type":["string","null"]},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","enum":["text","multi_line_text","number","boolean","url","select"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"]}}},"required":["key","label","type","required"]}}},"required":["app","appName","key","label","description","fields"]}},"exits":{"type":"array","items":{"type":"object","properties":{"exit":{"type":"string"},"means":{"type":"string"}},"required":["exit","means"]}}},"required":["triggers","steps","actions","exits"]}},"required":["data"]}}}},"default":{"description":"An error. See the `type` for which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"The access token your app received for the shop. It lasts 24 hours."}},"schemas":{"AppPurchase":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"amountMinor":{"type":"integer"},"currency":{"type":"string","enum":["usd","gbp","eur","inr"],"description":"The shop’s billing currency. Every amount here is in its minor unit: cents, pence, paise."},"test":{"type":"boolean","description":"True when no money moves."},"status":{"type":"string","enum":["pending","accepted","declined","expired"]},"createdAt":{"type":"string","format":"date-time"},"confirmationUrl":{"description":"Where the merchant approves it, while it waits. Send them there.","type":["string","null"]}},"required":["id","name","amountMinor","currency","test","status","createdAt","confirmationUrl"]},"AppSubscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"plan":{"type":"string","description":"The plan’s `key` in your manifest’s `[[billing.plans]]`."},"name":{"type":"string"},"status":{"type":"string","enum":["pending","active","past_due","frozen","scheduled","canceled","declined","expired"],"description":"`pending` waits for the merchant; `active`, `past_due` and `frozen` are in force; `scheduled` starts when the current period ends."},"amountMinor":{"type":"integer","description":"What each period costs."},"currency":{"type":"string","enum":["usd","gbp","eur","inr"],"description":"The shop’s billing currency. Every amount here is in its minor unit: cents, pence, paise."},"interval":{"type":"string","enum":["month","year"]},"test":{"type":"boolean","description":"True when no money moves."},"trialEndsAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"currentPeriodStart":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"currentPeriodEnd":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"cancelAtPeriodEnd":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"confirmationUrl":{"description":"Where the merchant approves it, while it waits. Send them there.","type":["string","null"]},"usageCapMinor":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The most a period’s usage may come to, for a plan that charges by use."},"usageTerms":{"description":"How usage is priced, in your words.","type":["string","null"]}},"required":["id","plan","name","status","amountMinor","currency","interval","test","trialEndsAt","currentPeriodStart","currentPeriodEnd","cancelAtPeriodEnd","createdAt","confirmationUrl","usageCapMinor","usageTerms"]},"AppUsage":{"type":"object","properties":{"capMinor":{"type":"integer","description":"The most this period’s usage may come to."},"usedMinor":{"type":"integer","description":"What has been reported so far this period."},"terms":{"description":"How usage is priced, in your words.","type":["string","null"]}},"required":["capMinor","usedMinor","terms"]},"Collection":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"title":{"type":"string"},"handle":{"type":"string"},"description":{"type":["string","null"]},"parentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"seoTitle":{"type":["string","null"]},"seoDescription":{"type":["string","null"]},"kind":{"type":"string","enum":["manual","automatic"]},"rules":{"maxItems":10,"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["title","product_type","vendor","tag","price"]},"operator":{"type":"string","enum":["equals","not_equals","contains","starts_with","ends_with","greater_than","less_than"]},"value":{"type":"string","minLength":1,"maxLength":200},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}},"required":["field","operator","value"]},"description":"What an automatic collection matches. Empty on a manual one."},"sortOrder":{"type":"string","enum":["manual","title_asc","title_desc","created_desc","price_asc","price_desc"]},"filterable":{"type":"boolean"},"publishedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","title","handle","description","parentId","seoTitle","seoDescription","kind","rules","sortOrder","filterable","publishedAt","createdAt","updatedAt"]},"Customer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"phone":{"type":["string","null"]},"accountType":{"type":"string","enum":["guest","registered","business"],"description":"`guest` until they first sign in with their email, then `registered`."},"acceptsMarketing":{"type":"boolean","description":"Whether they agreed to be emailed. Only the customer can give it; withdraw it with `withdrawCustomerMarketingConsent`."},"defaultAddress":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"description":"A code where the country has them, such as `CA`.","type":"string"},"country":{"type":"string","description":"Two letters, such as `GB`."},"postal_code":{"type":"string"}},"required":["line_one","city","country","postal_code"]},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"},"description":"The merchant’s labels."},"taxExempt":{"type":"boolean","description":"They pay no tax."},"taxExemptionReference":{"description":"Why they are exempt: a VAT number, a resale certificate.","type":["string","null"]},"note":{"description":"The merchant’s own note. Never shown to the customer.","type":["string","null"]},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When they last signed in with this email. Cleared when the email is changed, until they sign in again."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When they were archived. Lists leave archived customers out unless asked."}},"required":["id","storeId","email","firstName","lastName","phone","accountType","acceptsMarketing","defaultAddress","tags","taxExempt","taxExemptionReference","note","verifiedAt","createdAt","updatedAt","archivedAt"]},"CustomerSavedAddress":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"customerId":{"type":"string","format":"uuid"},"address":{"type":"object","properties":{"name":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"description":"A code where the country has them, such as `CA`.","type":"string"},"country":{"type":"string","description":"Two letters, such as `GB`."},"postal_code":{"type":"string"}},"required":["line_one","city","country","postal_code"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","customerId","address","createdAt","updatedAt"]},"CustomerSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"email":{"type":"string"},"firstName":{"type":["string","null"]},"lastName":{"type":["string","null"]},"phone":{"type":["string","null"]},"accountType":{"type":"string","enum":["guest","registered","business"],"description":"`guest` until they first sign in with their email, then `registered`."},"acceptsMarketing":{"type":"boolean","description":"Whether they agreed to be emailed. Only the customer can give it; withdraw it with `withdrawCustomerMarketingConsent`."},"defaultAddress":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"description":"A code where the country has them, such as `CA`.","type":"string"},"country":{"type":"string","description":"Two letters, such as `GB`."},"postal_code":{"type":"string"}},"required":["line_one","city","country","postal_code"]},{"type":"null"}]},"tags":{"type":"array","items":{"type":"string"},"description":"The merchant’s labels."},"taxExempt":{"type":"boolean","description":"They pay no tax."},"taxExemptionReference":{"description":"Why they are exempt: a VAT number, a resale certificate.","type":["string","null"]},"note":{"description":"The merchant’s own note. Never shown to the customer.","type":["string","null"]},"verifiedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When they last signed in with this email. Cleared when the email is changed, until they sign in again."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When they were archived. Lists leave archived customers out unless asked."},"orderCount":{"type":"integer","description":"Orders that were not cancelled."},"spentAmount":{"type":"integer","description":"What they have spent, in minor units: charged less refunded, over orders not cancelled."},"lastOrderAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When they last ordered."}},"required":["id","storeId","email","firstName","lastName","phone","accountType","acceptsMarketing","defaultAddress","tags","taxExempt","taxExemptionReference","note","verifiedAt","createdAt","updatedAt","archivedAt","orderCount","spentAmount","lastOrderAt"]},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storagePath":{"type":"string","description":"Where the file is kept, from its upload ticket."},"fileName":{"type":"string","description":"The name a buyer’s download is saved under."},"sizeBytes":{"type":["number","null"]},"downloadLimit":{"description":"How many times each buyer may download it. Null is no limit.","type":["number","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","variantId","storeId","storagePath","fileName","sizeBytes","downloadLimit","createdAt"]},"DownloadGrant":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"assetId":{"type":"string","format":"uuid"},"fileName":{"type":"string"},"sizeBytes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"downloadCount":{"type":"integer"},"downloadLimit":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Null means unlimited."},"downloadsRemaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Null when unlimited."},"firstDownloadedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"lastDownloadedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"available":{"type":"boolean","description":"False when the order does not entitle anyone, or the allowance is spent."},"unavailableReason":{"description":"Why not, in English, for the customer.","type":["string","null"]},"unavailable":{"anyOf":[{"type":"string","enum":["unpaid","canceled","refunded","exhausted"]},{"type":"null"}]}},"required":["lineItemId","assetId","fileName","sizeBytes","downloadCount","downloadLimit","downloadsRemaining","firstDownloadedAt","lastDownloadedAt","available","unavailableReason","unavailable"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"What went wrong, for a program: `not_found`, `validation_failed`."},"message":{"type":"string","description":"What went wrong, for a person."},"fields":{"description":"On 422: each field that is wrong, and what is wrong with it.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}}},"requiredScopes":{"description":"On 403: the permissions the call needed.","type":"array","items":{"type":"string"}}},"required":["type","message"]},"requestId":{"type":"string","description":"Quote it when asking for help."}},"required":["error","requestId"]},"Fulfillment":{"type":"object","properties":{"fulfillment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"locationId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"type":{"type":"string","enum":["shipping","pickup","digital"]},"status":{"type":"string","enum":["pending","processing","shipped","in_transit","out_for_delivery","ready_for_pickup","delivered","failed","canceled"]},"carrier":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"trackingUrl":{"type":["string","null"]},"destination":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"}},"required":["line_one","city","country","postal_code"]},{"type":"null"}],"description":"Where it is going."},"estimatedDeliveryEarliest":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"estimatedDeliveryLatest":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"digitalAccessUrl":{"type":["string","null"]},"digitalLicenseKey":{"type":["string","null"]},"digitalExpiresAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"description":{"type":["string","null"]},"supplierConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"supplierOrderId":{"type":["string","null"]},"actorType":{"anyOf":[{"type":"string","enum":["staff","customer","plugin","agent","system"]},{"type":"null"}],"description":"Who recorded it."},"actorId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","orderId","storeId","locationId","type","status","carrier","trackingNumber","trackingUrl","destination","estimatedDeliveryEarliest","estimatedDeliveryLatest","digitalAccessUrl","digitalLicenseKey","digitalExpiresAt","description","supplierConnectionId","supplierOrderId","actorType","actorId","createdAt","updatedAt"]},"events":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fulfillmentId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["processing","shipped","in_transit","out_for_delivery","ready_for_pickup","delivered","failed_attempt","returned"]},"occurredAt":{"type":"string","format":"date-time"},"description":{"type":["string","null"]},"location":{"type":["string","null"]},"sourceKey":{"description":"The carrier’s name for the scan. Null for one a person recorded.","type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","fulfillmentId","storeId","type","occurredAt","description","location","sourceKey","createdAt"]},"description":"Where it has got to, newest first."},"lineItems":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer"}},"required":["lineItemId","quantity"]},"description":"The order’s lines it carries, and how many of each."}},"required":["fulfillment","events","lineItems"]},"InventoryLevel":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"locationId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"onHand":{"type":"number","description":"What is on the shelf."},"reserved":{"type":"number","description":"Held for orders placed and not yet sent."},"available":{"type":"integer","description":"On hand less reserved: what can still be sold."},"updatedAt":{"type":"string","format":"date-time"}},"required":["variantId","locationId","storeId","onHand","reserved","available","updatedAt"]},"Listing":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"description":{"description":"HTML.","type":["string","null"]},"productType":{"type":["string","null"]},"variants":{"type":"integer","description":"How many variants it has. More than one means options, each with its own price."},"price":{"anyOf":[{"type":"object","properties":{"amount":{"type":"integer","description":"In the currency’s minor units, such as pence."},"currency":{"type":"string","description":"An ISO 4217 code, such as `GBP`."}},"required":["amount","currency"]},{"type":"null"}],"description":"Its price in the shop’s currency, when it has one variant and that is priced."},"madeToOrder":{"type":"boolean","description":"Whether it keeps selling with none in stock."},"pictures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":["string","null"]}},"required":["id","url"]},"description":"Its first three pictures, the cover first, sized for a small tile."}},"required":["id","title","status","description","productType","variants","price","madeToOrder","pictures"]},"Location":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"name":{"type":"string"},"isDefault":{"type":"boolean","description":"Orders take their stock from the default location. A shop has one."},"address":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"company":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string","description":"Two letters, such as `GB`."},"postal_code":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}},"required":["name","line_one","city","country","postal_code"]},{"type":"null"}],"description":"Where a carrier collects from. Null until somebody gives one."},"addressValidatedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When a carrier last agreed the address exists. Null is unchecked."},"kind":{"type":"string","enum":["own","supplier"],"description":"`supplier` stock is refreshed from the supplier and cannot be changed here."},"supplierConnectionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The supplier that stocks it. Null for the shop’s own."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","name","isDefault","address","addressValidatedAt","kind","supplierConnectionId","createdAt","updatedAt"]},"MetafieldDefinition":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"pluginId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The app whose manifest declares it. Null for the shop’s own field."},"ownerType":{"type":"string","enum":["product","variant","collection","customer","order","store"],"description":"The kind of record it hangs on."},"namespace":{"type":"string","description":"`custom` unless said. Namespaces starting `app_` belong to apps."},"key":{"type":"string"},"name":{"type":"string","description":"The merchant’s label for it."},"description":{"type":["string","null"]},"type":{"type":"string","enum":["single_line_text","multi_line_text","integer","decimal","boolean","date","url"]},"isList":{"type":"boolean","description":"Holds a list of values rather than one."},"validations":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"minLength":{"type":"integer"},"maxLength":{"type":"integer"},"choices":{"description":"The only values it may hold.","type":"array","items":{"type":"string"}},"scale":{"description":"Digits after the point, for `decimal`.","type":"integer"}},"description":"The rules every value is checked against."},"storefrontVisible":{"type":"boolean","description":"Shoppers may see it. Never true on a customer or an order."},"searchFacet":{"type":"boolean","description":"Shoppers can narrow search by it."},"position":{"type":"number","description":"Where it sits among the fields for its kind of record, lowest first."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","pluginId","ownerType","namespace","key","name","description","type","isList","validations","storefrontVisible","searchFacet","position","createdAt","updatedAt"]},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"sessionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"customerId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"buyerProven":{"type":"boolean","description":"Whether the basket named a known customer when the order was placed. False for an order filed under an email address someone typed."},"orderNumber":{"type":"string","description":"The number the shop and the buyer know it by, without the `#`."},"customerNote":{"description":"What the shopper wrote at checkout.","type":["string","null"]},"status":{"type":"string","enum":["created","confirmed","manual_review","processing","shipped","delivered","canceled"]},"currency":{"type":"string"},"locale":{"description":"The language the shopper was reading the shop in. Null when the shop never knew.","type":["string","null"]},"buyerEmail":{"type":"string"},"buyerFirstName":{"type":["string","null"]},"buyerLastName":{"type":["string","null"]},"buyerPhone":{"type":["string","null"]},"shippingAddress":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"}},"required":["line_one","city","country","postal_code"]},{"type":"null"}]},"billingAddress":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"line_one":{"type":"string"},"line_two":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"postal_code":{"type":"string"}},"required":["line_one","city","country","postal_code"]},{"type":"null"}]},"fulfillmentOption":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["shipping","digital","pickup","local_delivery"]},"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"carrier":{"type":"string"},"earliest_delivery_time":{"type":"string"},"latest_delivery_time":{"type":"string"},"amount":{"type":"integer","description":"Minor units."}},"required":["type","id","title","amount"]},{"type":"null"}],"description":"The delivery the shopper chose, by name. Null on older orders."},"subtotalAmount":{"type":"number","description":"The goods, before discounts, in minor units of `currency` (1999 is 19.99). Every amount on an order is in minor units."},"discountAmount":{"type":"number","description":"Everything discounts took off, including any taken off delivery."},"fulfillmentAmount":{"type":"number","description":"Delivery, after any discount on it."},"taxAmount":{"type":"number","description":"Tax, including any on delivery."},"fulfillmentTaxAmount":{"type":"number","description":"The part of `taxAmount` charged on delivery."},"fulfillmentDiscountAmount":{"type":"number","description":"The part of `discountAmount` that came off delivery."},"companyId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The trade account it was placed against, if any."},"priceListId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"paymentTermsNetDays":{"description":"Days to pay, for an order placed on account. Null when paid at checkout.","type":["number","null"]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When an order on account falls due."},"purchaseOrderNumber":{"type":["string","null"]},"totalAmount":{"type":"number","description":"What the order came to at checkout. Refunds and edits never change it; they are counted in `refundedAmount` and `changeAmount`."},"refundedAmount":{"type":"number","description":"Refunded so far."},"changeAmount":{"type":"number","description":"The net of every confirmed change, signed: positive means the customer owes more."},"creditAppliedAmount":{"type":"number","description":"The part of the total paid with store credit."},"taxCalculationId":{"type":["string","null"]},"taxTransactionId":{"type":["string","null"]},"discountId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"discountCode":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"},"description":"Labels the shop put on the order. Staff only, never shown to a shopper."},"heldAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When the shop kept this order back from being sent. Null when it may go."},"heldBy":{"description":"Who kept it back.","type":["string","null"]},"holdReason":{"description":"Why it was kept back. Staff only, never shown to a shopper.","type":["string","null"]},"origin":{"type":"string","enum":["storefront","agent","admin","plugin","imported","subscription"],"description":"Which door placed it."},"agentId":{"description":"The AI agent that placed it, when one did.","type":["string","null"]},"conversationId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"referralId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"adLinkId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"placedAt":{"type":"string","format":"date-time"},"canceledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"subscriptionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The subscription that produced it. Null for a one time purchase."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","sessionId","customerId","buyerProven","orderNumber","customerNote","status","currency","locale","buyerEmail","buyerFirstName","buyerLastName","buyerPhone","shippingAddress","billingAddress","fulfillmentOption","subtotalAmount","discountAmount","fulfillmentAmount","taxAmount","fulfillmentTaxAmount","fulfillmentDiscountAmount","companyId","priceListId","paymentTermsNetDays","dueAt","purchaseOrderNumber","totalAmount","refundedAmount","changeAmount","creditAppliedAmount","taxCalculationId","taxTransactionId","discountId","discountCode","tags","heldAt","heldBy","holdReason","origin","agentId","conversationId","referralId","adLinkId","placedAt","canceledAt","subscriptionId","createdAt","updatedAt"]},"OrderAdjustment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["refund","partial_refund","store_credit","return","exchange","cancellation","dispute","chargeback"]},"status":{"type":"string","enum":["pending","completed","failed"],"description":"A refund is `pending` while the money moves, then `completed` or `failed`."},"amount":{"type":"number","description":"In minor units of the order’s currency."},"currency":{"type":["string","null"]},"reason":{"type":["string","null"]},"description":{"type":["string","null"]},"providerRefundId":{"description":"The payment provider’s id for the refund, when one was sent.","type":["string","null"]},"evidenceDueBy":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"On a dispute: when the answer is due."},"feeAmount":{"description":"On a dispute: what it cost, in minor units of `feeCurrency`. Null until the payment provider states it.","type":["number","null"]},"feeCurrency":{"description":"On a dispute: the currency of `feeAmount`.","type":["string","null"]},"taxReversalId":{"type":["string","null"]},"actorType":{"anyOf":[{"type":"string","enum":["staff","customer","plugin","agent","system"]},{"type":"null"}],"description":"Who issued it. Null for a refund the payment provider reported."},"actorId":{"type":["string","null"]},"occurredAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","orderId","storeId","type","status","amount","currency","reason","description","providerRefundId","evidenceDueBy","feeAmount","feeCurrency","taxReversalId","actorType","actorId","occurredAt","createdAt","updatedAt"]},"OrderChange":{"type":"object","properties":{"change":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["edit","return","exchange","claim"]},"status":{"type":"string","enum":["pending","confirmed","declined","canceled"]},"reason":{"type":["string","null"]},"note":{"type":["string","null"]},"deltaSubtotalAmount":{"type":"number"},"deltaDiscountAmount":{"type":"number"},"deltaFulfillmentAmount":{"type":"number"},"deltaTaxAmount":{"type":"number"},"deltaTotalAmount":{"type":"number","description":"What the change came to, signed and in minor units: positive means the customer owes more. Zero until it is confirmed, as are the other deltas."},"currency":{"type":"string"},"adjustmentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The refund it made, when it gave money back."},"paymentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"actorType":{"anyOf":[{"type":"string","enum":["staff","customer","plugin","agent","system"]},{"type":"null"}]},"actorId":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"confirmedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","storeId","orderId","kind","status","reason","note","deltaSubtotalAmount","deltaDiscountAmount","deltaFulfillmentAmount","deltaTaxAmount","deltaTotalAmount","currency","adjustmentId","paymentId","actorType","actorId","createdAt","updatedAt","confirmedAt","declinedAt","canceledAt"]},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"changeId":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["item_add","item_quantity","item_remove","shipping_add","shipping_remove"]},"lineItemId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"variantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"quantityDelta":{"type":"number","description":"Signed. Negative takes units off the line."},"unitAmount":{"type":"number","description":"Minor units."},"amount":{"type":"number","description":"Minor units."},"details":{},"createdAt":{"type":"string","format":"date-time"}},"required":["id","storeId","changeId","action","lineItemId","variantId","quantityDelta","unitAmount","amount","details","createdAt"]}}},"required":["change","actions"]},"OrderLineItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"variantId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"productId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"title":{"type":"string","description":"The product’s title when it was bought."},"variantTitle":{"description":"The variant’s title when it was bought.","type":["string","null"]},"productHandle":{"type":["string","null"]},"sku":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"quantityOrdered":{"type":"number"},"quantityShipped":{"type":"number","description":"Units sent."},"quantityRefunded":{"type":"number","description":"Units whose money went back."},"quantityReturned":{"type":"number","description":"Units that came back, whatever the shopper got for them."},"unitAmount":{"type":"number","description":"One unit, in minor units of the order’s currency."},"subtotalAmount":{"type":"number","description":"Every unit on the line, before its discount and tax."},"priceListId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"listUnitAmount":{"description":"What one unit costs at the shop’s own price, when a price list priced this line. Null otherwise.","type":["number","null"]},"discountAmount":{"type":"number","description":"The line’s share of the discounts."},"taxAmount":{"type":"number","description":"The line’s tax."},"sellingPlanId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","orderId","storeId","variantId","productId","title","variantTitle","productHandle","sku","imageUrl","quantityOrdered","quantityShipped","quantityRefunded","quantityReturned","unitAmount","subtotalAmount","priceListId","listUnitAmount","discountAmount","taxAmount","sellingPlanId","createdAt","updatedAt"]},"OrderNote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"body":{"type":"string"},"actorType":{"type":"string","enum":["staff","system","agent","plugin"],"description":"Who wrote it."},"actorId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","orderId","storeId","body","actorType","actorId","createdAt"]},"PayoutSummary":{"type":"object","properties":{"connected":{"type":"boolean","description":"False for a shop with no payment account yet."},"live":{"type":"boolean","description":"False when the balance and the list could not be read just now. They are then empty, and `failure` is still current."},"balance":{"type":"object","properties":{"available":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"integer","description":"In the currency’s minor unit: cents, pence, paise."},"currency":{"type":"string","description":"Lower case, such as `gbp`."}},"required":["amount","currency"]},"description":"Ready to be sent, per currency."},"pending":{"type":"array","items":{"type":"object","properties":{"amount":{"type":"integer","description":"In the currency’s minor unit: cents, pence, paise."},"currency":{"type":"string","description":"Lower case, such as `gbp`."}},"required":["amount","currency"]},"description":"Still clearing, per currency."}},"required":["available","pending"]},"payouts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"integer","description":"In the currency’s minor unit."},"currency":{"type":"string"},"arrivalDate":{"type":"string","format":"date-time","description":"When the bank should have it, or did."},"status":{"type":"string","description":"`paid`, `pending`, `in_transit`, `canceled` or `failed`."},"failureCode":{"description":"Why it failed, as a code such as `account_closed`, when it did.","type":["string","null"]}},"required":["id","amount","currency","arrivalDate","status","failureCode"]},"description":"The latest ten, newest first."},"nextArrival":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"The earliest arrival among those on their way, or null when none is."},"failure":{"anyOf":[{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"code":{"type":["string","null"]}},"required":["at","code"]},{"type":"null"}],"description":"The last failure on record, while no later payout has arrived."}},"required":["connected","live","balance","payouts","nextArrival","failure"]},"PriceChange":{"type":"object","properties":{"id":{"type":"number","description":"Pass as `historyId` to put back the price from before this change."},"storeId":{"type":"string","format":"uuid"},"variantId":{"type":"string","format":"uuid"},"currency":{"type":"string"},"amount":{"type":"number","description":"The new price, in minor units."},"previousAmount":{"description":"The price before. Null for the variant’s first price.","type":["number","null"]},"compareAtAmount":{"type":["number","null"]},"previousCompareAtAmount":{"type":["number","null"]},"actorType":{"type":"string","enum":["staff","customer","plugin","agent","system"]},"actorId":{"type":["string","null"]},"reason":{"anyOf":[{"type":"string","enum":["merchant","import","bulk","proposal","revert"]},{"type":"null"}],"description":"Why it moved, where known, such as `revert` for a change put back."},"proposalId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}},"required":["id","storeId","variantId","currency","amount","previousAmount","compareAtAmount","previousCompareAtAmount","actorType","actorId","reason","proposalId","createdAt"]},"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"title":{"type":"string"},"handle":{"type":"string","description":"The product’s address on the shop front: `/products/{handle}`."},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","archived"],"description":"Only an `active` product is on sale."},"productType":{"type":["string","null"]},"vendor":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"seoTitle":{"type":["string","null"]},"seoDescription":{"type":["string","null"]},"isGiftCard":{"type":"boolean","description":"Buying it buys a gift card worth the variant’s price."},"pinnedCopy":{"type":"array","items":{"type":"string"},"description":"Fields whose wording is the merchant’s own, which automatic copy leaves alone."},"publishedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it first went on sale. Putting it on sale again does not move it."},"enrichmentStatus":{"type":"string","enum":["none","queued","ready","failed"]},"indexedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"indexedEnrichmentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"indexedBackends":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was archived. Lists leave archived products out unless asked."}},"required":["id","storeId","title","handle","description","status","productType","vendor","tags","seoTitle","seoDescription","isGiftCard","pinnedCopy","publishedAt","enrichmentStatus","indexedAt","indexedEnrichmentId","indexedBackends","createdAt","updatedAt","archivedAt"]},"ProductDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"title":{"type":"string"},"handle":{"type":"string","description":"The product’s address on the shop front: `/products/{handle}`."},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","archived"],"description":"Only an `active` product is on sale."},"productType":{"type":["string","null"]},"vendor":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"seoTitle":{"type":["string","null"]},"seoDescription":{"type":["string","null"]},"isGiftCard":{"type":"boolean","description":"Buying it buys a gift card worth the variant’s price."},"pinnedCopy":{"type":"array","items":{"type":"string"},"description":"Fields whose wording is the merchant’s own, which automatic copy leaves alone."},"publishedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it first went on sale. Putting it on sale again does not move it."},"enrichmentStatus":{"type":"string","enum":["none","queued","ready","failed"]},"indexedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"indexedEnrichmentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"indexedBackends":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was archived. Lists leave archived products out unless asked."},"options":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"position":{"type":"integer"},"values":{"type":"array","items":{"type":"string"},"description":"Its values, in order."},"valueRows":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"value":{"type":"string"},"position":{"type":"integer"}},"required":["id","value","position"]},"description":"The same values with their ids, for renaming or removing one."}},"required":["id","name","position","values","valueRows"]}},"variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","description":"Its option values joined, such as `S / Navy`, unless set by hand."},"sku":{"type":["string","null"]},"barcode":{"type":["string","null"]},"weightGrams":{"anyOf":[{"type":"integer"},{"type":"null"}]},"hsCode":{"description":"The tariff code customs is told abroad.","type":["string","null"]},"countryOfOrigin":{"description":"Two letters, such as `US`.","type":["string","null"]},"requiresShipping":{"type":"boolean"},"isDigital":{"type":"boolean"},"position":{"type":"integer"},"continueSelling":{"type":"boolean","description":"Whether it keeps selling once its stock is zero."},"taxClassId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The shop’s own tax rate it is sold at. Null is the standard one."},"shippingClassId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The delivery group it belongs to, which decides the rates it can go by."},"cost":{"anyOf":[{"type":"object","properties":{"amount":{"type":"integer","description":"In the currency’s minor units, such as pence."},"currency":{"type":"string","description":"An ISO 4217 code, such as `GBP`."}},"required":["amount","currency"]},{"type":"null"}],"description":"What one cost to buy. Null means unknown, not free."},"prices":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"integer"},"compareAtAmount":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The higher price shown struck through beside it."}},"required":["currency","amount","compareAtAmount"]}}},"required":["id","title","sku","barcode","weightGrams","hsCode","countryOfOrigin","requiresShipping","isDigital","position","continueSelling","taxClassId","shippingClassId","cost","prices"]}}},"required":["id","storeId","title","handle","description","status","productType","vendor","tags","seoTitle","seoDescription","isGiftCard","pinnedCopy","publishedAt","enrichmentStatus","indexedAt","indexedEnrichmentId","indexedBackends","createdAt","updatedAt","archivedAt","options","variants"]},"ProductFigures":{"type":"object","properties":{"notLive":{"type":"integer","description":"Drafts, not yet on sale."},"outOfStock":{"type":"integer","description":"Products nobody can buy: every version keeps a count and none is left. `filter=out_of_stock` lists them."},"neverRead":{"type":"integer","description":"Products the shop has never read. `filter=never_read` lists them."},"sold30Days":{"anyOf":[{"type":"object","properties":{"products":{"type":"integer","description":"How many products were on an order."},"units":{"type":"integer","description":"How many of them were ordered."}},"required":["products","units"]},{"type":"null"}],"description":"The last thirty days. Null without `analytics:read`. `filter=sold_30d` lists them."}},"required":["notLive","outOfStock","neverRead","sold30Days"]},"ProductMedia":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"storagePath":{"type":["string","null"]},"sourceUrl":{"type":["string","null"]},"storageProvider":{"type":"string","enum":["supabase","r2"]},"mimeType":{"type":"string"},"sizeBytes":{"type":["number","null"]},"width":{"type":["number","null"]},"height":{"type":["number","null"]},"alt":{"type":["string","null"]},"mirrorClaimedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"mirrorAttempts":{"type":"number"},"mirrorFailedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"url":{"type":"string","description":"Where the image is served."},"position":{"type":"integer","description":"Its place in the order, from 0."}},"required":["id","storeId","storagePath","sourceUrl","storageProvider","mimeType","sizeBytes","width","height","alt","mirrorClaimedAt","mirrorAttempts","mirrorFailedAt","createdAt","url","position"]},"ProductRow":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"title":{"type":"string"},"handle":{"type":"string","description":"The product’s address on the shop front: `/products/{handle}`."},"description":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","archived"],"description":"Only an `active` product is on sale."},"productType":{"type":["string","null"]},"vendor":{"type":["string","null"]},"tags":{"type":"array","items":{"type":"string"}},"seoTitle":{"type":["string","null"]},"seoDescription":{"type":["string","null"]},"isGiftCard":{"type":"boolean","description":"Buying it buys a gift card worth the variant’s price."},"pinnedCopy":{"type":"array","items":{"type":"string"},"description":"Fields whose wording is the merchant’s own, which automatic copy leaves alone."},"publishedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it first went on sale. Putting it on sale again does not move it."},"enrichmentStatus":{"type":"string","enum":["none","queued","ready","failed"]},"indexedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"indexedEnrichmentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"indexedBackends":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"When it was archived. Lists leave archived products out unless asked."},"thumbnail":{"description":"Its first picture, sized for a row. Null when it has none.","type":["string","null"]},"price":{"anyOf":[{"type":"object","properties":{"min":{"type":"integer","description":"The cheapest version, in the currency’s minor units."},"max":{"type":"integer","description":"The dearest version, in the same units."},"currency":{"type":"string","description":"The shop’s own currency."}},"required":["min","max","currency"]},{"type":"null"}],"description":"Null when no version has a price in the shop’s currency."},"stock":{"type":"object","properties":{"available":{"type":"integer","description":"What is left to sell, over every location and every version that counts."},"tracked":{"type":"boolean","description":"False when no version keeps a count: each sells on with none left, or is a download."},"sellsOn":{"type":"boolean","description":"True when at least one version sells on with none left, or is a download, so the product can still be bought at nought."}},"required":["available","tracked","sellsOn"],"description":"What is left of it."}},"required":["id","storeId","title","handle","description","status","productType","vendor","tags","seoTitle","seoDescription","isGiftCard","pinnedCopy","publishedAt","enrichmentStatus","indexedAt","indexedEnrichmentId","indexedBackends","createdAt","updatedAt","archivedAt","thumbnail","price","stock"]},"ProductSales":{"type":"object","properties":{"units":{"type":"array","items":{"type":"integer"},"description":"30 entries, one per day, oldest first."},"revenue":{"type":"integer","description":"What those units were sold for in the shop’s own currency, in minor units. Sales taken in another currency count as units and are left out of this figure."},"currency":{"description":"The shop’s currency, or null when nothing sold in it.","type":["string","null"]}},"required":["units","revenue","currency"]},"Return":{"type":"object","properties":{"request":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"customerId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"returnNumber":{"type":"string"},"status":{"type":"string","enum":["requested","approved","declined","in_transit","partially_received","received","resolved","canceled"]},"reasonId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"reasonNote":{"type":["string","null"]},"resolution":{"anyOf":[{"type":"string","enum":["refund","store_credit","exchange"]},{"type":"null"}]},"locationId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"carrier":{"type":["string","null"]},"trackingNumber":{"type":["string","null"]},"trackingUrl":{"type":["string","null"]},"labelUrl":{"type":["string","null"]},"adjustmentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"orderChangeId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"creditEntryId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"exchangeSessionId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"exchangeOrderId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"estimatedRefundAmount":{"type":"number","description":"Minor units, as every amount on a return is."},"restockingFeeAmount":{"type":"number"},"shippingRefundAmount":{"type":"number"},"currency":{"type":"string"},"origin":{"type":"string","enum":["storefront","agent","admin","plugin","imported"]},"agentId":{"type":["string","null"]},"requestedAt":{"type":"string","format":"date-time"},"approvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"inTransitAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"receivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"canceledAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"windowOverriddenAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"merchantNote":{"type":["string","null"]},"declineReason":{"type":["string","null"]},"decidedVia":{"anyOf":[{"type":"string","enum":["policy","mandate"]},{"type":"null"}]},"mandateHeldBecause":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","orderId","customerId","returnNumber","status","reasonId","reasonNote","resolution","locationId","carrier","trackingNumber","trackingUrl","labelUrl","adjustmentId","orderChangeId","creditEntryId","exchangeSessionId","exchangeOrderId","estimatedRefundAmount","restockingFeeAmount","shippingRefundAmount","currency","origin","agentId","requestedAt","approvedAt","declinedAt","inTransitAt","receivedAt","resolvedAt","canceledAt","windowOverriddenAt","merchantNote","declineReason","decidedVia","mandateHeldBecause","createdAt","updatedAt"]},"lines":{"type":"array","items":{"type":"object","properties":{"returnId":{"type":"string","format":"uuid"},"lineItemId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"quantityRequested":{"type":"number"},"quantityApproved":{"type":"number"},"quantityReceived":{"type":"number"},"quantityRestocked":{"type":"number"},"quantityClaimed":{"type":"number"},"reasonId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"reasonNote":{"type":["string","null"]},"disposition":{"anyOf":[{"type":"string","enum":["restock","damaged","discard","quarantine","return_to_vendor"]},{"type":"null"}]},"inspectedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"refundAmount":{"type":"number"},"taxRefundAmount":{"type":"number"},"restockingFeeAmount":{"type":"number"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"title":{"type":"string"},"variantTitle":{"type":["string","null"]},"sku":{"type":["string","null"]},"imageUrl":{"type":["string","null"]}},"required":["returnId","lineItemId","storeId","quantityRequested","quantityApproved","quantityReceived","quantityRestocked","quantityClaimed","reasonId","reasonNote","disposition","inspectedAt","refundAmount","taxRefundAmount","restockingFeeAmount","createdAt","updatedAt","title","variantTitle","sku","imageUrl"]}},"reason":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"code":{"type":"string","enum":["wrong_size","wrong_item_sent","damaged_in_transit","defective","not_as_described","looks_different_to_photo","quality_below_expectation","arrived_late","changed_mind","other"]},"label":{"type":"string"},"refundsShipping":{"type":"boolean"},"waivesRestockingFee":{"type":"boolean"},"requiresReturn":{"type":"boolean"},"defaultDisposition":{"type":"string","enum":["restock","damaged","discard","quarantine","return_to_vendor"]},"position":{"type":"number"},"shopAdded":{"type":"boolean"},"archivedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","code","label","refundsShipping","waivesRestockingFee","requiresReturn","defaultDisposition","position","shopAdded","archivedAt","createdAt","updatedAt"]},{"type":"null"}]}},"required":["request","lines","reason"]},"ShippingClass":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string","description":"Stable across renames. What a later import matches on."},"description":{"description":"A note for the merchant. Shoppers do not see it.","type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","name","slug","description","createdAt","updatedAt"]},"ShippingClassRow":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string","description":"Stable across renames. What a later import matches on."},"description":{"description":"A note for the merchant. Shoppers do not see it.","type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"variantCount":{"type":"integer","description":"How many variants are in it."},"rateCount":{"type":"integer","description":"How many delivery rates name it."}},"required":["id","storeId","name","slug","description","createdAt","updatedAt","variantCount","rateCount"]},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"orderId":{"type":"string","format":"uuid"},"fulfillmentId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The despatch it is for."},"returnId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The return it brings back."},"direction":{"type":"string","enum":["outbound","return"]},"status":{"type":"string","enum":["reserved","action_required","authorized","purchasing","purchased","void_pending","voided","failed","canceled"]},"livemode":{"type":"boolean"},"payOnUse":{"type":"boolean","description":"A return label charged only if a carrier scans it."},"carrier":{"type":"string"},"carrierName":{"type":"string"},"serviceToken":{"type":"string"},"serviceName":{"type":"string"},"estimatedDays":{"anyOf":[{"type":"integer"},{"type":"null"}]},"trackingNumber":{"type":["string","null"]},"trackingUrl":{"type":["string","null"]},"trackingStatus":{"type":["string","null"]},"labelUrl":{"description":"The label to print, once it is bought.","type":["string","null"]},"commercialInvoiceUrl":{"type":["string","null"]},"amount":{"type":"integer","description":"The carrier’s price, in minor units."},"currency":{"type":"string"},"charge":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["pending","action_required","authorized","captured","canceled","failed","owed"]},"postage":{"type":"integer"},"fee":{"type":"integer"},"total":{"type":"integer"},"refunded":{"type":"integer"}},"required":["status","postage","fee","total","refunded"]},{"type":"null"}],"description":"What the card was charged, in minor units."},"parcel":{"type":"object","properties":{"packageId":{"type":"string","format":"uuid"},"packageName":{"type":"string"},"lengthMm":{"type":"integer"},"widthMm":{"type":"integer"},"heightMm":{"type":"integer"},"weightGrams":{"type":"integer"}},"required":["lengthMm","widthMm","heightMm","weightGrams"]},"lines":{"type":"array","items":{"type":"object","properties":{"lineItemId":{"type":"string","format":"uuid"},"quantity":{"type":"integer"}},"required":["lineItemId","quantity"]}},"failure":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"purchasedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"voidedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"clientSecret":{"description":"Present only while the bank wants the cardholder to confirm the charge.","type":"string"}},"required":["id","orderId","fulfillmentId","returnId","direction","status","livemode","payOnUse","carrier","carrierName","serviceToken","serviceName","estimatedDays","trackingNumber","trackingUrl","trackingStatus","labelUrl","commercialInvoiceUrl","amount","currency","charge","parcel","lines","failure","createdAt","purchasedAt","voidedAt"]},"Variant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"productId":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"title":{"type":"string","description":"Its option values joined, such as `S / Navy`, unless set by hand."},"sku":{"type":["string","null"]},"barcode":{"type":["string","null"]},"position":{"type":"number"},"weightGrams":{"type":["number","null"]},"lengthMm":{"type":["number","null"]},"widthMm":{"type":["number","null"]},"heightMm":{"type":["number","null"]},"hsCode":{"description":"The tariff code customs is told when it is posted abroad.","type":["string","null"]},"countryOfOrigin":{"description":"Two letters, such as `US`.","type":["string","null"]},"shippingClassId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The delivery group it belongs to, which decides the rates it can go by."},"lowStockThreshold":{"type":["number","null"]},"taxClassId":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"The shop’s own tax rate it is sold at. Null is the standard one."},"orderMinimum":{"type":["number","null"]},"orderMaximum":{"type":["number","null"]},"orderIncrement":{"type":["number","null"]},"costAmount":{"description":"What one cost to buy, in minor units of `costCurrency`. Null means unknown.","type":["number","null"]},"costCurrency":{"type":["string","null"]},"requiresShipping":{"type":"boolean"},"isDigital":{"type":"boolean"},"continueSelling":{"type":"boolean","description":"Whether it keeps selling once its stock is zero."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","productId","storeId","title","sku","barcode","position","weightGrams","lengthMm","widthMm","heightMm","hsCode","countryOfOrigin","shippingClassId","lowStockThreshold","taxClassId","orderMinimum","orderMaximum","orderIncrement","costAmount","costCurrency","requiresShipping","isDigital","continueSelling","createdAt","updatedAt"]},"VariantExtras":{"type":"object","properties":{"variantId":{"type":"string","format":"uuid"},"levels":{"type":"array","items":{"$ref":"#/components/schemas/InventoryLevel"},"description":"Its stock at every location holding it."},"assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"},"description":"The files it delivers, oldest first."},"images":{"type":"array","items":{"$ref":"#/components/schemas/ProductMedia"},"description":"Its own pictures, in order."},"metafields":{"type":"array","items":{"type":"object","properties":{"definitionId":{"type":"string","format":"uuid"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string","description":"The merchant’s name for the field."},"type":{"type":"string","description":"single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types."},"isList":{"type":"boolean"},"storefrontVisible":{"type":"boolean"},"searchFacet":{"type":"boolean"},"position":{"type":"integer"},"value":{"description":"The value, or a list of values when `isList`."},"displayValue":{"type":"string","description":"The value as one line of text, lists joined."},"source":{"type":"string","description":"Who set it: the merchant, an import, or an app’s slug."}},"required":["definitionId","namespace","key","label","type","isList","storefrontVisible","searchFacet","position","value","displayValue","source"]}}},"required":["variantId","levels","assets","images","metafields"]}}}}