Product Tutorial
How to add your first products
This tutorial presents how to create a basic product. To learn more about types of products available in the Emporix Commerce Engine, check out the Products guide.
Take a look at the relationships between prices and other resources in the Emporix Commerce Engine:
Countries and regions are predefined in the Emporix API Country Service. You can check which countries and regions are available by sending requests to the following endpoints:
Creating your first product is a process made up of defining sales tax rates, adding the product and adding media files for a product.
Define sales tax rates
Sales tax rates are stored in tax configurations. Each configuration indicates a country and defines tax classes applicable to it.
You can manage your tax configurations through the Emporix API Tax Service.
For more information, check out the Tax classes guide.
To define sales tax rates for a country, send a request to the Creating a new tax configuration endpoint.
Add products
To add a single basic product, send a request to the Creating a new product endpoint.
Simple product example:
You can also add multiple basic products at the same time. To achieve that, send a request to the Creating multiple products endpoint.
Add media for a product
To add media files, for example images or videos, for a particular product, you can upload them directly to the Emporix database, or link to their location on an external website. In the following example, we are creating a public type of an asset that is linked to the product of our choice by sending a request to the Creating an asset endpoint with the media.asset_manage scope.
Sending a json/application request to the Creating an asset endpoint does not mean that the asset is uploaded to the database. It is only linked to the resource (category or product). If you want to upload the asset to the database, send a multipart request to the Creating an asset endpoint. For more information, check out the Media Management Tutorials.
How to create a basic product with a template
You can create a product template that contains additional attributes describing your product, and then create products using that template. Templates are optional but useful for organizing product attributes consistently across your catalog.
Create a product template
To create a new product template, call the Creating a new product template endpoint.
The id from the response is the product template ID that you can use when creating products.
When creating a product template for a basic product, do not set variantAttribute to true in the attribute metadata. Variant attributes are only for PARENT_VARIANT and VARIANT product types.
Create a product using a template
By applying a product template, you can create a product that contains additional attributes, which are included in the product's mixins.productTemplateAttributes field.
To create a new product by applying a product template to it, call the Creating a new product endpoint and provide the template's ID in the request body.
How to create a product bundle
With Emporix API, you can group together two or more products that already exist in the system so that they can be sold at one collective price. Product bundles do not require product templates or variant generation.
To learn more about product bundles, check out the Products guide.
To create a product bundle, perform the following steps:
Before you start, ensure you have defined the tax classes.
The products you want to bundle must already exist in the system.
The
product.product_publishscope is only required if you want to publish the product on its creation.
Create a bundle of products
You can group together two or more products that already exist in the system so that they can be sold at one collective price. To achieve that, call the Creating a new product endpoint.
In this example, we create a bundle containing a T-shirt product and socks product that already exist in the system.
The value of the productId from the response is the {{bundle_Id}}.
Required fields for bundles:
name: Product namecode: Unique product identifierbundledProducts: Array of products to include in the bundle (each withproductIdandamount)productType: Must be set to"BUNDLE"
Optional fields:
template: Product templates are optional for bundlesdescription: Product descriptiontaxClasses: Tax class configurationpublished: Publication statusmixins: Additional product attributes
How to create a parent variant product with variants
Variants are derivatives of the parent variant product. They contain the same attributes as their parent variant, but assume different attribute values.
The product.product_publish scope is only required if you want to publish the product on its creation.
Create a product template with variant attributes
Create a product template that defines the variant attributes (for example, color and size) and their allowed values. Set variantAttribute to true in the attribute metadata so they can be used for variant generation.
Call the Creating a new product template endpoint.
The id from the response is the product template ID. Use it as {{product_template_Id}} in the next step.
Create a parent variant product
Variants are created automatically whenever their parent variant product is created or updated. The combinations of variants are created based on the attributes defined in the product template applied to the parent variant, and the attributes and values specified in the variantAttributes field of the parent variant.
Before you start, ensure that the skipVariantGeneration parameter is set to false.
When creating or updating a product of the PARENT_VARIANT type, by default, product variants are generated. If you do not want to create product variants for the product, set the skipVariantGeneration parameter to true.
The product template can contain more attributes and values than are needed to create a parent variant. In the variantAttributes field, specify the attributes and values from the product template that are relevant to the particular parent variant product and its variants.
To create a single parent_variant type of product with variants, send a request to the Creating a new product endpoint.
Optional: Create multiple parent variant products
If you want to create multiple parent_variant products at the same time, send a request to the Creating multiple products endpoint.
To test the endpoint, open the API reference or check the example of a curl request.
How to create variants with new attributes and values
If you want to create variants by adding new variant attributes and/or values for a parent variant, perform the following steps.
You can add new attribute values either by adding them to the product template and then updating the product, or by updating the product with new values under variantAttributes, if they already exist in the product template.
The product.product_publish scope is only required if you want to publish the product on its creation.
Update a product template with new attributes and values
To add new variant attribute values to your product template, update the template by calling the Updating a product template endpoint. In this example, we add PURPLE to the existing color attribute values.
Each of the attributes has its own metadata element, where you can specify whether the attribute is mandatory, if it can be used as a variant attribute, and what its default value is.
Update the existing parent variant product with the new product template
Since updating the product template results in it being assigned a new version, update the parent variant by sending a request to the Partially updating a product endpoint and providing the new template.version value.
In the variantAttributes field, specify the attributes and attribute values that the variant products will assume. Based on the specified attributes, variant product combinations will be created automatically.
When creating or updating a product of the PARENT_VARIANT type, by default, product variants are generated. If you do not want to create product variants for the product, set the skipVariantGeneration parameter to true.
As a result, new product variants are created automatically, in combinations that include the newly specified attributes and values.
How to override variant attribute values
You may choose to update the basic fields of a particular variant, for example name, description, or relatedItems.
The product.product_publish and product.product_unpublish scopes are only required if you want to publish or unpublish the product on its update.
Updating a variant with new attribute values
By default, all variant products inherit their attributes from the parent variant. You need to include the name of the attribute in the metadata.overridden field to be able to replace the attribute values.
You cannot override the following attributes: id, code, template, variantAttributes.
The parentVariantId field cannot be updated. It can only be set when creating a new variant product. When updating an existing variant, this field should be omitted or will be ignored if included.
Update a specific variant product by sending a request to the Upserting a product endpoint.
In the following example, we override the following fields:
publishedtaxClasses
How to update multiple products in one operation
If you want to update multiple products, use the bulk update feature to update several products in one operation. Send a request to the Upserting multiple products endpoint.
The product.product_update scope is required. The product.product_publish and product.product_unpublish scopes are only required if you want to publish or unpublish the products on the update.
When the update request is sent successfully, the response for a particular product is returned at the same position (index) at which it is located in the request body. The expected response is as follows:
When something goes wrong, you might see some error message in the response. See some examples of error notifications you might encounter:
404: The first product was not found, check if you have provided the correct id.
409: The second product returns conflict, check if you have provided the correct product schema version.
404: The third product cannot be updated because the product template provided in the payload was not found, check if you have provided the correct data.
Related services:
Tax:
API ReferenceProduct:
API ReferenceMedia:
API ReferenceClassification
Classification categories allow you to organize products with consistent attributes across your catalog. By assigning products to classification categories, they automatically receive reusable attribute schemas that ensure data quality and consistency while reducing manual work.
Creating a product with classification mixins
To create a product with classification mixins, assign it first to a classification category and then update it with classification mixin attributes.
Assign your product to classification category
Assign the product to a classification category using the Assigning a resource to a category endpoint:
Update product with classification mixin attributes
Update the product with classification mixin attributes using the Partially updating a product endpoint. Use the mixinPath from the classification category's classificationMixins field:
When updating a product with classification mixins, you don't need to provide the schema URL in metadata.mixins for classification mixins. The system automatically populates these schema URLs based on the product's category assignments.
Product response with classification mixins
To retrieve a product that is assigned to a classification category, send a request to the Retrieving a product endpoint. The response includes the classificationMixins field in the metadata:
The response includes the classificationMixins field:
To learn about the end-to-end flow for implementing classification in your B2B commerce platform, along with the category service , see the Classification tutorial.
Last updated
Was this helpful?