Creates an item to be stored in a merchant's catalog.
This endpoint creates an item to be stored in a merchant's catalog. The item uses is_active, is_taxable, is_service or is_discount to denote whether the item is actively sold, taxable, a service or a discount, respectively.
You can create a product, service or discount item to be added to the catalog.
Duplicate Item Detection
The API prevents duplicate catalog items from being created within the same merchant. A duplicate is identified when all of the following fields match an existing, non-deleted item:
| Field | Matching Behavior |
|---|---|
item (name) | Case-insensitive comparison (e.g., "Widget" and "WIDGET" are considered the same) |
price | Exact match |
is_service | Exact match (defaults to false if omitted) |
is_discount | Exact match (defaults to false if omitted) |
If a duplicate is detected, the API returns a 422 response:
{
"item": ["This item already exists in your Catalog."]
}Items with the same name are allowed when the price or type (is_service/is_discount) differs. Items that have been deleted (soft-deleted) do not count as duplicates.
If the server is unable to process the request due to concurrent duplicate checks, a 429 response is returned:
{
"error": ["Unable to create this item right now. Please try again."]
}To create a product item
To create a product, is_discount and is_service would be set to false for a product.
| Variable | Description |
|---|---|
| item | Name of the item. |
| price | The price to set for the product or service. |
| category | You can choose a category for the item. |
| details | Details provide the description of the item. |
| code | This is the internal code for the item. |
| in_stock | The value that is on hand. |
| low_stock_alert | The value that will issue a low stock alert. |
| is_service | Set to False. |
| is_active | Set to True if this item is available to be used. |
| is_taxable | Sets if the item is taxable. True is taxable, while False would be tax-exempt. |
| is_discount | Set to False. |
| is_discountable | If True, the item price can be affected by a discount. |
| files | Add file IDs to be associated with the item. |
| thumbnail_id | Associates a file ID with a thumbnail image of the item. This can help identify the item in the UI. |
To create a service
To create a service, is_discount would be set to False and is_service would be set to True for a service.
| Variable | Description |
|---|---|
| item | Name of the item. |
| price | The price to set for the service. |
| category | You can choose a category for the item. |
| details | Details provide the description of the item. |
| code | This is the internal code for the item. |
| is_service | Set to true. |
| is_active | Set to True if this item is available to be used. |
| is_taxable | Sets if the item is taxable. True is taxable, while False would be tax-exempt. |
| is_discount | Set to False. |
| is_discountable | If True, the item price can be affected by a discount. |
| files | Add file IDs to be associated with the item. |
| thumbnail_id | Associates a file ID with a thumbnail image of the item. This can help identify the item in the UI. |
To create a discount item
To create a discount, is_discount is set to True for a discount.
| Variable | Description |
|---|---|
| item | Name of the item. |
| price | The amount to be discounted. If is_percentage is True, this value is a percentage; otherwise, it is a dollar amount. |
| category | You can choose a category for the item. |
| details | Details provide the description of the item. |
| code | This is the internal code for the item. |
| in_stock | The number of discounts available. |
| low_stock_alert | A warning is received when the stock reaches this level. |
| is_active | Set to True if this item is available to be used. |
| is_discount | Set to True to create a discount item. |
| is_percentage | Determines if the price variable is a dollar amount or a percentage. |
| files | Add file IDs to be associated with the item. |
| thumbnail_id | Associates a file ID with a thumbnail image of the item. This can help identify the item in the UI. |