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.

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

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}

Parameters

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

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

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

An https image

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

An https image. The first one becomes the thumbnail if there is none.

Parameters

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

Request body

application/json (required)

Field	Type	Required
`url`	string or null	no
`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 Update image

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

Update image

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

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
`url`	string or null	no
`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