Product Service Tutorials

How to add your first products

attention

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:

attention

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:

Adding your first product is a process made up of two main steps:

Defining sales tax rates.
Adding products.
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.

info

For more information, check out the Tax classes guide.

To define sales tax rates for a country, you need to send a request to the Creating a new tax configuration endpoint.

Add products

To add a single basic product, you need to send a request to the Creating a new product endpoint.

You can also add multiple basic products at the same time. To achieve that, you need to 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.

info

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 Creating an asset endpoint. For more information, check out the Media Management Tutorials.

How to create a bundle of personalized products

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.

info

To learn more about product bundles and templates, check out the Products guide.

To create personalized products and then group them in a bundle, perform the following steps:

Create a template for your product.
Create a product by using a product template.
Create a bundle of products.

Before you start

attention

The product.product_publish scope is only required if you want to publish the product on its creation.

Ensure that you have defined sales tax rates.

Create a product template

You can create a product template that contains additional attributes describing your product. To create a new product template, you need to call the Creating a new product template endpoint.

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.

info

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 How to create a parent product with variants tutorial.

info

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.

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, you need to call the Creating a new product endpoint.

In this example, we will create a bundle of the T-shirt product we created above, and join it with the socks product that already exists.

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.

attention

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.

info

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.

To create a single parent_variant type of product with variants, you need to send a request to the Creating a new product endpoint.

If you want to create multiple parent_variant products at the same time, send a request to the Creating multiple products endpoint.

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:

Update the product template with new variant attributes and values.
Update the parent variant product with the newly updated product template.

info

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.

attention

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.

info

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.

info

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.

info

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.

info

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.

attention

You cannot override the following attributes: id, code, template, variantAttributes.

Update a specific variant product by sending a request to the Upserting a product endpoint.

In the following example, we override the following fields:

published
taxClasses

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.

info

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:

Copy

Copied

[
  {
      "index": 0,
      "id": "65492420e492d916983c8431",
      "code": 204,
      "status": "NO_CONTENT"
  },
  {
      "index": 1,
      "id": "6549262ce492d916983c8432",
      "code": 204,
      "status": "NO_CONTENT"
  },
  {
      "index": 2,
      "id": "654926f4e492d916983c8433",
      "code": 204,
      "status": "NO_CONTENT"
  }
]

When something goes wrong, you might see some error message in the response. See some examples of error notifications you might encounter:

Copy

Copied

[
    {
        "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.

Copy

Copied

[
    {
        "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.

Copy

Copied

[
    {
        "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.