Create Product

post https://{shopdomain}.myshoplaza.com/openapi/2022-01/products

🔒
Requires write_product access scope. For more access scope

The Create Product API enables merchants to add new products to their store seamlessly. This endpoint supports detailed customization of product attributes, including title, price, inventory, and more.This API is especially useful for:

Adding new products with tailored specifications such as descriptions, SEO details, and inventory settings.
Simplifying product management with customizable fields like tags, variants, and vendor details.

Note: The operation is scoped to a specific shop, identified by its unique domain prefix (shopdomain), ensuring all updates are applied to the correct store.

Public Request Parameters

Parameter Name	Type	Required	Parameter Location	Parameter Value	Description
Access-Token	`String`	Yes	Header	Bx-_5aV eXNwl-4AB98s5xLV yg0fNzGf MuTpqtlBA	Used to authenticate API requests. Obtain an access token from the Access Token Guide. Pass it in the `Authorization` header for every request.
Content-Type	`String`	Yes	Header	`application` `/json`	Indicates the media type of the request body. It tells the server how to parse the request and the client how to interpret the response. For more details, visit Content-Type.

Public Response Parameters

Parameter Name	Type	Mandatory	Parameter Location	Example Value	Description
error	String	No	Response Body	`{ "error": "store is not active" }`	Indicates an error encountered during the process. This field typically appears when the Access Token is missing or invalid. Example: `{ "error": "store is not active" }`.
errors	Array	No	Response Body	`{ "errors"["No Context"] }`	A list of errors that occurred during the request processing. Example: `{ "errors": [ "No Context" ] }`.
Request-Id	String	Yes	Header	Bx-_5aV eXNwl-4AB98s5xLV yg0fNzGf MuTpqtlBA	A unique identifier for each request. It helps in identifying and debugging specific requests.

Error and Errors Clarification:

Added explanation that the error and errors fields are currently dependent on the API implementation, with plans for future unification.

Request Parameters

Body Parameters

Parameter	Type	Required	Example	Description
`title`	String	Yes	`"Test Product"`	The title of the product.
`brief`	String	No	`"Short description` `of product"`	A brief description of the product.
`description`	String	No	`"Detailed` `description here."`	Detailed description of the product.
`published`	Boolean	No	`true`	Indicates if the product is published.
`requires_shipping`	Boolean	No	`false`	Specifies if shipping is required for the product.
`taxable`	Boolean	No	`true`	Indicates if the product is taxable.
`tags`	String	No	`"tag1,tag2"`	Tags for categorizing the product, separated by commas.
`vendor`	String	No	`"Vendor Name"`	Name of the vendor for the product.
`vendor_url`	String	No	`"https://vendor-` `website.com"`	Vendor's URL.
`note`	String	No	`"Additional notes"`	Notes associated with the product.
`seo_title`	String	No	`"SEO Title"`	SEO-friendly title for the product.
`seo_description`	String	No	`"SEO Description"`	SEO description for the product.
`seo_keywords`	String	No	`"keyword1,keyword2"`	SEO keywords separated by commas.
`handle`	String	No	`"product-handle"`	URL handle for the product.
`has_only_default_variant`	Boolean	Yes	`true`	Indicates if the product has only a default variant. Defaults to`true`.
`inventory_tracking`	Boolean	No	`true`	Specifies if inventory tracking is enabled.
`inventory_policy`	String	No	`"continue"`	Inventory policy (e.g., `continue`, `deny`,`auto_unpublished`). Required if `inventory_tracking` is `true`.
`need_variant_image`	Boolean	No	`false`	Specifies if a variant image is needed. It's required if `has_only_default_variant` is false
`spu`	String	No	`"SPU12345"`	Stock-keeping unit (SPU) for the product.
`fake_sales`	Integer	No	`100`	Fake sales count for display purposes.
`display_fake_sales`	Boolean	No	`true`	Whether to display fake sales count.
`options`	Array of options object	No	`[{"name": "Size", "values":` `["S", "M", "L"]}]`	Product options like size or color.
`options.name`	String	Required if new options	`Size`	Product option's name
`options.values`	Array of Strings	Required if new options	`["S", "M", "L"]`	options list
`images`	Array of image object	No	`[{"src": "image_url",` `"alt": "Alt text"}]`	Images associated with the product.
`images.src`	String	Required if new images	`"image_url"`	URL of the image.
`images.width`	Integer	No	`100`	Width of the image in pixels.
`images.height`	Integer	No	`100`	Height of the image in pixels.
`images.alt`	String	No	`"Alt text"`	Alt text for the image.
`variants`	Array of variant object	No	`[{"option1": "S",` `"price": 19.99}]`	Variants of the product, including price and options.
`variants.option1`	String	No	`"S"`	First option value.
`variants.option2`	String	No	`"Black"`	Second option value.
`variants.option3`	String	No	`"Light"`	Third option value.
`variants.image`	Array of image object	No	`[{"src": "image_url", "alt": "Alt text"}]`	Images associated with the product.
`variants.image.src`	String	Required if new `variant.images`	`"image_url"`	URL of the image.
`variants.image.width`	Integer	No	`100`	Width of the image in pixels.
`variants.image.height`	Integer	No	`100`	Height of the image in pixels.
`variants.image.alt`	String	No	`"Alt text"`	Alt text for the image.
`variants.compare_at_price`	String	No	`"29.99"`	The compare-at price for discounts.
`variants.price`	String	Yes	`"29.99"`	The price of the variant, set it to "0.00" if you want to leave the price empty.
`variants.sku`	String	No	`"SKU12345"`	Stock Keeping Unit for the variant.
`variants.barcode`	String	No		Barcode of the variant.
`variants.note`	String	No	`"123456789012"`	Additional notes about the variant.
`variants.inventory_quantity`	Integer	No	`100`	Available inventory quantity.
`variants.weight`	String	No		The weight of the variant.
`variants.weight_unit`	String	No	`"100"`	Possible value are: kg, g, lb, oz
`variants.cost_price`	String	No	`"100"`	Cost price
`variants.wholesale_price`	Array of wholsesale price	No	`[{"price": 8.99,` `"min_quantity": 10}]`	Wholesale pricing information.
`variants.wholesale_price.` `price`	String	No	`"8.99"`	The wholesale price for the variant.
`variants.wholesale_price.` `min_quantity`	Integer	No	`18`	Minimum quantity for the price.
`mixed_wholesale`	Boolean	No	`true`	Indicates if mixed wholesale pricing is supported.
`unique_token`	String	Yes	`"e6cc4df1-d4f5-` `4ad4-a019-2e0f3ddd6e63"`	Unique token for idempotency verification.

Response Explanation

Successful Response

Field	Type	Example	Description
`product.id`	`string`	`"9fb9f3c6-2300-42c1` `-8593-d9008d7cfc09"`	Unique identifier for the product.
`product.title`	`string`	`"Stylish Shirt"`	Title of the product.
`product.brief`	`string`	`"A stylish shirt."`	Brief description or summary of the product.
`product.description`	`string`	`""`	Full description of the product.
`product.published`	`boolean`	`true`	Indicates whether the product is published.
`product.requires_shipping`	`boolean`	`true`	Indicates if the product requires shipping.
`product.taxable`	`boolean`	`true`	Indicates if the product is subject to tax.
`product.tags`	`string`	`"shirt,stylish,cotton"`	Tags associated with the product, separated by commas.
`product.vendor`	`string`	`"Awesome Vendor"`	Name of the product vendor.
`product.vendor_url`	`string`	`"https://awesomevendor.com"`	URL of the vendor's website.
`product.inventory_quantity`	`integer`	`300`	Total inventory available for the product.
`product.published_at`	`string (ISO8601)`	`"2024-12-03T19:02:30Z"`	Timestamp when the product was published.
`product.created_at`	`string (ISO8601)`	`"2024-12-03T19:02:30Z"`	Timestamp when the product was created.
`product.updated_at`	`string (ISO8601)`	`"2024-12-03T19:02:30Z"`	Timestamp when the product was last updated.
`product.note`	`string`	`"Special promotion item."`	Notes or special remarks about the product.
`product.seo_title`	`string`	`"Buy Stylish Shirt Online"`	SEO-friendly title for the product.
`product.seo_description`	`string`	`"Premium cotton"`	SEO-friendly description for the product.
`product.seo_keywords`	`string`	`"shirt, cotton, stylish"`	SEO keywords for the product, separated by commas.
`product.handle`	`string`	`"stylish-shirt-zbxf"`	URL-friendly handle for the product.
`product.has_only_default_variant`	`boolean`	`false`	Indicates if the product has only the default variant.
`product.inventory_tracking`	`boolean`	`true`	Indicates if inventory tracking is enabled for the product.
`product.inventory_policy`	`string`	`"continue"`	Inventory policy for the product (e.g., `"continue"`, `"deny"`).
`product.need_variant_image`	`boolean`	`false`	The need_variant_image field is automatically set to true if any variant has an image; otherwise, it is set to false.
`product.spu`	`string`	`"SS1234"`	Product's Stock Keeping Unit (SPU) identifier.
`product.fake_sales`	`integer`	`50`	Fake sales count for display purposes.
`product.display_fake_sales`	`boolean`	`true`	Indicates if fake sales should be displayed.
`product.mixed_wholesale`	`boolean`	`true`	Indicates if mixed wholesale pricing is allowed for the product.
`product.image.src`	`string`	`"//img.fantaskycdn.` `com/loading.png"`	Source URL of the product's main image.
`product.image.width`	`integer`	`100`	Width of the product's main image in pixels.
`product.image.height`	`integer`	`100`	Height of the product's main image in pixels.
`product.image.path`	`string`	`"loading.png"`	File path of the product's main image.
`product.image.alt`	`string`	`""`	Alternative text for the product's main image.
`product.images`	array of image object	See `images` fields below	Array of additional images for the product.
`product.images[].id`	`string`	`"15333433-a0d5-44c` `9-941b-2c59ea07683e"`	Unique identifier for the image.
`product.images[].product_id`	`string`	`"9fb9f3c6-2300-42c1` `-8593-d9008d7cfc09"`	ID of the product associated with the image.
`product.images[].position`	`integer`	`1`	Position of the image in the gallery.
`product.images[].src`	`string`	`"//img.fantaskycdn.` `com/loading.png"`	Source URL of the image.
`product.images[].width`	`integer`	`100`	Width of the image in pixels.
`product.images[].height`	`integer`	`100`	Height of the image in pixels.
`product.images[].alt`	`string`	`""`	Alternative text for the image.
`product.images[].created_at`	`string (ISO8601)`	`"2024-12-03T19:02:30Z"`	Timestamp when the image was created.
`product.images[].updated_at`	`string (ISO8601)`	`"2024-12-03T19:02:30Z"`	Timestamp when the image was last updated.
`product.options`	array of options object	See `options` fields below	Array of product options, like size and color.
`product.options[].id`	`string`	`"8e40555e-a152-45fc-` `9587-fe85280701c5"`	Unique identifier for the option.
`product.options[].product_id`	`string`	`"9fb9f3c6-2300-42c1-` `8593-d9008d7cfc09"`	ID of the product associated with the option.
`product.options[].position`	`integer`	`1`	Position of the option.
`product.options[].name`	`string`	`"Size"`	Name of the option (e.g., `"Size"` or `"Color"`).
`product.options[].values`	`array of strings`	`["Small", "Medium", "Large"]`	Array of possible values for the option.
`product.variants`	array of variant object	See `variants` fields below	Array of product variants.
`product.variants[].id`	`string`	`"d7c7f9ba-f824-46b6-` `94af-1c2d1befaf27"`	Unique identifier for the variant.
`product.variants[].title`	`string`	`"Small-Red"`	Title of the variant.
`product.variants[].option1`	`string`	`"Small"`	Value of the first option for the variant.
`product.variants[].option2`	`string`	`"Red"`	Value of the second option for the variant.
`product.variants[].price`	`string`	`"19.99"`	Price of the variant.
`product.variants[].sku`	`string`	`"SS1234-RD-S"`	Stock Keeping Unit (SKU) for the variant.
`product.variants[].` `inventory_quantity`	`integer`	`100`	Inventory quantity for the variant.
`product.variants[].` `wholesale_price`	array of wholesale price	See `wholesale_price` fields below	Wholesale price information for the variant.
`product.variants[].` `wholesale_price[].price`	`string`	`"19.99"`	Wholesale price for the variant.
`product.variants[].` `wholesale_price[].min_quantity`	`integer`	`1`	Minimum quantity for the wholesale price.
`product.category`	`Object`	Category object	Category information for the product.
`product.category.id`	`integer`	368313940138040900	The ID of the category
`product.category.name`	`string`	`"3"`	Category name
`product.category.google_id.`	`integer`	`0`	Google category id
`product.category.level.`	`integer`	`"3"`	Level of category
`product.category.path.`	`string`	"368313940138008142, 368313940138024526, 368313940138040910"	The full path of a category, consisting of a category id.

Error Response

Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.

Field	Type	Example	Description
`errors`	Array	`["Context"]`	A list of errors encountered during the request processing.

Field	Type	Example	Description
`error`	Array	`"store is not active"`	Indicates an error encountered during the process.

Request Examples

curl -X POST "https://shopdomain.myshoplaza.com/openapi/2022-01/products \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{
  "product": {
    "title": "Stylish Shirt",
    "brief": "A stylish shirt.",
    "description": "",
    "published": true,
    "requires_shipping": true,
    "taxable": true,
    "tags": "shirt,stylish,cotton",
    "vendor": "Awesome Vendor",
    "vendor_url": "https://awesomevendor.com",
    "inventory_quantity": 300,
    "note": "Special promotion item.",
    "seo_title": "Buy Stylish Shirt Online",
    "seo_description": "Premium cotton",
    "seo_keywords": "shirt, cotton, stylish",
    "handle": "stylish-shirt-zbxf",
    "has_only_default_variant": false,
    "inventory_tracking": true,
    "inventory_policy": "continue",
    "need_variant_image": false,
    "spu": "SS1234",
    "fake_sales": 50,
    "display_fake_sales": true,
    "mixed_wholesale": true,
    "images": [
      {
        "src": "//img.fantaskycdn.com/loading.png",
        "width": 100,
        "height": 100,
        "alt": ""
      },
      {
        "src": "//img.fantaskycdn.com/loading.png",
        "width": 100,
        "height": 100,
        "alt": ""
      }
    ],
    "options": [
      {
        "name": "Size",
        "values": ["Small", "Medium", "Large", "Extra Large"]
      },
      {
        "name": "Color",
        "values": ["Red", "Blue", "Black"]
      }
    ],
    "variants": [
      {
        "title": "Small-Red",
        "option1": "Small",
        "option2": "Red",
        "compare_at_price": "29.99",
        "price": "19.99",
        "sku": "SS1234-RD-S",
        "barcode": "123456789012",
        "note": "Limited",
        "inventory_quantity": 100,
        "weight": "0.50",
        "weight_unit": "kg",
        "cost_price": "12.99",
        "wholesale_price": [
          {
            "price": "19.99",
            "min_quantity": 1
          }
        ]
      },
      {
        "title": "Medium-Blue",
        "option1": "Medium",
        "option2": "Blue",
        "compare_at_price": "29.99",
        "price": "19.99",
        "sku": "SS1234-BL-M",
        "barcode": "123456789013",
        "note": "Best-selling",
        "inventory_quantity": 200,
        "weight": "0.60",
        "weight_unit": "kg",
        "cost_price": "13.99",
        "wholesale_price": [
          {
            "price": "19.99",
            "min_quantity": 1
          }
        ]
      }
    ]
  }
}'

Success Response Example

{
    "product": {
        "id": "33f1b4f6-9474-4e6c-9a3f-676a420ea8bb",
        "title": "Stylish Shirt",
        "brief": "A stylish shirt.",
        "description": "",
        "published": true,
        "requires_shipping": true,
        "taxable": true,
        "tags": "shirt,stylish,cotton",
        "vendor": "Awesome Vendor",
        "vendor_url": "https://awesomevendor.com",
        "inventory_quantity": 300,
        "published_at": "2024-12-09T23:39:00Z",
        "created_at": "2024-12-09T23:39:00Z",
        "updated_at": "2024-12-09T23:39:00Z",
        "note": "Special promotion item.",
        "seo_title": "Buy Stylish Shirt Online",
        "seo_description": "Premium cotton",
        "seo_keywords": "shirt, cotton, stylish",
        "handle": "stylish-shirt-zbxf",
        "has_only_default_variant": false,
        "inventory_tracking": true,
        "inventory_policy": "continue",
        "need_variant_image": false,
        "spu": "SS1234",
        "fake_sales": 50,
        "display_fake_sales": true,
        "mixed_wholesale": true,
        "image": {
            "src": "//img.fantaskycdn.com/loading.png",
            "width": 100,
            "height": 100,
            "path": "loading.png",
            "alt": ""
        },
        "images": [
            {
                "id": "1a995f5e-d6e5-48df-bee8-8792a13deab3",
                "product_id": "33f1b4f6-9474-4e6c-9a3f-676a420ea8bb",
                "position": 1,
                "src": "//img.fantaskycdn.com/loading.png",
                "width": 100,
                "height": 100,
                "alt": "",
                "created_at": "2024-12-09T23:39:00Z",
                "updated_at": "2024-12-09T23:39:00Z"
            },
            {
                "id": "dd9d0f98-d610-4d9d-9670-55856573bc2c",
                "product_id": "33f1b4f6-9474-4e6c-9a3f-676a420ea8bb",
                "position": 2,
                "src": "//img.fantaskycdn.com/loading.png",
                "width": 100,
                "height": 100,
                "alt": "",
                "created_at": "2024-12-09T23:39:00Z",
                "updated_at": "2024-12-09T23:39:00Z"
            }
        ],
        "options": [
            {
                "id": "179fa6d5-3b61-4bae-9bb8-1594750a5991",
                "product_id": "33f1b4f6-9474-4e6c-9a3f-676a420ea8bb",
                "position": 1,
                "name": "Size",
                "values": [
                    "Small",
                    "Medium",
                    "Large",
                    "Extra Large"
                ]
            },
            {
                "id": "c4cb286c-2341-4ff3-95eb-9424499bc0c2",
                "product_id": "33f1b4f6-9474-4e6c-9a3f-676a420ea8bb",
                "position": 2,
                "name": "Color",
                "values": [
                    "Red",
                    "Blue",
                    "Black"
                ]
            }
        ],
        "variants": [
            {
                "id": "3fb78d27-0b56-41bc-bf9e-34e52ecd7529",
                "product_id": "33f1b4f6-9474-4e6c-9a3f-676a420ea8bb",
                "image_id": "",
                "created_at": "2024-12-09T23:39:00Z",
                "updated_at": "2024-12-09T23:39:00Z",
                "title": "Small-Red",
                "option1": "Small",
                "option2": "Red",
                "option3": "",
                "image": null,
                "position": 1,
                "compare_at_price": "29.99",
                "price": "19.99",
                "sku": "SS1234-RD-S",
                "barcode": "123456789012",
                "note": "Limited",
                "inventory_quantity": 100,
                "weight": "0.50",
                "weight_unit": "kg",
                "cost_price": "12.99",
                "wholesale_price": [
                    {
                        "price": "19.99",
                        "min_quantity": 1
                    }
                ],
                "extend": null
            },
            {
                "id": "f26b1b77-90b0-436f-9a8b-236a29cd5bfb",
                "product_id": "33f1b4f6-9474-4e6c-9a3f-676a420ea8bb",
                "image_id": "",
                "created_at": "2024-12-09T23:39:00Z",
                "updated_at": "2024-12-09T23:39:00Z",
                "title": "Medium-Blue",
                "option1": "Medium",
                "option2": "Blue",
                "option3": "",
                "image": null,
                "position": 2,
                "compare_at_price": "29.99",
                "price": "19.99",
                "sku": "SS1234-BL-M",
                "barcode": "123456789013",
                "note": "Best-selling",
                "inventory_quantity": 200,
                "weight": "0.60",
                "weight_unit": "kg",
                "cost_price": "13.99",
                "wholesale_price": [
                    {
                        "price": "19.99",
                        "min_quantity": 1
                    }
                ],
                "extend": null
            }
        ],
        "category": null
    }
}

Error Response Example

{
  "errors": [
    "Title is required"
  ]
}

{
  "error": "store is not active"
}

Error Details

ErrorCode	Description	Possible Reasons	Example Response
400	Bad Request	Incorrect domain name
401	UnauthorizedError	Missing StoreID
422	Unprocessable Entity	Provided token is malformed or missing required sections	{ "errors": [ "idempotent parameter mismatch" ]}
422	Unprocessable Entity	Non-UUID string passed as unique_token.	{ "error": ["unique token must be uuid format"]}
422	Unprocessable Entity	Missing required field input.	{"errors": ["Title is required" ]}
425	Too Early	- Another request with the same unique_token is still processing. - Client retries the same request too soon.	{ "error": ["Duplicate requests"] }
500	Internal State Error	1.Aborted 2.Unimplemented 3.Unauthenticated 4.DeadlineExceeded 5. Response message parsing error	{"error": ["failed to get unique token value"]}
500	No context	Missing Context	{ "error": ["no Context"] }

🔒Requires write_product access scope. For more access scope

Public Request Parameters

Public Response Parameters

Request Parameters

Body Parameters

Response Explanation

Successful Response

Error Response

Request Examples

Success Response Example

Error Response Example

Error Details

🔒
Requires `write_product` access scope. For more access scope