Organization API: Catalog &amp; Services: Commerce

Name	In	Type	Required
`collection_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`product_ids`	array of integer	yes

Responses

Section titled Products, most recently changed first

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Products, most recently changed first

GET /api/v1/orgs/{org_slug}/commerce/products

Products, most recently changed first. q matches the title, the handle or a variant's SKU; collection_id follows a smart collection's rules; category_id is direct membership unless include_descendants. Send fields to get only the keys you need: the answer comes back sooner when it leaves out variants, images and the other lists.

Parameters

Name	In	Type	Required	Description
`org_slug`	path	string	yes
`q`	query	string or null	no
`status`	query	string or null	no
`collection_id`	query	integer or null	no
`category_id`	query	integer or null	no
`include_descendants`	query	boolean	no	Default: `False`.
`tag`	query	string or null	no
`sales_channel_id`	query	integer or null	no
`external_id`	query	string or null	no
`limit`	query	integer	no	Default: `50`.
`offset`	query	integer	no	Default: `0`.
`fields`	query	string or null	no	Comma-separated top-level keys to answer, such as `id,handle,title`. `id` is always included. Relations you leave out are not loaded, so the answer comes back sooner. Without it the object is whole. A product's keys are `id`, `title`, `subtitle`, `handle`, `description`, `status`, `thumbnail_url`, `is_giftcard`, `discountable`, `product_type`, `vendor`, `shipping_profile_id`, `weight_g`, `length_mm`, `width_mm`, `height_mm`, `hs_code`, `origin_country`, `mid_code`, `material`, `tax_code`, `seo_title`, `seo_description`, `external_id`, `metadata`, `options`, `variants`, `images`, `tags`, `collection_ids`, `category_ids`, `sales_channel_ids`, `published_at`, `created_at`, `updated_at`. A list that shows titles and stock asks for `title,variants`; leaving out `variants` also skips prices and stock. A key the product does not have answers 422 `invalid_fields`, with the keys allowed in `allowed`.

Responses

Section titled Create product

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Create product

POST /api/v1/orgs/{org_slug}/commerce/products

A product, with its options, variants, channels, collections, categories and tags when given. A draft unless status says otherwise; sold in the store's default channel unless sales_channel_ids says otherwise.

Parameters

Name	In	Type	Required
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`weight_g`	integer or null	no
`length_mm`	integer or null	no
`width_mm`	integer or null	no
`height_mm`	integer or null	no
`hs_code`	string or null	no
`origin_country`	string or null	no
`mid_code`	string or null	no
`material`	string or null	no
`tax_code`	string or null	no
`external_id`	string or null	no
`metadata`	object or null	no
`title`	string or null	no
`handle`	string or null	no
`subtitle`	string or null	no
`description`	string or null	no
`status`	string or null	no
`thumbnail_url`	string or null	no
`is_giftcard`	boolean or null	no
`discountable`	boolean or null	no
`product_type`	string or null	no
`vendor`	string or null	no
`shipping_profile_id`	integer or null	no
`seo_title`	string or null	no
`seo_description`	string or null	no
`options`	array of object or null	no
`variants`	array of object or null	no
`sales_channel_ids`	array of integer or null	no
`collection_ids`	array of integer or null	no
`category_ids`	array of integer or null	no
`tags`	array of any or null	no

Responses

Section titled Get product

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Get product

GET /api/v1/orgs/{org_slug}/commerce/products/{product_id}

One product with its options, its variants with their prices and stock, its images and tags, and the ids of its collections, categories and sales channels. Send fields to get only the keys you need, as on the list.

Parameters

Name	In	Type	Required	Description
`product_id`	path	integer	yes
`org_slug`	path	string	yes
`fields`	query	string or null	no	Comma-separated top-level keys to answer, such as `id,handle,title`. `id` is always included. Relations you leave out are not loaded, so the answer comes back sooner. Without it the object is whole. A product's keys are `id`, `title`, `subtitle`, `handle`, `description`, `status`, `thumbnail_url`, `is_giftcard`, `discountable`, `product_type`, `vendor`, `shipping_profile_id`, `weight_g`, `length_mm`, `width_mm`, `height_mm`, `hs_code`, `origin_country`, `mid_code`, `material`, `tax_code`, `seo_title`, `seo_description`, `external_id`, `metadata`, `options`, `variants`, `images`, `tags`, `collection_ids`, `category_ids`, `sales_channel_ids`, `published_at`, `created_at`, `updated_at`. A list that shows titles and stock asks for `title,variants`; leaving out `variants` also skips prices and stock. A key the product does not have answers 422 `invalid_fields`, with the keys allowed in `allowed`.

Responses

Section titled Fields change when named

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields change when named

PATCH /api/v1/orgs/{org_slug}/commerce/products/{product_id}

Fields change when named. options, variants, sales_channel_ids, collection_ids, category_ids and tags replace what the product had when given: a variant not in variants is deleted.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`weight_g`	integer or null	no
`length_mm`	integer or null	no
`width_mm`	integer or null	no
`height_mm`	integer or null	no
`hs_code`	string or null	no
`origin_country`	string or null	no
`mid_code`	string or null	no
`material`	string or null	no
`tax_code`	string or null	no
`external_id`	string or null	no
`metadata`	object or null	no
`title`	string or null	no
`handle`	string or null	no
`subtitle`	string or null	no
`description`	string or null	no
`status`	string or null	no
`thumbnail_url`	string or null	no
`is_giftcard`	boolean or null	no
`discountable`	boolean or null	no
`product_type`	string or null	no
`vendor`	string or null	no
`shipping_profile_id`	integer or null	no
`seo_title`	string or null	no
`seo_description`	string or null	no
`options`	array of object or null	no
`variants`	array of object or null	no
`sales_channel_ids`	array of integer or null	no
`collection_ids`	array of integer or null	no
`category_ids`	array of integer or null	no
`tags`	array of any or null	no

Responses

Section titled Archived and gone from every list and the Store API

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Archived and gone from every list and the Store API

DELETE /api/v1/orgs/{org_slug}/commerce/products/{product_id}

Archived and gone from every list and the Store API. Orders keep naming its variants; its handle and SKUs are free for new products.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled An https image, given by its url or by mediaid, an image in the store's media

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

An https image, given by its url or by mediaid, an image in the store's media

POST /api/v1/orgs/{org_slug}/commerce/products/{product_id}/images

An https image, given by its url or by media_id, an image in the store's media.

The first one becomes the thumbnail if there is none. With media_id the image takes the file's width, height and alt text unless the body gives them. A media_id that is not an image in the store's media answers 422, and so does a body with both url and media_id.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required	Description
`url`	string or null	no
`media_id`	string or null	no	An image in the store's media, such as media_01J9Z8Q4N6, in place of url. The image then links to the file's url, and takes its width, height and alt text unless the body gives them.
`alt`	string or null	no
`variant_id`	integer or null	no
`rank`	integer or null	no
`width`	integer or null	no
`height`	integer or null	no

Responses

Section titled Change an image: its url or mediaid, alt text, variant, rank or size

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Change an image: its url or mediaid, alt text, variant, rank or size

PATCH /api/v1/orgs/{org_slug}/commerce/products/{product_id}/images/{image_id}

Change an image: its url or media_id, alt text, variant, rank or size.

With media_id the image takes the file's width and height unless the body gives them, and the file's alt text when the file has one and the body gives none. If the image was the thumbnail, the thumbnail follows it.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`image_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required	Description
`url`	string or null	no
`media_id`	string or null	no	An image in the store's media, such as media_01J9Z8Q4N6, in place of url. The image then links to the file's url, and takes its width, height and alt text unless the body gives them.
`alt`	string or null	no
`variant_id`	integer or null	no
`rank`	integer or null	no
`width`	integer or null	no
`height`	integer or null	no

Responses

Section titled If it was the thumbnail, the next image takes its place

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

If it was the thumbnail, the next image takes its place

DELETE /api/v1/orgs/{org_slug}/commerce/products/{product_id}/images/{image_id}

If it was the thumbnail, the next image takes its place.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`image_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled An option such as Size

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

An option such as Size

POST /api/v1/orgs/{org_slug}/commerce/products/{product_id}/options

An option such as Size. Every existing variant takes its first value.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`title`	string or null	no
`values`	array of any or null	no

Responses

Section titled Update option

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Update option

PATCH /api/v1/orgs/{org_slug}/commerce/products/{product_id}/options/{option_id}

Rename the option, or give its full list of values: new ones are added, and one a variant still uses cannot be left out (409).

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`option_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`title`	string or null	no
`values`	array of any or null	no

Responses

Section titled Delete option

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Delete option

DELETE /api/v1/orgs/{org_slug}/commerce/products/{product_id}/options/{option_id}

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`option_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Create variant

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Create variant

POST /api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants

A variant naming one value for each of the product's options (a new value is added to its option). Its inventory item is created with it.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`weight_g`	integer or null	no
`length_mm`	integer or null	no
`width_mm`	integer or null	no
`height_mm`	integer or null	no
`hs_code`	string or null	no
`origin_country`	string or null	no
`mid_code`	string or null	no
`material`	string or null	no
`tax_code`	string or null	no
`external_id`	string or null	no
`metadata`	object or null	no
`title`	string or null	no
`sku`	string or null	no
`barcode`	string or null	no
`ean`	string or null	no
`upc`	string or null	no
`options`	object or null	no
`manage_inventory`	boolean or null	no
`allow_backorder`	boolean or null	no
`rank`	integer or null	no
`prices`	array of object or null	no

Responses

Section titled Fields change when named; prices replaces the variant's base prices

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields change when named; prices replaces the variant's base prices

PATCH /api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}

Fields change when named; prices replaces the variant's base prices.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`variant_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Field	Type	Required
`weight_g`	integer or null	no
`length_mm`	integer or null	no
`width_mm`	integer or null	no
`height_mm`	integer or null	no
`hs_code`	string or null	no
`origin_country`	string or null	no
`mid_code`	string or null	no
`material`	string or null	no
`tax_code`	string or null	no
`external_id`	string or null	no
`metadata`	object or null	no
`title`	string or null	no
`sku`	string or null	no
`barcode`	string or null	no
`ean`	string or null	no
`upc`	string or null	no
`options`	object or null	no
`manage_inventory`	boolean or null	no
`allow_backorder`	boolean or null	no
`rank`	integer or null	no
`prices`	array of object or null	no

Responses

Section titled Gone from the catalog; orders keep naming it, and its SKU is free

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Gone from the catalog; orders keep naming it, and its SKU is free

DELETE /api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}

Gone from the catalog; orders keep naming it, and its SKU is free.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`variant_id`	path	integer	yes
`org_slug`	path	string	yes

Responses

Section titled Replace variant prices

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Replace variant prices

PUT /api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}/prices

The variant's base prices (outside any price list) become exactly these: {"prices": [...]} or a bare list of {currency_code, amount, compare_at_amount?, region_id?, min_quantity?, max_quantity?}.

Parameters

Name	In	Type	Required
`product_id`	path	integer	yes
`variant_id`	path	integer	yes
`org_slug`	path	string	yes

Request body

application/json (required)

Type: Payload.

Responses