Create a product

Creates a new product with the provided details including name, product number, status, tax group, and optional metadata. Returns the created product with all related data including variants, prices, and market status.

POST/api/v1/{team_slug}/{app_slug}/products

API: Management
OpenAPI: management-api
Updated: Apr 26, 2026

management-api:POST:/api/v1/{team_slug}/{app_slug}/products

API ownership

API family: Management API
Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data.
Do not use from: Browser-only storefront code or public clients.
Guide route: /apis/management/latest

The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation.

Operation

Method: POST
Path: /api/v1/\{team_slug\}/\{app_slug\}/products
Summary: Create a product
Description: Creates a new product with the provided details including name, product number, status, tax group, and optional metadata. Returns the created product with all related data including variants, prices, and market status.
OpenAPI contract: management-api
Operation ID: Not documented in the OpenAPI contract.

Operation key uses API family, method, and path because this OpenAPI contract does not publish an operation ID.

Parameters2 parameters

Name	In	Required	Type	Description
app_slug	path	Yes	string	App slug
team_slug	path	Yes	string	Team slug

Request bodyDocumented body

Required: Yes
Description: Product data
Content: application/json (object)

Create Product Payload

Property	Type	Required	Details
`brand_id`	string	No	Brand or series of a brand connected to product
`custom`	object	No	Custom fields
`description`	string	No	Deprecated: read-only in write payloads. Derived from html_description.
`exclude_from_feeds`	boolean	No	Whenever a product should exist in feeds or not. Default `false`
`html_description`	string	No	HTML description of the description fields. All of the fields which is not related to showing content, e.g or tags will be stripped from the input
`html_short_description`	string	No	HTML Shortdescription of the description fields. All of the fields which is not related to showing content, e.g or tags will be stripped from the input
`market_status`	object[]	No	-
`meta_description`	string	No	Meta description for SEO
`meta_title`	string	No	Meta title for SEO
`package_dimensions`	object	No	The package dimensions
`product_dimensions`	object	No	The products dimensions
`product_name`	string	Yes	Name of the product
`product_number`	string	Yes	Product number
`product_type`	enum("flexible", "simple")	No	Product type. Default 'simple'
`short_description`	string	No	Deprecated: read-only in write payloads. Derived from html_short_description.
`slug`	string	No	Slug for the product
`status`	enum("active", "draft", "inactive", "archived")	Yes	Status of the product
`tax_group_slug`	string	Yes	The tax group related to the product

Product Market Status

Property	Type	Required	Details
`market_id`	string	Yes	-
`status`	enum("active", "inactive", "draft", "incomplete", "archived")	Yes	-
`store_group_id`	string	Yes	-

Dimensions

Property	Type	Required	Details
`capacity_milliliter`	integer	No	min: 0 the capacity in milliliter
`depth`	integer	No	min: 0 The products depth in millimeter
`diameter`	integer	No	min: 0 the products diameter in millimeter
`height`	integer	No	min: 0 The products height in millimeter
`length`	integer	No	min: 0 The products length in millimeter
`weight`	integer	No	min: 0 The products weight in grams
`width`	integer	No	min: 0 The products width in millimeter

{
  "brand_id": "string",
  "custom": {},
  "description": "string",
  "exclude_from_feeds": false,
  "html_description": "string",
  "html_short_description": "string",
  "market_status": [
    {
      "market_id": "string",
      "status": "active",
      "store_group_id": "string"
    }
  ],
  "meta_description": "string",
  "meta_title": "string",
  "package_dimensions": {
    "capacity_milliliter": 0,
    "depth": 0,
    "diameter": 0,
    "height": 0,
    "length": 0,
    "weight": 0,
    "width": 0
  },
  "product_dimensions": {
    "capacity_milliliter": 0,
    "depth": 0,
    "diameter": 0,
    "height": 0,
    "length": 0,
    "weight": 0,
    "width": 0
  },
  "product_name": "string",
  "product_number": "string",
  "product_type": "flexible",
  "short_description": "string",
  "slug": "string",
  "status": "active",
  "tax_group_slug": "string"
}

Responses4 statuses

Status	Description	Content
201	Product created or updated successfully	application/json (object)
400	Invalid request (e.g. bad UUID, validation error)	application/json (object)
401	Unauthorized access	application/json (object)
500	Internal server error	application/json (object)

201 - object

Product Response

Property	Type	Required	Details
`data`	object	No	-
`details`	string[]	No	Additional contextual information about the response. Used to provide supplementary details beyond the main data payload, such as validation warnings or processing notes
`success`	boolean	No	-

Product

Property	Type	Required	Details
`attributes`	object[]	No	Product attributes
`brand`	object	No	Brand of the product
`categories`	object[]	No	Associated categories
`channel_statuses`	object[]	No	-
`collections`	object[]	No	Associated collections
`created_at`	string	No	Creation timestamp
`custom`	object	No	-
`description`	string	No	Description of the product
`exclude_from_feeds`	boolean	No	If the products should exist in feeds or not
`files`	object[]	No	Product files
`html_description`	string	No	Html description
`html_short_description`	string	No	Html short description
`id`	string	No	Product ID
`images`	object[]	No	Images of the product
`market_status`	object[]	No	-
`markets`	object[]	No	Associated markets
`meta_description`	string	No	Meta description for SEO
`meta_title`	string	No	Meta title for SEO
`package_dimensions`	object	No	The package dimensions
`product_dimensions`	object	No	The products dimensions
`product_name`	string	No	VariantName of the product
`product_number`	string	No	Product number
`product_type`	string	No	Product type
`redirects`	object[]	No	Product redirects
`relations`	object[]	No	Product relations
`schedules`	object[]	No	-
`short_description`	string	No	Short description of the product
`slug`	string	No	Slug for the product
`source_app_id`	string	No	-
`source_id`	string	No	-
`status`	string	No	Status of the product
`tags`	object[]	No	Product tags
`tax_group_id`	string	No	The id of the tax group
`third_part_links`	object[]	No	-
`translations`	object	No	Product translations
`updated_at`	string	No	Last updated timestamp
`variant_groups`	object[]	No	Variant groups with images, attributes, videos
`variants`	object[]	No	Product variants
`videos`	object[]	No	Videos of the product

Attribute

Property	Type	Required	Details
`created_at`	string	No	-
`description`	string	No	-
`filterable`	boolean	No	-
`id`	string	No	-
`key`	string	No	-
`name`	string	No	-
`template_key`	string	No	-
`template_name`	string	No	-
`translatable`	boolean	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`values`	object	No	-

Product Brand

Property	Type	Required	Details
`address`	object	No	-
`email`	string	No	-
`id`	string	No	-
`name`	string	No	-
`series`	object	No	-
`slug`	string	No	-

Brand Address

Property	Type	Required	Details
`city`	string	No	-
`co_address`	string	No	-
`country`	string	No	-
`house_number`	string	No	-
`postal_code`	string	No	-
`state_province`	string	No	-
`street_address`	string	No	-

Product Series

Property	Type	Required	Details
`id`	string	No	-
`name`	string	No	-
`slug`	string	No	-

Product Category

Property	Type	Required	Details
`attributes`	object[]	No	-
`children`	object[]	No	-
`cover_url`	string	No	-
`created_at`	string	No	-
`google_product_category_id`	string	No	-
`id`	string	No	-
`is_main_category`	boolean	No	-
`name`	string	No	-
`order`	integer	No	-
`parent_id`	string	No	-
`redirects`	object[]	No	-
`slug`	string	No	-
`sort_order`	integer	No	Used for ordering categories themselves
`status`	string	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`uri`	string	No	-

Product Channel Status

Property	Type	Required	Details
`channel_id`	string	No	-
`channel_slug`	string	No	-
`status`	string	No	-

Product Collection

Property	Type	Required	Details
`children`	object[]	No	-
`created_at`	string	No	-
`id`	string	No	-
`order`	integer	No	-
`parent_id`	string	No	-
`redirects`	object[]	No	-
`slug`	string	Yes	-
`status`	enum("active", "inactive", "draft")	Yes	-
`title`	string	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`uri`	string	No	-

File

Property	Type	Required	Details
`attributes`	object[]	No	-
`created_at`	string	No	-
`folder_id`	string	No	-
`id`	string	No	-
`public`	boolean	No	-
`title`	string	No	-
`translations`	object	No	-
`type`	string	No	-
`updated_at`	string	No	-
`url`	string	No	-

Image With Priority

Property	Type	Required	Details
`alt`	string	No	-
`app_id`	string	No	-
`attributes`	object[]	No	-
`blurhash`	string	No	-
`copyright`	string	No	-
`custom`	object	No	-
`folder_id`	string	No	-
`id`	string	No	-
`parent_id`	string	No	-
`priority`	integer	No	-
`public`	boolean	No	-
`source_app_id`	string	No	-
`source_id`	string	No	-
`status`	string	No	-
`title`	string	No	-
`translations`	object	No	-
`url`	string	No	-

Market Status

Property	Type	Required	Details
`created_at`	string	No	-
`market_id`	string	No	-
`market_slug`	string	No	-
`status`	string	No	-
`store_group_id`	string	No	-
`store_group_slug`	string	No	-
`updated_at`	string	No	-

Market

Property	Type	Required	Details
`active`	boolean	No	-
`country_codes`	string[]	No	-
`created_at`	string	No	-
`currency_code`	string	No	-
`id`	string	No	-
`locale`	string	No	-
`name`	string	No	-
`slug`	string	No	-
`updated_at`	string	No	-

Dimensions

Property	Type	Required	Details
`capacity_milliliter`	integer	No	min: 0 the capacity in milliliter
`depth`	integer	No	min: 0 The products depth in millimeter
`diameter`	integer	No	min: 0 the products diameter in millimeter
`height`	integer	No	min: 0 The products height in millimeter
`length`	integer	No	min: 0 The products length in millimeter
`weight`	integer	No	min: 0 The products weight in grams
`width`	integer	No	min: 0 The products width in millimeter

Redirects

Property	Type	Required	Details
`id`	string	No	-
`item_id`	string	No	-
`locale`	string	No	-
`new_slug`	string	No	-
`old_slug`	string	No	-
`type`	enum("product", "page", "collection", "category", "product_bundle")	No	-

Relation

Property	Type	Required	Details
`direction`	string	No	-
`id`	string	No	-
`primary_product_id`	string	No	-
`products`	object[]	No	-
`title`	string	No	-
`type`	string	No	-
`type_id`	string	No	-

Job

Property	Type	Required	Details
`add_category_names`	string[]	No	-
`add_collection_names`	string[]	No	-
`add_tag_names`	string[]	No	-
`execute_at`	string	No	Date when the job should run
`finished_at`	string	No	If a job is finished will this timestamp be filled
`id`	string	No	-
`item_id`	string	No	-
`item_name`	string	No	-
`item_type`	string	No	-
`remove_category_names`	string[]	No	-
`remove_collection_names`	string[]	No	-
`remove_tag_names`	string[]	No	-
`to_amount_cents_with_tax`	integer	No	-
`to_market_id`	string	No	-
`to_market_status`	string	No	-
`to_on_sale`	boolean	No	-
`to_sale_amount_cents_with_tax`	integer	No	-
`to_start_sale_timestamp`	string	No	-
`to_status`	string	No	-
`to_stop_sale_timestamp`	string	No	-
`to_store_group_id`	string	No	-

Product Tag

Property	Type	Required	Details
`attributes`	object[]	No	-
`created_at`	string	No	-
`filterable`	boolean	No	-
`id`	string	No	-
`key`	string	No	-
`markets`	object[]	No	-
`name`	string	No	-
`order`	integer	No	-
`schedules`	object[]	No	-
`source_app_id`	string	No	-
`source_id`	string	No	-
`status`	string	No	-
`translations`	object	No	-
`updated_at`	string	No	-

Third Party Link

Property	Type	Required	Details
`created_at`	string	No	-
`id`	string	No	-
`title`	string	No	-
`type`	string	No	-
`updated_at`	string	No	-
`url`	string	No	-

Product Translations

Property	Type	Required	Details
`description`	object[]	No	-
`html_description`	object[]	No	-
`html_short_description`	object[]	No	-
`meta_description`	object[]	No	-
`meta_title`	object[]	No	-
`name`	object[]	No	-
`short_description`	object[]	No	-
`slug`	object[]	No	-

Variant Group

Property	Type	Required	Details
`attributes`	object[]	No	-
`channel_statuses`	object[]	No	-
`created_at`	string	No	-
`id`	string	No	-
`images`	object[]	No	-
`name`	string	No	-
`priority`	integer	No	-
`product_id`	string	No	-
`slug`	string	No	-
`tags`	object[]	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`variants`	object[]	No	-
`videos`	object[]	No	-

Variant

Property	Type	Required	Details
`attributes`	object[]	No	-
`created_at`	string	No	-
`custom_fields`	object	No	-
`id`	string	No	-
`images`	object[]	No	Images of the product
`listings`	object	No	-
`parent_product_id`	string	No	-
`purchase_price`	object	No	-
`shipping_attributes`	string[]	No	-
`source_app_id`	string	No	-
`source_id`	string	No	-
`status`	string	No	-
`store_group`	object[]	No	Product StoreGroup
`tags`	object[]	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`validate_stock`	boolean	No	-
`variant_dimensions`	object	No	-
`variant_group_id`	string	No	-
`variant_name`	string	No	-
`variant_number`	string	No	-
`videos`	object[]	No	Videos of the product
`warehouse_variant_stock`	object[]	No	-

Video

Property	Type	Required	Details
`attributes`	object[]	No	-
`description`	string	No	-
`folder_id`	string	No	-
`id`	string	No	-
`path`	string	No	-
`public`	boolean	No	-
`status`	string	No	-
`title`	string	No	-
`translations`	object	No	-
`variants`	object[]	No	-

{
  "data": {
    "attributes": [
      {
        "created_at": "string",
        "description": "string",
        "filterable": false,
        "id": "string",
        "key": "string",
        "name": "string",
        "template_key": "string",
        "template_name": "string",
        "translatable": false,
        "translations": {
          "description": null,
          "name": null
        },
        "updated_at": "string",
        "values": {}
      }
    ],
    "brand": {
      "address": {
        "city": "string",
        "co_address": "string",
        "country": "string",
        "house_number": "string",
        "postal_code": "string",
        "state_province": "string",
        "street_address": "string"
      },
      "email": "string",
      "id": "string",
      "name": "string",
      "series": {
        "id": "string",
        "name": "string",
        "slug": "string"
      },
      "slug": "string"
    },
    "categories": [
      {
        "attributes": [],
        "children": [],
        "cover_url": "string",
        "created_at": "string",
        "google_product_category_id": "string",
        "id": "string",
        "is_main_category": false,
        "name": "string",
        "order": 0,
        "parent_id": "string",
        "redirects": [],
        "slug": "string",
        "sort_order": 0,
        "status": "string",
        "translations": {
          "name": null,
          "slug": null
        },
        "updated_at": "string",
        "uri": "string"
      }
    ],
    "channel_statuses": [
      {
        "channel_id": "string",
        "channel_slug": "string",
        "status": "string"
      }
    ],
    "collections": [
      {
        "children": [],
        "created_at": "string",
        "id": "string",
        "order": 0,
        "parent_id": "string",
        "redirects": [],
        "slug": "string",
        "status": "active",
        "title": "string",
        "translations": {
          "slug": null,
          "title": null
        },
        "updated_at": "string",
        "uri": "string"
      }
    ],
    "created_at": "string",
    "custom": {},
    "description": "string",
    "exclude_from_feeds": false,
    "files": [
      {
        "attributes": [],
        "created_at": "string",
        "folder_id": "string",
        "id": "string",
        "public": false,
        "title": "string",
        "translations": {
          "title": null,
          "type": null
        },
        "type": "string",
        "updated_at": "string",
        "url": "string"
      }
    ],
    "html_description": "string",
    "html_short_description": "string",
    "id": "string",
    "images": [
      {
        "alt": "string",
        "app_id": "string",
        "attributes": [],
        "blurhash": "string",
        "copyright": "string",
        "custom": {},
        "folder_id": "string",
        "id": "string",
        "parent_id": "string",
        "priority": 0,
        "public": false,
        "source_app_id": "string",
        "source_id": "string",
        "status": "string",
        "title": "string",
        "translations": {
          "alt": null,
          "copyright": null,
          "title": null
        },
        "url": "string"
      }
    ],
    "market_status": [
      {
        "created_at": "string",
        "market_id": "string",
        "market_slug": "string",
        "status": "string",
        "store_group_id": "string",
        "store_group_slug": "string",
        "updated_at": "string"
      }
    ],
    "markets": [
      {
        "active": false,
        "country_codes": [],
        "created_at": "string",
        "currency_code": "string",
        "id": "string",
        "locale": "string",
        "name": "string",
        "slug": "string",
        "updated_at": "string"
      }
    ],
    "meta_description": "string",
    "meta_title": "string",
    "package_dimensions": {
      "capacity_milliliter": 0,
      "depth": 0,
      "diameter": 0,
      "height": 0,
      "length": 0,
      "weight": 0,
      "width": 0
    },
    "product_dimensions": {
      "capacity_milliliter": 0,
      "depth": 0,
      "diameter": 0,
      "height": 0,
      "length": 0,
      "weight": 0,
      "width": 0
    },
    "product_name": "string",
    "product_number": "string",
    "product_type": "string",
    "redirects": [
      {
        "id": "string",
        "item_id": "string",
        "locale": "string",
        "new_slug": "string",
        "old_slug": "string",
        "type": "product"
      }
    ],
    "relations": [
      {
        "direction": "string",
        "id": "string",
        "primary_product_id": "string",
        "products": [],
        "title": "string",
        "type": "string",
        "type_id": "string"
      }
    ],
    "schedules": [
      {
        "add_category_names": [],
        "add_collection_names": [],
        "add_tag_names": [],
        "execute_at": "string",
        "finished_at": "string",
        "id": "string",
        "item_id": "string",
        "item_name": "string",
        "item_type": "string",
        "remove_category_names": [],
        "remove_collection_names": [],
        "remove_tag_names": [],
        "to_amount_cents_with_tax": 0,
        "to_market_id": "string",
        "to_market_status": "string",
        "to_on_sale": false,
        "to_sale_amount_cents_with_tax": 0,
        "to_start_sale_timestamp": "string",
        "to_status": "string",
        "to_stop_sale_timestamp": "string",
        "to_store_group_id": "string"
      }
    ],
    "short_description": "string",
    "slug": "string",
    "source_app_id": "string",
    "source_id": "string",
    "status": "string",
    "tags": [
      {
        "attributes": [],
        "created_at": "string",
        "filterable": false,
        "id": "string",
        "key": "string",
        "markets": [],
        "name": "string",
        "order": 0,
        "schedules": [],
        "source_app_id": "string",
        "source_id": "string",
        "status": "string",
        "translations": {
          "name": null
        },
        "updated_at": "string"
      }
    ],
    "tax_group_id": "string",
    "third_part_links": [
      {
        "created_at": "string",
        "id": "string",
        "title": "string",
        "type": "string",
        "updated_at": "string",
        "url": "string"
      }
    ],
    "translations": {
      "description": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ],
      "html_description": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ],
      "html_short_description": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ],
      "meta_description": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ],
      "meta_title": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ],
      "name": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ],
      "short_description": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ],
      "slug": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ]
    },
    "updated_at": "string",
    "variant_groups": [
      {
        "attributes": [],
        "channel_statuses": [],
        "created_at": "string",
        "id": "string",
        "images": [],
        "name": "string",
        "priority": 0,
        "product_id": "string",
        "slug": "string",
        "tags": [],
        "translations": {
          "name": null,
          "slug": null
        },
        "updated_at": "string",
        "variants": [],
        "videos": []
      }
    ],
    "variants": [
      {
        "attributes": [],
        "created_at": "string",
        "custom_fields": {},
        "id": "string",
        "images": [],
        "listings": {
          "smart": null,
          "static": null
        },
        "parent_product_id": "string",
        "purchase_price": {
          "currency": null,
          "value_cents": null
        },
        "shipping_attributes": [],
        "source_app_id": "string",
        "source_id": "string",
        "status": "string",
        "store_group": [],
        "tags": [],
        "translations": {
          "name": null
        },
        "updated_at": "string",
        "validate_stock": false,
        "variant_dimensions": {
          "capacity_milliliter": null,
          "depth": null,
          "diameter": null,
          "height": null,
          "length": null,
          "weight": null,
          "width": null
        },
        "variant_group_id": "string",
        "variant_name": "string",
        "variant_number": "string",
        "videos": [],
        "warehouse_variant_stock": []
      }
    ],
    "videos": [
      {
        "attributes": [],
        "description": "string",
        "folder_id": "string",
        "id": "string",
        "path": "string",
        "public": false,
        "status": "string",
        "title": "string",
        "translations": {
          "description": null,
          "title": null
        },
        "variants": []
      }
    ]
  },
  "details": [
    "string"
  ],
  "success": false
}

400 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

401 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

500 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

Contract identity

Use these fields to confirm you are implementing the intended endpoint contract.

API family: Management API
Method: POST
Path: /api/v1/\{team_slug\}/\{app_slug\}/products
Operation ID: Not documented in the OpenAPI contract.
OpenAPI tag: Products
OpenAPI summary: Create a product