Variants

Read what every variant of a product holds

GET /api/v1/stores/{storeId}/products/{productId}/variant-extras

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.

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`productId`	path	string	The product.

Answers 200

Field	Type	Description
`data`	array of VariantExtras

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

Update a variant

PATCH /api/v1/stores/{storeId}/variants/{variantId}

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.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Body

Field	Type	Required	Description
`title`	string	No	1 to 300 characters.
`sku`	string or null	No	1 to 120 characters.
`barcode`	string or null	No	1 to 120 characters.
`lowStockThreshold`	integer or null	No	From 0 to 100,000.
`weightGrams`	integer or null	No	From 0 to 1,000,000.
`hsCode`	string or null	No	Matches `^\d{4}(\.?\d{2}){1,3}$`.
`countryOfOrigin`	string or null	No	Matches `^[A-Za-z]{2}$`.
`requiresShipping`	boolean	No
`isDigital`	boolean	No
`position`	integer	No	From 0 to 10,000.
`orderMinimum`	integer or null	No	From 1 to 10,000.
`orderMaximum`	integer or null	No	From 1 to 10,000.
`orderIncrement`	integer or null	No	From 1 to 10,000.
`taxClassId`	string (uuid) or null	No
`shippingClassId`	string (uuid) or null	No

Answers 200

Field	Type	Description
`data`	Variant

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

Set a variant’s price

POST /api/v1/stores/{storeId}/variants/{variantId}/price

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.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Body

Field	Type	Required	Description
`amount`	integer	Yes	At least 0.
`currency`	string	Yes	Matches `^[A-Z]{3}$`.
`compareAtAmount`	integer	No

Answers 204: Done, with nothing to send back.

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

List a variant’s price changes

GET /api/v1/stores/{storeId}/variants/{variantId}/price/history

Every price the variant has had, newest first, each with the one before it.

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.
`limit`	query	integer	How many to return, up to 200. Twenty when not given. From 1 to 200.
`currency`	query	string	Only changes in this currency, such as `GBP`.

Answers 200

Field	Type	Description
`data`	array of PriceChange

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/variants/$VARIANT_ID/price/history" \
  -H "Authorization: Bearer $TOKEN"

Put a price back

POST /api/v1/stores/{storeId}/variants/{variantId}/price/revert

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.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Body

Field	Type	Required	Description
`historyId`	integer	Yes	The `id` of the change to undo, from the history.

Answers 204: Done, with nothing to send back.

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

Set what a variant cost to buy

POST /api/v1/stores/{storeId}/variants/{variantId}/cost

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.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Body

Any JSON.

Answers 204: Done, with nothing to send back.

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

Set whether a variant sells with no stock

POST /api/v1/stores/{storeId}/variants/{variantId}/backorder

With allow true the variant keeps selling once its stock reaches zero; with false it stops there.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Body

Field	Type	Required	Description
`allow`	boolean	Yes

Answers 204: Done, with nothing to send back.

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

List a variant’s images

GET /api/v1/stores/{storeId}/variants/{variantId}/media

The images shown when a shopper picks this variant, in order. A variant with none shows the product’s gallery.

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Answers 200

Field	Type	Description
`data`	array of ProductMedia

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

Show an image for a variant

POST /api/v1/stores/{storeId}/variants/{variantId}/media

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.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Body

Field	Type	Required	Description
`mediaId`	string (uuid)	Yes	An image uploaded to the shop.

Answers 204: Done, with nothing to send back.

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

Take an image off a variant

DELETE /api/v1/stores/{storeId}/variants/{variantId}/media

Takes the image off the variant’s own images and leaves the image itself alone. The id goes in the query string.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.
`mediaId`	query	string (uuid)	Required. The image to take off.

Answers 204: Done, with nothing to send back.

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

List a variant’s downloads

GET /api/v1/stores/{storeId}/variants/{variantId}/digital-assets

The files a buyer of this variant may download, oldest first.

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Answers 200

Field	Type	Description
`data`	array of DigitalAsset

curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/variants/$VARIANT_ID/digital-assets" \
  -H "Authorization: Bearer $TOKEN"

Attach a download to a variant

POST /api/v1/stores/{storeId}/variants/{variantId}/digital-assets

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.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Body

Field	Type	Required	Description
`storagePath`	string	Yes	1 to 500 characters.
`fileName`	string	Yes	1 to 255 characters.
`sizeBytes`	integer	No	At most 524,288,000.
`downloadLimit`	integer	No	At most 1,000.

Answers 201

Field	Type	Description
`data`	DigitalAsset

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

List a variant’s metafields

GET /api/v1/stores/{storeId}/variants/{variantId}/metafields

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

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Answers 200

Field	Type	Description
`data`	array of object
`data[].definitionId`	string (uuid)
`data[].namespace`	string
`data[].key`	string
`data[].label`	string	The merchant’s name for the field.
`data[].type`	string	single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types.
`data[].isList`	boolean
`data[].storefrontVisible`	boolean
`data[].searchFacet`	boolean
`data[].position`	integer
`data[].value`	any	The value, or a list of values when `isList`.
`data[].displayValue`	string	The value as one line of text, lists joined.
`data[].source`	string	Who set it: the merchant, an import, or an app’s slug.

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

Set a variant’s metafields

PUT /api/v1/stores/{storeId}/variants/{variantId}/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

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`variantId`	path	string	The variant.

Body

Field	Type	Required	Description
`metafields`	array of object	Yes	Up to 25 items. At least 1 item.
`metafields[].namespace`	string	No	Default `custom`.
`metafields[].key`	string	Yes
`metafields[].value`	any	No

Answers 200

Field	Type	Description
`data`	array of object
`data[].definitionId`	string (uuid)
`data[].namespace`	string
`data[].key`	string
`data[].label`	string	The merchant’s name for the field.
`data[].type`	string	single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types.
`data[].isList`	boolean
`data[].storefrontVisible`	boolean
`data[].searchFacet`	boolean
`data[].position`	integer
`data[].value`	any	The value, or a list of values when `isList`.
`data[].displayValue`	string	The value as one line of text, lists joined.
`data[].source`	string	Who set it: the merchant, an import, or an app’s slug.

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

Read what every variant of a product holdsCopy Anchor Link

Update a variantCopy Anchor Link

Set a variant’s priceCopy Anchor Link

List a variant’s price changesCopy Anchor Link

Put a price backCopy Anchor Link

Set what a variant cost to buyCopy Anchor Link

Set whether a variant sells with no stockCopy Anchor Link

List a variant’s imagesCopy Anchor Link

Show an image for a variantCopy Anchor Link

Take an image off a variantCopy Anchor Link

List a variant’s downloadsCopy Anchor Link

Attach a download to a variantCopy Anchor Link

List a variant’s metafieldsCopy Anchor Link

Set a variant’s metafieldsCopy Anchor Link

On this page

Read what every variant of a product holds

Update a variant

Set a variant’s price

List a variant’s price changes

Put a price back

Set what a variant cost to buy

Set whether a variant sells with no stock

List a variant’s images

Show an image for a variant

Take an image off a variant

List a variant’s downloads

Attach a download to a variant

List a variant’s metafields

Set a variant’s metafields