Collections

List collections

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

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.

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`search`	query	string	Words in the title or handle.
`kind`	query	string	One of `manual`, `automatic`.
`sort`	query	string	By title unless `updated_desc`, most recently changed first. Any other value is ignored. One of `title_asc`, `updated_desc`.
`limit`	query	integer	How many to return. Fifty when not given. From 1 to 200.
`offset`	query	integer	How many to skip, for the next page. At least 0.

Answers 200

Field	Type	Description
`data`	array of Collection
`meta`	object	Only on a page.
`meta.total`	integer
`meta.counts`	map of integer	Products in each collection on this page, by id.

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

Create a collection

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

Needs products:write.

Parameters

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

Body

Field	Type	Required	Description
`title`	string	Yes	1 to 300 characters.
`handle`	string	No	Up to 128 characters. Matches `^[a-z0-9][a-z0-9-]*$`.
`description`	string	No	Up to 50,000 characters.
`parentId`	string (uuid)	No
`seoTitle`	string	No	Up to 300 characters.
`seoDescription`	string	No	Up to 1,000 characters.
`kind`	string	No	One of `manual`, `automatic`. Default `manual`.
`rules`	array of object	No	Up to 10 items. Default `[]`.
`rules[].field`	string	Yes	One of `title`, `product_type`, `vendor`, `tag`, `price`.
`rules[].operator`	string	Yes	One of `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`.
`rules[].value`	string	Yes	1 to 200 characters.
`rules[].currency`	string	No	Matches `^[A-Z]{3}$`.
`sortOrder`	string	No	One of `manual`, `title_asc`, `title_desc`, `created_desc`, `price_asc`, `price_desc`. Default `manual`.
`filterable`	boolean	No

Answers 201

Field	Type	Description
`data`	Collection

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

Get a collection

GET /api/v1/stores/{storeId}/collections/{collectionId}

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`collectionId`	path	string	The collection.

Answers 200

Field	Type	Description
`data`	Collection

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

Update a collection

PATCH /api/v1/stores/{storeId}/collections/{collectionId}

Changes only the fields sent.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`collectionId`	path	string	The collection.

Body

Field	Type	Required	Description
`title`	string	No	1 to 300 characters.
`handle`	string	No	Up to 128 characters. Matches `^[a-z0-9][a-z0-9-]*$`.
`description`	string	No	Up to 50,000 characters.
`seoTitle`	string	No	Up to 300 characters.
`seoDescription`	string	No	Up to 1,000 characters.
`rules`	array of object	No	Up to 10 items.
`rules[].field`	string	Yes	One of `title`, `product_type`, `vendor`, `tag`, `price`.
`rules[].operator`	string	Yes	One of `equals`, `not_equals`, `contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`.
`rules[].value`	string	Yes	1 to 200 characters.
`rules[].currency`	string	No	Matches `^[A-Z]{3}$`.
`sortOrder`	string	No	One of `manual`, `title_asc`, `title_desc`, `created_desc`, `price_asc`, `price_desc`.
`filterable`	boolean	No

Answers 200

Field	Type	Description
`data`	Collection

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

Delete a collection

DELETE /api/v1/stores/{storeId}/collections/{collectionId}

Deletes the collection and says what it touched. Its products are kept, and its children move to the top level.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`collectionId`	path	string	The collection.

Answers 200

Field	Type	Description
`data`	object
`data.id`	string (uuid)
`data.title`	string
`data.handle`	string
`data.productsUnlinked`	integer	Products that were in it. The products are untouched.
`data.childrenPromoted`	integer	Child collections moved to the top level.
`data.menuItemsRemoved`	integer	Menu entries that pointed at it.
`data.discountTargetsRemoved`	integer	Discounts that named it, which now apply to less.

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

List a collection’s products

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

A page of the products in the collection, in its own order. Pass meta.next back as after for the next page.

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`collectionId`	path	string	The collection.
`search`	query	string	Words in a product’s title.
`ids`	query	string	Comma separated product ids: which of these are in it.
`limit`	query	integer	How many to return. Fifty when not given. From 1 to 200.
`after`	query	string	The `meta.next` of the page before.

Answers 200

Field	Type	Description
`data`	array of Product
`meta`	object
`meta.total`	integer	Members the search and ids match.
`meta.held`	integer	Every product in the collection.
`meta.next`	string or null	Pass back as `after`. Null on the last page.
`meta.truncated`	boolean	True when a price sort was cut short at its cap.

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

Add products to a collection

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

Adds products to a manual collection. Products already in it are left where they are.

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`collectionId`	path	string	The collection.

Body

Field	Type	Required	Description
`productIds`	array of string (uuid)	Yes	The products to add.

Answers 201

Field	Type	Description
`data`	object
`data.added`	integer

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

Remove a product from a collection

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

Needs products:write.

Parameters

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

Answers 200

Field	Type	Description
`data`	object
`data.removed`	`true`

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

List a collection’s metafields

GET /api/v1/stores/{storeId}/collections/{collectionId}/metafields

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

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`collectionId`	path	string	The collection.

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/collections/$COLLECTION_ID/metafields" \
  -H "Authorization: Bearer $TOKEN"

Set a collection’s metafields

PUT /api/v1/stores/{storeId}/collections/{collectionId}/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.
`collectionId`	path	string	The collection.

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/collections/$COLLECTION_ID/metafields" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json

List a collection’s translations

GET /api/v1/stores/{storeId}/collections/{collectionId}/translations

Every translated field, by locale.

Needs products:read.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`collectionId`	path	string	The collection.

Answers 200

Field	Type	Description
`data`	map of map of string	Locale, then field, then the translated text.

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

Set a collection’s translations

PUT /api/v1/stores/{storeId}/collections/{collectionId}/translations

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

Needs products:write.

Parameters

Parameter	In	Type	Description
`storeId`	path	string	The shop.
`collectionId`	path	string	The collection.

Body

Field	Type	Required	Description
`locale`	string	Yes	Matches `^[a-z]{2,3}(-[A-Z]{2})?$`.
`fields`	map of string or null	Yes

Answers 200

Field	Type	Description
`data`	map of string	The locale’s fields after the change.

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

List collectionsCopy Anchor Link

Create a collectionCopy Anchor Link

Get a collectionCopy Anchor Link

Update a collectionCopy Anchor Link

Delete a collectionCopy Anchor Link

List a collection’s productsCopy Anchor Link

Add products to a collectionCopy Anchor Link

Remove a product from a collectionCopy Anchor Link

List a collection’s metafieldsCopy Anchor Link

Set a collection’s metafieldsCopy Anchor Link

List a collection’s translationsCopy Anchor Link

Set a collection’s translationsCopy Anchor Link

On this page

List collections

Create a collection

Get a collection

Update a collection

Delete a collection

List a collection’s products

Add products to a collection

Remove a product from a collection

List a collection’s metafields

Set a collection’s metafields

List a collection’s translations

Set a collection’s translations