# Organization API: Catalog & Services: Commerce

> The 16 Organization API operations for commerce.

Source: https://www.coritan.com/docs/api/reference/organizations/catalog-services/commerce/

Part of [Catalog & Services](/docs/api/reference/organizations/catalog-services/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/collections/{collection_id}/products`](#op-put-api-v1-orgs-org-slug-commerce-collections-collection-id-products) | A manual collection's products become exactly these, in this order |
| GET | [`/api/v1/orgs/{org_slug}/commerce/products`](#op-get-api-v1-orgs-org-slug-commerce-products) | Products, most recently changed first |
| POST | [`/api/v1/orgs/{org_slug}/commerce/products`](#op-post-api-v1-orgs-org-slug-commerce-products) | Create product |
| GET | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}`](#op-get-api-v1-orgs-org-slug-commerce-products-product-id) | Get product |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}`](#op-patch-api-v1-orgs-org-slug-commerce-products-product-id) | Fields change when named |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}`](#op-delete-api-v1-orgs-org-slug-commerce-products-product-id) | Archived and gone from every list and the Store API |
| POST | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/images`](#op-post-api-v1-orgs-org-slug-commerce-products-product-id-images) | An https image |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/images/{image_id}`](#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-images-image-id) | Update image |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/images/{image_id}`](#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-images-image-id) | If it was the thumbnail, the next image takes its place |
| POST | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/options`](#op-post-api-v1-orgs-org-slug-commerce-products-product-id-options) | An option such as Size |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/options/{option_id}`](#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-options-option-id) | Update option |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/options/{option_id}`](#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-options-option-id) | Delete option |
| POST | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants`](#op-post-api-v1-orgs-org-slug-commerce-products-product-id-variants) | Create variant |
| PATCH | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}`](#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id) | Fields change when named; prices replaces the variant's base prices |
| DELETE | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}`](#op-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 |
| PUT | [`/api/v1/orgs/{org_slug}/commerce/products/{product_id}/variants/{variant_id}/prices`](#op-put-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id-prices) | Replace variant prices |

### A manual collection's products become exactly these, in this order {#op-put-api-v1-orgs-org-slug-commerce-collections-collection-id-products}

`PUT /api/v1/orgs/{org_slug}/commerce/collections/{collection_id}/products`

A manual collection's products become exactly these, in this order.
A smart collection answers 409: its rules choose.

#### Parameters

| 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

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

### Products, most recently changed first {#op-get-api-v1-orgs-org-slug-commerce-products}

`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

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

### Create product {#op-post-api-v1-orgs-org-slug-commerce-products}

`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

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

### Get product {#op-get-api-v1-orgs-org-slug-commerce-products-product-id}

`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

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

### Fields change when named {#op-patch-api-v1-orgs-org-slug-commerce-products-product-id}

`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

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

### Archived and gone from every list and the Store API {#op-delete-api-v1-orgs-org-slug-commerce-products-product-id}

`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

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

### An https image {#op-post-api-v1-orgs-org-slug-commerce-products-product-id-images}

`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

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

### Update image {#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-images-image-id}

`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

| 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 {#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-images-image-id}

`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

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

### An option such as Size {#op-post-api-v1-orgs-org-slug-commerce-products-product-id-options}

`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

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

### Update option {#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-options-option-id}

`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

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

### Delete option {#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-options-option-id}

`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

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

### Create variant {#op-post-api-v1-orgs-org-slug-commerce-products-product-id-variants}

`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

| 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 {#op-patch-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id}

`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

| 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 {#op-delete-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id}

`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

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

### Replace variant prices {#op-put-api-v1-orgs-org-slug-commerce-products-product-id-variants-variant-id-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

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