Products

List catalog products, newest added first, with their variants, option axes, category ids, tags, attribute values, primary image and per-language translation overrides. Rows stay in the base language; use get_product for one product with its whole gallery and its recent orders.

One product with everything on it: variants and their option combinations, option axes, category ids, tags, the attribute value map, the full image gallery, translation overrides, plus its ten most recent completed orders and the total count of them. Use this before updating a product so you know which variant ids exist. On a store that sells in more than one currency each variant, each add-on price and the product itself also carry currency_amounts, the prices set in the other currencies as decimal strings; a currency with no entry is one the variant is not sold in. A grouped product or a kit also carries set_price: what one set of its children costs at their own prices (parts_minor), its bundle price when sell_as_set is on (price_minor) and the saving, in the store's own currency.

Create a product and at least one variant, and return the created product in the same form get_product does. A title is required; the slug is derived from it when omitted and a slug already in use answers 409. Send one variant under variant or several under variants; exactly one becomes the default, the one flagged is_default or else the first. Variant prices are decimal strings in the store currency, not minor units. Option axes and images are added against an existing product, so they are never part of a create. On a store that sells in more than one currency a variant, and the product (for pay what you want), may carry currency_amounts with the same prices in the other currencies.

Change one or more fields of a product and return the updated product. Only the keys sent are touched. category_ids, customer_group_ids, tags and translations replace their whole set when present and are left alone when absent. attributes is different: it is a merge keyed by attribute slug, so a key you do not send keeps its value and a key sent as null removes that one value. variants is a map keyed by variant id, and a variant can be promoted to default but never demoted, so move the flag by naming its replacement. sell_as_set turns a grouped product's own price into a bundle price for a full set of its children. On a store that sells in more than one currency, a variant in variants and each add-on price in option_prices may carry currency_amounts (see update_variant), and the product itself may carry currency_amounts for pay what you want and the deposit; the whole request is checked first, so one bad amount writes nothing.

Put the catalog in the order the ids are given, and answer with how many rows moved. The ids named take positions 0 to n in that order and everything else keeps its relative order behind them, so a page of a long catalog can be sent without disturbing the rest. Ids naming nothing are ignored. This is the order the storefront lists products in while the store's catalog.sort is manual, and nothing else reads it.

Delete a product, its variants, its option axes, its attribute values, its releases and file rows, and its images including the bytes on disk. Orders that bought it are untouched, because an order line keeps its own snapshot of what was sold.

Change one variant of a product and return it with the rest of the product's variants beside it. This is the route for a price change: send price_minor in minor units, the way every read of this API hands it back, or price as a decimal string. sku, position, stock_qty, stock_managed, backorders, backorder_note, is_digital, title, weight_grams, length_mm, width_mm, height_mm, compare_price, image_id, gtin, mpn, min_qty, max_qty and qty_step are all accepted, and only the keys sent are touched. bundle_of makes this variant a bundle of the listed variant ids, one of each, for the cart's bundle suggestion; an empty list stops it being a bundle, and fewer than two parts, the variant itself, a duplicate or an unknown id is refused with a 422. The three millimetre figures are the parcel's size; null is how you say a size has not been recorded, and a zero, a negative or a decimal is refused with a 422 naming the field. The three quantity keys are this variant's own limits; null on any of them inherits the product's. A key nobody declared is refused rather than dropped. is_default promotes this variant and never demotes another, so move the flag by naming its replacement. On a store that sells in more than one currency, currency_amounts sets the variant's prices there: a currency code to {price, compare_price} as decimal strings in that currency's own decimal places (yen take whole numbers). An empty string or null removes an amount, which means the variant cannot be bought in that currency, and a key left out is left alone. A currency the store does not sell in, the base currency, a negative amount or too many decimals is refused with a 422 and nothing is written, the base price included.

Find variants by product title, variant title or SKU, across every product whatever its status, for choosing the parts of a bundle. Each row carries a label ready to show, such as "Rentals — Rentals only".

Remove one variant of a product and return the variants that remain. Refused with 422 when it is the last variant, because a product with no variant has no price and nothing to sell; delete the product instead. Deleting the default variant promotes a sibling first. Existing orders keep their own snapshot of what was bought.