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 .
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:
Retrieving all countries
Retrieving all regions
Adding your first product is a process made up of two main steps:
Define sales tax rates
Sales tax rates are stored in tax configurations. Each configuration indicates a country and defines tax classes applicable to it.
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.
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.
You can also personalize your products by using the Emporix-provided templates, or by creating your own ones. The values of the template's attributes are specified in the product's mixins.productTemplateAttributes field.
To create personalized products and then group them in a bundle, perform the following steps:
Before you start
The product.product_publish scope is only required if you want to publish the product on its creation.
The id from the response is further referred to as {{product_template_Id}}.
Create a product by using a product 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, you need to call the Creating a new product endpoint and provide the template's ID in the request body.
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 value of the productId from the response is the {{bundle_Id}}.
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 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, you need to specify the attributes and values from the product template that are relevant to the particular parent variant product and its variants.
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, you need to perform the following actions:
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 specify new attributes for your product's variants, you need to add them in the attributes field by calling the Updating a product template endpoint. Here, we've added a new key size to the list of available attributes.
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.
To specify new values for your product's attributes, you need to add them in the values field. Here, we've added PURPLE to the list of available attribute values.
Update the existing parent variant product with the new product template
Since updating the product template results in it being assigned a new version, you need to 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, you need to 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.overriden field to be able to replace the attribute values.
You cannot override the following attributes: id, code, template, variantAttributes.
In the following example, we override the following fields:
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:
[
{
"index": 0,
"id": "65492420e492d916983c8431",
"code": 404,
"status": "NOT_FOUND",
"message": "The product with id 65492420e492d916983c8431 has not been found."
}
]
404: The first product was not found, check if you have provided the correct id.
[
{
"index": 1,
"id": "6549262ce492d916983c8432",
"code": 409,
"status": "CONFLICT",
"message": "The resource that was requested for update has changed. Please retry your request with valid version."
}
]
409: The second product returns conflict, check if you have provided the correct product schema version.
[
{
"index": 2,
"id": "654926f4e492d916983c8433",
"code": 404,
"status": "NOT_FOUND",
"message": "Product template with id 634cea2740033d7c2e7b03a8 is not present in the database."
}
]
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.
.
.
.
You can manage your tax configurations through the Emporix API .
For more information, check out the .
To define sales tax rates for a country, you need to send a request to the endpoint.
To add a single basic product, you need to send a request to the endpoint.
You can also add multiple basic products at the same time. To achieve that, you need to send a request to the endpoint.
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, you need to send a multipart request to the endpoint.
For more information, check out the .
To learn more about product bundles and templates, check out the .
You can create a product template that contains additional attributes describing your product. To create a new product template, you need to call the endpoint.
In this example, we assign a template to a product on its creation. The created product can be a standalone one, or contain variants. Here, the product does not contain any variants. For creating a parent variant product with variants, check out the tutorial.
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, you need to call the endpoint.
To create a single parent_variant type of product with variants, you need to send a request to the endpoint.
If you want to create multiple parent_variant products at the same time, send a request to the endpoint.
Update a specific variant product by sending a request to the endpoint.
If you want to update multiple products, use the bulk update feature to update several products in one operation. Send a request to the products endpoint.
