Products

List productsCopy Anchor Link

GET /api/v1/stores/{storeId}/products

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.

Needs products:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/products" \
  -H "Authorization: Bearer $TOKEN"

Create a productCopy Anchor Link

POST /api/v1/stores/{storeId}/products

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).

Needs products:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/products" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Count the catalogueCopy Anchor Link

GET /api/v1/stores/{storeId}/products/figures

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.

Needs products:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/figures" \
  -H "Authorization: Bearer $TOKEN"

Get a productCopy Anchor Link

GET /api/v1/stores/{storeId}/products/{productId}

The product with its options, its variants and each variant’s prices.

Needs products:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN"

Update a productCopy Anchor Link

PATCH /api/v1/stores/{storeId}/products/{productId}

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.

Needs products:write.

Parameters

Body

Answers 200

curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Archive a productCopy Anchor Link

DELETE /api/v1/stores/{storeId}/products/{productId}

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.

Needs products:write.

Parameters

Answers 204: Done, with nothing to send back.

curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $TOKEN"

Get a product’s sales by dayCopy Anchor Link

GET /api/v1/stores/{storeId}/products/{productId}/sales

Units of this product ordered on each of the last 30 days, oldest first and today last, counting orders that are still sales.

Needs products:read and analytics:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/sales" \
  -H "Authorization: Bearer $TOKEN"

Copy a productCopy Anchor Link

POST /api/v1/stores/{storeId}/products/{productId}/duplicate

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.

Needs products:write.

Parameters

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/duplicate" \
  -H "Authorization: Bearer $TOKEN"

List a product’s imagesCopy Anchor Link

GET /api/v1/stores/{storeId}/products/{productId}/media

The product’s gallery in order, each image with its address. The first is the cover.

Needs products:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/media" \
  -H "Authorization: Bearer $TOKEN"

Add an image to a productCopy Anchor Link

POST /api/v1/stores/{storeId}/products/{productId}/media

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.

Needs products:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/media" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Reorder a product’s imagesCopy Anchor Link

POST /api/v1/stores/{storeId}/products/{productId}/media/order

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.

Needs products:write.

Parameters

Body

Answers 204: Done, with nothing to send back.

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/media/order" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Add an option to a productCopy Anchor Link

POST /api/v1/stores/{storeId}/products/{productId}/options

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.

Needs products:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/options" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Rename an optionCopy Anchor Link

PATCH /api/v1/stores/{storeId}/options/{optionId}

Changes an option’s name. Variant titles are made of values alone, so none of them change. Answers with the whole product.

Needs products:write.

Parameters

Body

Answers 200

curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/options/$OPTION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Add a value to an optionCopy Anchor Link

POST /api/v1/stores/{storeId}/options/{optionId}

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.

Needs products:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/options/$OPTION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Rename an option valueCopy Anchor Link

PATCH /api/v1/stores/{storeId}/option-values/{optionValueId}

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.

Needs products:write.

Parameters

Body

Answers 200

curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/option-values/$OPTION_VALUE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Remove an option valueCopy Anchor Link

DELETE /api/v1/stores/{storeId}/option-values/{optionValueId}

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.

Needs products:write.

Parameters

Answers 200

curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/option-values/$OPTION_VALUE_ID" \
  -H "Authorization: Bearer $TOKEN"

Get several listingsCopy Anchor Link

GET /api/v1/stores/{storeId}/products/listings

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.

Needs products:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/listings" \
  -H "Authorization: Bearer $TOKEN"

Create a listingCopy Anchor Link

POST /api/v1/stores/{storeId}/products/listings

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).

Needs products:write.

Parameters

Body

Answers 201

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/listings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Change many prices at onceCopy Anchor Link

POST /api/v1/stores/{storeId}/products/prices

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).

Needs products:write.

Parameters

Body

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/prices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Price and publish several listingsCopy Anchor Link

POST /api/v1/stores/{storeId}/products/listings/settle

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.

Needs products:write.

Parameters

Body

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/listings/settle" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

Search as an AI shopperCopy Anchor Link

POST /api/v1/stores/{storeId}/search/as-ai-shopper

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.

Needs products:read.

Parameters

Body

Answers 200

curl -X POST "https://api.storeware.ai/api/v1/stores/$STORE_ID/search/as-ai-shopper" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List a product’s metafieldsCopy Anchor Link

GET /api/v1/stores/{storeId}/products/{productId}/metafields

Every metafield value set on a product, each with its definition.

Needs products:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/metafields" \
  -H "Authorization: Bearer $TOKEN"

Set a product’s metafieldsCopy Anchor Link

PUT /api/v1/stores/{storeId}/products/{productId}/metafields

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.

Needs products:write.

Parameters

Body

Answers 200

curl -X PUT "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/metafields" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List a product’s translationsCopy Anchor Link

GET /api/v1/stores/{storeId}/products/{productId}/translations

Every translated field, by locale.

Needs products:read.

Parameters

Answers 200

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/translations" \
  -H "Authorization: Bearer $TOKEN"

Set a product’s translationsCopy Anchor Link

PUT /api/v1/stores/{storeId}/products/{productId}/translations

Sets translated fields for one locale. Fields not named are left alone, and a null clears one.

Needs products:write.

Parameters

Body

Answers 200

curl -X PUT "https://api.storeware.ai/api/v1/stores/$STORE_ID/products/$PRODUCT_ID/translations" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json