Product Service

Download OpenAPI specification:Download

Manage structured product information.


Key Features:

  • Support for different product types - physical, digital, or services
  • Extensible / customizable product configuration
  • Attach media such as pictures, videos, manuals, etc.
  • Tax class configuration
  • Localization of production information (i18n), including language localization such as en_EN, en_US, de_DE, de_CH or de_AT

Key Benefits:

  • Create a rich, golden record of all product information to help customers to make a better-informed purchase decision
  • Correctly associated products with tax information depending on the market it is sold in => create tax reports faster and more accurately
  • Use rich media to present and demo products better online
  • Quickly create comparison charts
  • Use correct product attribute names rather than re-use existing names that may not mean the same or are just generic placeholders
  • Create localized content, such as a warning / legal information, different configuration (for example, supported power plugs), etc.
  • Fully internationalize product information without duplicating a product record

Products

Manage Products

Retrieving all of products

Retrieves a list of products.


Required scopes

  • product.product_read_unpublished Note: Only required if the response should contain unpublished products.
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
pageNumber
integer

The page number to be retrieved where the size of the pages must be specified by the pageSize parameter. The number of the first page is 1.

pageSize
integer
Default: 60

The number of documents being retrieved on the page.

sort
string

List of properties used to sort the results, separated by colons.

Possible values:

  • {fieldName}
  • {fieldName}:asc
  • {fieldName}:desc

Note: If you want to sort the results by localized properties, the possible values are:

  • {fieldName}.{language}
  • {fieldName}.{language}:asc
  • {fieldName}.{language}:desc

By default, the fields are sorted in ascending order.

q
string

A standard query parameter is used to search for specific values.

  • Searching for items by string-based properties:
    • By field value: q=name:apple_lobo, where name is the field name and apple_logo is its desired value.
    • By localized field value: q=name.en:apple_lobo, where name is the field name, en is a language code and apple_lobo is the field value expressed in the specified language. Note: This query works only for localized fields, which are stored in a Map format where key is a language code and value is translation to particular language.
  • Searching for items by number-based property:
    • With a specific value: q=mixins.productCustomAttributes.maxOrderQuantity:20
    • With a value greater than: q=mixins.productCustomAttributes.maxOrderQuantity:>20
    • With a value lower than: q=mixins.productCustomAttributes.maxOrderQuantity:<20
    • With a value greater than or equal to: q=mixins.productCustomAttributes.maxOrderQuantity:>=20
    • With a value lower than or equal to: q=mixins.productCustomAttributes.maxOrderQuantity:<=20
    • With a value within a range of values: q=mixins.productCustomAttributes.maxOrderQuantity:(>=10 AND <=20)
      where mixins.price.value is name of number-based field and 20 is it's querying value.
  • Searching for items by date-based property: All number-based property queries are valid also for dates. In that case the date should be placed within double quotes: q=metadataCreatedAt:(>="2021-05-18T07:27:27.455Z" AND <"2021-05-20T07:27:27.455Z")
  • Searching for items by boolean-based property: q=description.multiLanguage:true, where description.multiLanguage is the boolean field name and true is its desired value.
  • Searching for items with a nonexistent or null property: q=description.en:null, where description.en is the field that has its value set to null or when it does not exist in the database.
  • Searching for items with an existing property: q=mixin:exists, where mixin is the field that exists in the database.
  • Searching for items with an nonexistent property: q=mixin:missing, where mixin is the field that does not exist in the database.
  • Searching for items by multiple specific values: q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494), where id is the field name, and strings within the bracket are the desired values.
  • Searching for items by multiple fields: q=id:5c3325baa9812100098ff48f code:A705121667 where id and code are field names. All objects that contain the specified values are returned. Multiple fields (separated by space) can be specified. Multiple values for each field can also be specified in a format presented earlier.
  • Searching for items with string-based properties conforming to a regex: q=code:~ABCD12 or q=code:(~AB CD) - in case of searching for strings with space, where code is the name of field and ABCD12 or AB CD is its querying regex.
  • Searching for items with a localized string-based property conforming to a regex: name.localizedMap.en:~(Yoghurt im) - where name is the field name, localizedMap is a keyword which indicates that the field is a localized one, en is a desired language, and Joghurt im is a search term.
Example: q=name:{productName}
fields
string

Fields to be returned in the response.

When this parameter is passed, only the id, yrn and {fieldName} are retrieved for each product.

You can specify multiple fields by separating them with commas.

Example: fields=name,code
expand
string

Fields that should be expanded with additional information in the response body. Expressed as strings separated by commas.

Possible values:

  • template
  • parentVariant
rawValue
boolean

Flag indicating whether product variant(s) should include their parent variants' attribute values.

  • If set to true, the result will contain values from both the variant and its parent variant.
  • If set to false, the result will only contain variant values.
header Parameters
X-Total-Count
boolean

Flag indicating whether the total number of retrieved results should be returned.

Accept-Language
string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses
200

Resources have been retrieved successfully.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

500

Internal Server Error.

get/{tenant}/products
Request samples
Response samples
application/json
[]

Creating a new product

Creates a new product.


Required scopes

  • product.product_create
  • product.product_publish Note: Only required if you want to publish the product when creating it.
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
skipVariantGeneration
boolean
Default: false

The parameter is valid only for PARENT_VARIANT type. If true then variants are not automatically generated for the parent variant configuration.

doIndex
boolean
Default: true

Allows to control whether the change of the state should cause reindexing or not.

header Parameters
Content-Language
string

The Content-Language request HTTP header defines a language or multiple languages of the request body.

  • If the Content-Language header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the Content-Language header is set to a specific language, the localized fields should be provided as strings.
  • If the Content-Language header is empty, the endpoint will assume that the localized fields are provided in the default language or languages defined in the Configuration Service.

Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

Request Body schema: application/json
Any of:

Schema for creating products of the BASIC type.

required
string or object

Product name.

code
required
string non-empty

Unique product identifier, defined by the user.

string or object

Product description.

object (taxClasses)

Map of key-value pairs that associates tax classes with locations (countries). The key of the map should be specified as the existing location/country identifier (see the country-service). The value of the map entry should contain a tax class code (see the tax-service). Information about the association is required for price matching mechanism (see the price-service#MatchPrice).

published
boolean (published)
Default: false

Flag indicating whether the product has been published or not.

object (productMixins)

Mixins request.

Array of objects (relatedItem)

List of items in a relationship with the main product. Assuming that in the system the following relation types are defined: ACCESSORY and CONSUMABLE, the two products: Printer and Ink exist, then the Ink product can be used as a related item with type CONSUMABLE for the Printer product. In order to find all printers for which the ink is defined as a CONSUMABLE then q-param can be used: products?q=relatedItems.type:CONSUMABLE relatedItems.refId:Ink_Id

brandId
string

Id of brand.

labelIds
Array of strings

Collection of label ids.

object (productMetadataCore)

Metadata request.

object (template)

Indicates the template that has been used during the product creation. After assigning a template to the product, the new attributes can be defined under the productTemplateAttributes key in the mixins field. In case of variant attributes, the attributes should be defined under productVariantAttributes. The attributes are then validated in accordance with their definition in the template.

Note: The template with defined variant attributes can be used only in PARENT_VARIANT and VARIANT types of product.

productType
string (productType)
Default: "BASIC"

Indicates the product type, which is immutable. Once the product type is set, it cannot be updated.

Enum: "BASIC" "BUNDLE" "PARENT_VARIANT" "VARIANT"
Responses
201

The resource has been successfully created.

400

Resources cannot be created due to an error.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

409

There are three possible reasons:

  1. Product with given code already exists, please choose unique code for your product
  2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated product in the time user was performing his changes). User should retrieve the latest product data and retry the request.
  3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.
500

Internal Server Error.

post/{tenant}/products
Request samples
application/json
{
  • "name": "Smartphone Zony Yperia X2",
  • "code": "BASIC001",
  • "description": "The world's best camera and camcorder in a waterproof smartphone.",
  • "published": false,
  • "taxClasses": {
    },
  • "productType": "BASIC",
  • "template": {
    },
  • "relatedItems": [
    ],
  • "mixins": {
    },
}
Response samples
application/json
{
  • "productId": "631b4bfe61f5e1663c745ffd",
  • "yrn": "urn:yaas:saasag:caasproduct:product:apistage;631b4bfe61f5e1663c745ffd"
}

Creating multiple products

Creates products in a bulk. Response for a particular product will be returned at the same position (index) at which that price is located in the request body.

Required scopes

  • product.product_create
  • product.product_publish Note: Only required if you want to publish the product when creating it.
SecurityOAuth2
Request
path Parameters
tenant
required
string

Your Emporix tenant's name.Note: The tenant should always be written in lowercase.

query Parameters
skipVariantGeneration
boolean
Default: false

The parameter is valid only for PARENT_VARIANT type. If true then variants are not automatically generated for the parent variant configuration.

doIndex
boolean
Default: true

Allows to control whether the change of the state should cause reindexing or not.

header Parameters
Content-Language
string

The Content-Language request HTTP header defines a language or multiple languages of the request body.

  • If the Content-Language header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the Content-Language header is set to a specific language, the localized fields should be provided as strings.
  • If the Content-Language header is empty, the endpoint will assume that the localized fields are provided in the default language or languages defined in the Configuration Service.

Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

Request Body schema: application/json

A list of product create requests

Array
One of:

Schema for creating products of the BASIC type.

required
string or object

Product name.

code
required
string non-empty

Unique product identifier, defined by the user.

string or object

Product description.

object (taxClasses)

Map of key-value pairs that associates tax classes with locations (countries). The key of the map should be specified as the existing location/country identifier (see the country-service). The value of the map entry should contain a tax class code (see the tax-service). Information about the association is required for price matching mechanism (see the price-service#MatchPrice).

published
boolean (published)
Default: false

Flag indicating whether the product has been published or not.

object (productMixins)

Mixins request.

Array of objects (relatedItem)

List of items in a relationship with the main product. Assuming that in the system the following relation types are defined: ACCESSORY and CONSUMABLE, the two products: Printer and Ink exist, then the Ink product can be used as a related item with type CONSUMABLE for the Printer product. In order to find all printers for which the ink is defined as a CONSUMABLE then q-param can be used: products?q=relatedItems.type:CONSUMABLE relatedItems.refId:Ink_Id

brandId
string

Id of brand.

labelIds
Array of strings

Collection of label ids.

object (productMetadataCore)

Metadata request.

object (template)

Indicates the template that has been used during the product creation. After assigning a template to the product, the new attributes can be defined under the productTemplateAttributes key in the mixins field. In case of variant attributes, the attributes should be defined under productVariantAttributes. The attributes are then validated in accordance with their definition in the template.

Note: The template with defined variant attributes can be used only in PARENT_VARIANT and VARIANT types of product.

productType
string (productType)
Default: "BASIC"

Indicates the product type, which is immutable. Once the product type is set, it cannot be updated.

Enum: "BASIC" "BUNDLE" "PARENT_VARIANT" "VARIANT"
Responses
207

Example response

400

Resources cannot be created due to an error.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

There are three possible reasons:

  1. Product with given code already exists, please choose unique code for your product
  2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated product in the time user was performing his changes). User should retrieve the latest product data and retry the request.
  3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.
500

Internal Server Error.

post/{tenant}/products/bulk
Request samples
application/json
[
  • {
    },
  • {
    },
  • {
    }
]
Response samples
[
  • {
    },
  • {
    }
]

Updating multiple products

Updates products in a bulk. Response for a particular product will be returned at the same position (index) at which it is located in the request body.


Required scopes

  • product.product_update
  • product.product_publish Note: Only required if you want to publish the product when updating it.
  • product.product_unpublish Note: Only required if you want to unpublish the product when updating it.
SecurityOAuth2
Request
path Parameters
tenant
required
string

Your Emporix tenant's name.Note: The tenant should always be written in lowercase.

query Parameters
skipVariantGeneration
boolean
Default: false

The parameter is valid only for PARENT_VARIANT type. If true then variants are not automatically generated for the parent variant configuration.

doIndex
boolean
Default: true

Allows to control whether the change of the state should cause reindexing or not.

header Parameters
Content-Language
string

The Content-Language request HTTP header defines a language or multiple languages of the request body.

  • If the Content-Language header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the Content-Language header is set to a specific language, the localized fields should be provided as strings.
  • If the Content-Language header is empty, the endpoint will assume that the localized fields are provided in the default language or languages defined in the Configuration Service.

Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

Request Body schema: application/json

A list of product update requests

Array
One of:

Schema for updating products of the BASIC type in bulk.

id
required
string (id)

Unique resource identifier.

required
string or object

Product name.

code
required
string non-empty

Unique product identifier, defined by the user.

string or object

Product description.

object (taxClasses)

Map of key-value pairs that associates tax classes with locations (countries). The key of the map should be specified as the existing location/country identifier (see the country-service). The value of the map entry should contain a tax class code (see the tax-service). Information about the association is required for price matching mechanism (see the price-service#MatchPrice).

published
boolean (published)
Default: false

Flag indicating whether the product has been published or not.

object (productMixins)

Mixins request.

Array of objects (relatedItem)

List of items in a relationship with the main product. Assuming that in the system the following relation types are defined: ACCESSORY and CONSUMABLE, the two products: Printer and Ink exist, then the Ink product can be used as a related item with type CONSUMABLE for the Printer product. In order to find all printers for which the ink is defined as a CONSUMABLE then q-param can be used: products?q=relatedItems.type:CONSUMABLE relatedItems.refId:Ink_Id

brandId
string

Id of brand.

labelIds
Array of strings

Collection of label ids.

object (productMetadataWithVersion)

Metadata request.

object (template)

Indicates the template that has been used during the product creation. After assigning a template to the product, the new attributes can be defined under the productTemplateAttributes key in the mixins field. In case of variant attributes, the attributes should be defined under productVariantAttributes. The attributes are then validated in accordance with their definition in the template.

Note: The template with defined variant attributes can be used only in PARENT_VARIANT and VARIANT types of product.

Responses
207

Example response

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

500

Internal Server Error.

put/{tenant}/products/bulk
Request samples
application/json
[
  • {
    },
  • {
    },
  • {
    }
]
Response samples
application/json
[
  • {
    },
  • {
    }
]

Retrieving a product

Retrieves a specified product's details.


Required scopes

  • product.product_read_unpublished Note: Only required if the product has not been published.
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

productId
required
string

Product’s unique identifier generated when the product is created.

query Parameters
fields
string

Fields to be returned in the response.

When this parameter is passed, only the id, yrn and {fieldName} are retrieved for each product.

You can specify multiple fields by separating them with commas.

Example: fields=name,code
expand
string

Fields that should be expanded with additional information in the response body. Expressed as strings separated by commas.

Possible values:

  • template
  • parentVariant
rawValue
boolean

Flag indicating whether product variant(s) should include their parent variants' attribute values.

  • If set to true, the result will contain values from both the variant and its parent variant.
  • If set to false, the result will only contain variant values.
header Parameters
Accept-Language
string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses
200

Product successfully retrieved.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

Resource has not been found.

500

Internal Server Error.

get/{tenant}/products/{productId}
Request samples
Response samples
application/json
{}

Updating a product

Updates a specified product by replacing all of its existing data with data from the request body.


Required scopes

  • product.product_update
  • product.product_publish Note: Only required if you want to publish the product when updating it.
  • product.product_unpublish Note: Only required if you want to unpublish the product when updating it.
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

productId
required
string

Product’s unique identifier generated when the product is created.

query Parameters
partial
boolean
Default: false
Option Description
true A partial product update will be performed.
false A full product replacement will be performed.
skipVariantGeneration
boolean
Default: false

The parameter is valid only for PARENT_VARIANT type. If true then variants are not automatically generated for the parent variant configuration.

doIndex
boolean
Default: true

Allows to control whether the change of the state should cause reindexing or not.

header Parameters
Content-Language
string

The Content-Language request HTTP header defines a language or multiple languages of the request body.

  • If the Content-Language header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the Content-Language header is set to a specific language, the localized fields should be provided as strings.
  • If the Content-Language header is empty, the endpoint will assume that the localized fields are provided in the default language or languages defined in the Configuration Service.

Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

Request Body schema: application/json
One of:

Schema for updating products of the BASIC type.

required
string or object

Product name.

code
required
string non-empty

Unique product identifier, defined by the user.

string or object

Product description.

object (taxClasses)

Map of key-value pairs that associates tax classes with locations (countries). The key of the map should be specified as the existing location/country identifier (see the country-service). The value of the map entry should contain a tax class code (see the tax-service). Information about the association is required for price matching mechanism (see the price-service#MatchPrice).

published
boolean (published)
Default: false

Flag indicating whether the product has been published or not.

object (productMixins)

Mixins request.

Array of objects (relatedItem)

List of items in a relationship with the main product. Assuming that in the system the following relation types are defined: ACCESSORY and CONSUMABLE, the two products: Printer and Ink exist, then the Ink product can be used as a related item with type CONSUMABLE for the Printer product. In order to find all printers for which the ink is defined as a CONSUMABLE then q-param can be used: products?q=relatedItems.type:CONSUMABLE relatedItems.refId:Ink_Id

brandId
string

Id of brand.

labelIds
Array of strings

Collection of label ids.

object (productMetadataWithVersion)

Metadata request.

object (template)

Indicates the template that has been used during the product creation. After assigning a template to the product, the new attributes can be defined under the productTemplateAttributes key in the mixins field. In case of variant attributes, the attributes should be defined under productVariantAttributes. The attributes are then validated in accordance with their definition in the template.

Note: The template with defined variant attributes can be used only in PARENT_VARIANT and VARIANT types of product.

Responses
204

The resource has been successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

Resource has not been found.

409

There are three possible reasons:

  1. Product with given code already exists, please choose unique code for your product
  2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated product in the time user was performing his changes). User should retrieve the latest product data and retry the request.
  3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.
500

Internal Server Error.

put/{tenant}/products/{productId}
Request samples
application/json
{
  • "name": "Smartphone Zony Yperia X2",
  • "code": "TESTDOC000",
  • "description": "The world's best camera and camcorder in a waterproof smartphone.",
  • "published": false,
  • "taxClasses": {
    },
  • "template": {
    },
  • "relatedItems": [
    ],
  • "mixins": {
    },
}
Response samples
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Validation problem with request body."
}

Partially updating a product

Partially updates a specified product.


Required scopes

  • product.product_update
  • product.product_publish Note: Only required if you want to publish the product when updating it.
  • product.product_unpublish Note: Only required if you want to unpublish the product when updating it.
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

productId
required
string

Product’s unique identifier generated when the product is created.

query Parameters
skipVariantGeneration
boolean
Default: false

The parameter is valid only for PARENT_VARIANT type. If true then variants are not automatically generated for the parent variant configuration.

doIndex
boolean
Default: true

Allows to control whether the change of the state should cause reindexing or not.

header Parameters
Content-Language
string

The Content-Language request HTTP header defines a language or multiple languages of the request body.

  • If the Content-Language header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the Content-Language header is set to a specific language, the localized fields should be provided as strings.
  • If the Content-Language header is empty, the endpoint will assume that the localized fields are provided in the default language or languages defined in the Configuration Service.

Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

Request Body schema: application/json
string or object

Product name.

code
string non-empty

Unique product identifier, defined by the user.

string or object

Product description.

object (taxClasses)

Map of key-value pairs that associates tax classes with locations (countries). The key of the map should be specified as the existing location/country identifier (see the country-service). The value of the map entry should contain a tax class code (see the tax-service). Information about the association is required for price matching mechanism (see the price-service#MatchPrice).

published
boolean (published)
Default: false

Flag indicating whether the product has been published or not.

object (productMixins)

Mixins request.

Array of objects (relatedItem)

List of items in a relationship with the main product. Assuming that in the system the following relation types are defined: ACCESSORY and CONSUMABLE, the two products: Printer and Ink exist, then the Ink product can be used as a related item with type CONSUMABLE for the Printer product. In order to find all printers for which the ink is defined as a CONSUMABLE then q-param can be used: products?q=relatedItems.type:CONSUMABLE relatedItems.refId:Ink_Id

brandId
string

Id of brand.

labelIds
Array of strings

Collection of label ids.

object (template)

Indicates the template that has been used during the product creation. After assigning a template to the product, the new attributes can be defined under the productTemplateAttributes key in the mixins field. In case of variant attributes, the attributes should be defined under productVariantAttributes. The attributes are then validated in accordance with their definition in the template.

Note: The template with defined variant attributes can be used only in PARENT_VARIANT and VARIANT types of product.

Array of objects (bundledProducts)

List of bundled products

object (variantAttributes)

This field contains all information about attributes and their values that are used for creating variants. It is presented in the form of a map, where 'key' is the name of the attribute and 'value' is the list of values of that attribute. The attributes and their values are based on their definitions in the template element assigned to the parent variant. Each attribute defined in the product template is flagged as a variantAttribute. Only the attributes that have this flag set as true can be used in the variantAttributes field.

object (productMetadataWithVersion)

Metadata with the version information.

Responses
204

The resource has been successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

The requested resource does not exist.

409

There are three possible reasons:

  1. Product with given code already exists, please choose unique code for your product
  2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated product in the time user was performing his changes). User should retrieve the latest product data and retry the request.
  3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.
500

Internal Server Error.

patch/{tenant}/products/{productId}
Request samples
application/json
{
  • "published": true
}
Response samples
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Validation problem with request body."
}

Deleting a product

Deletes a specified product.


Required scopes

  • product.product_delete
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

productId
required
string

Product’s unique identifier generated when the product is created.

query Parameters
force
boolean
Default: false

Removing the PARENT_VARIANT product means that all corresponding products of the VARIANT type are removed as well. This operation has to be confirmed by setting the flag on the force element as true.

doIndex
boolean
Default: true

Allows to control whether the change of the state should cause reindexing or not.

Responses
204

The resource has been successfully deleted.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

500

Internal Server Error.

delete/{tenant}/products/{productId}
Request samples
Response samples
application/json
{
  • "fault": {
    }
}

Searching for products by YRNs

Searches for specified products by their YRNs.


Required scopes

  • product.product_read_unpublished Note: Only required if the response should contain unpublished products.
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
expand
string

Fields that should be expanded with additional information in the response body. Expressed as strings separated by commas.

Possible values:

  • template
fields
string

Fields to be returned in the response.

When this parameter is passed, only the id, yrn and {fieldName} are retrieved for each product.

You can specify multiple fields by separating them with commas.

Example: fields=name,code
header Parameters
Accept-Language
string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Request Body schema: application/json
yrns
required
Array of strings (YRN (attribute))

List of YRNs. Each YRN identifies a separate product.

object

Optional query parameters.

Responses
200

Search query result has been successfully retrieved.

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

500

Internal Server Error.

post/{tenant}/search
Request samples
application/json
{
  • "yrns": [
    ],
  • "params": {
    }
}
Response samples
application/json
[
  • {
    },
  • {
    }
]

Product Templates

Manage Product Templates

Retrieving all product templates

Retrieves all product templates. You can filter the results with query parameters.

A product template defines a set of attributes which are common for all product instances based on that template.


Required scopes

  • product.product_template_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
pageNumber
integer

The page number to be retrieved where the size of the pages must be specified by the pageSize parameter. The number of the first page is 1.

pageSize
integer
Default: 60

The number of documents being retrieved on the page.

sort
string

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. While sorting by a localised field the following rule is taken into account:

  1. If a localized field contains information about a language then the language should be used. For example name.en:ASC. In that case en language will be used for sorting the name property. The language suffix takes precedence over Accept-Language header.
  2. If a localized field does not contain information about language then Accept-Language header will be used. For example name:ASC and Accept-Language: de. In that case de will be used for sorting the name property
  3. If a localized field does not contain information about language and Accept-Language header contains * then default language from configuration service will be used as a language. For example name:ASC and Accept-Language: * and default language is pl then pl will be used as a language for name property
  4. If a localized field does not contains information about language and Accept-Language header does not exists in the request then default language from configuration service will be used. "
q
string

Standard query parameter used to search for specific values.

  • Searching for an item by string property: q=id:31065d5b-b62e, where id is the field name and 31065d5b-b62e is its required value.
  • Searching for an item by localized field property: q=name.en:T-s where name is the name of the field, en is a language code and T-s is a required value of this field. This query works only for localized fields, which are stored in a Map format where key is a language code and value is translation to particular language. + Searching for items by date property. All numer-based property queries are valid also for dates. In that case the date should be placed within double quotes: q=metadata.createdAt:(>="2021-05-18T07:27:27.455Z" AND <"2021-05-20T07:27:27.455Z") + Searching for items with non existing or empty property: q=name.en:null where name.en is a name of fields that has value null. + Searching for items with existing property: q=attributes:exists where attributes is a name of field that has non null value. + Searching for items by multiple specific values: q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494) where id is name of field and strings within a bracket are it''s required value. + Searching for items by multiple fields: q=id:5c3325baa9812100098ff48f name.en:T-s where id and ''name.en'' are the names of fields. All documents that contain given values of these fields are returned. Multiple fields separated by space can be specified. Multiple values for each field can be also specified in a format presented above. + Searching for items with string fields conforming to a regex: q=name.en:~ABCD12 or q=name.en:(~AB CD) - in case of searching for strings with space, where name is the name of field and ABCD12 or AB CD is it''s querying regex.'
header Parameters
X-Total-Count
boolean

Flag indicating whether the total number of retrieved results should be returned.

Accept-Language
string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses
200
400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

500

Internal Server Error.

get/{tenant}/product-templates
Request samples
Response samples
application/json
[]

Creating a new product template

Creates a new product template.

A product template defines a set of attributes which are common for all product instances based on that template.


Required scopes

  • product.product_template_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

header Parameters
Content-Language
string

The Content-Language request HTTP header defines a language or multiple languages of the request body.

  • If the Content-Language header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the Content-Language header is set to a specific language, the localized fields should be provided as strings.
  • If the Content-Language header is empty, the endpoint will assume that the localized fields are provided in the default language or languages defined in the Configuration Service.

Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

Request Body schema: application/json
required
object

Localized product template name in a form of a map of translations.

required
Array of objects (productTemplateAttribute)

List of attributes related to the product template.

id
string

Identifier of the product template.

Responses
201
400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

500

Internal Server Error.

post/{tenant}/product-templates
Request samples
application/json
{
  • "id": "545b4e3dfaee4c10def3db24",
  • "name": {
    },
  • "attributes": [
    ]
}
Response samples
application/json
{
  • "id": "624c3e7c3406122baacc7e93"
}

Retrieving a product template

Retrieves a specified product template's details.

A product template defines a set of attributes which are common for all product instances based on that template.


Required scopes

  • product.product_template_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

product-template-id
required
string

Unique identifier of the product template.

query Parameters
version
string

Version of the product template. If the parameter is not provided, the latest version of product template is returned.

header Parameters
Accept-Language
string

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If empty, the default system language is assumed. It can be a priority list working as a fallback mechanism.

Responses
200
401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

Resource has not been found.

500

Internal Server Error.

get/{tenant}/product-templates/{product-template-id}
Request samples
Response samples
application/json
{}

Updating a product template

Updates a specified product template by replacing all of its existing data with data from the request body.

Note: Every product template update creates a new version of the template. Products based on previous versions are not automatically updated. In order to see the changes (for example new attributes) on the product level, you need to update the template version in applicable products.


Required scopes

  • product.product_template_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

product-template-id
required
string

Unique identifier of the product template.

header Parameters
Content-Language
string

The Content-Language request HTTP header defines a language or multiple languages of the request body.

  • If the Content-Language header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the Content-Language header is set to a specific language, the localized fields should be provided as strings.
  • If the Content-Language header is empty, the endpoint will assume that the localized fields are provided in the default language or languages defined in the Configuration Service.

Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

Request Body schema: application/json
required
object

Localized product template name in a form of a map of translations.

required
Array of objects (productTemplateAttribute)

List of attributes related to the product template.

required
object
Responses
204

No Content

400

Bad request due to validation, incorrect parameters, etc.

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

404

Resource has not been found.

409

There are three possible reasons:

  1. Product with given code already exists, please choose unique code for your product
  2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated product in the time user was performing his changes). User should retrieve the latest product data and retry the request.
  3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.
500

Internal Server Error.

put/{tenant}/product-templates/{product-template-id}
Request samples
application/json
{
  • "name": {
    },
  • "attributes": [
    ],
  • "metadata": {
    }
}
Response samples
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Validation problem with request body."
}

Deleting a product template

Deletes a specified product template. Only product templates which are not used in products and parent variants can be deleted.


Required scopes

  • product.product_template_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

product-template-id
required
string

Unique identifier of the product template.

Responses
204

No Content

401

Unauthorized

403

Access forbidden. The caller is not allowed to access this resource.

500

Internal Server Error.

delete/{tenant}/product-templates/{product-template-id}
Request samples
Response samples
application/json
{
  • "fault": {
    }
}