Product Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

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_manage
    • 

  • 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.


id
string
Custom product identifier. If not provided, it is automatically generated


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


 
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. 

  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. 

  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.
    4. 



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": {
    },
  • "metadata": {}
}
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_manage
    • 

  • 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.


id
string
Custom product identifier. If not provided, it is automatically generated


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


 
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. 

  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. 

  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.
    4. 



500
Internal Server Error.


post/{tenant}/products/bulk
Request samples 
application/json
[
  • {
    },
  • {
    },
  • {
    }
]
Response samples 
[
  • {
    },
  • {
    }
]
Upserting multiple products
Updates or creates products in a bulk. Response for a particular product is returned at the same position (index) at which it is located in the request body.




Required scopes


    

  • product.product_manage
    • 

  • 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
{}
Upserting a product
Updates or creates a specified product by replacing all of its existing data with data from the request body.
If the metadata.version is provided then optimistic locking is enabled and version must match the version in the database.




Required scopes


    

  • product.product_manage
    • 

  • 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 
201
The resource has been successfully created.


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. 

  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. 

  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.
    4. 



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": {
    },
  • "metadata": {}
}
Response samples 
application/json
{
  • "productId": "631b4bfe61f5e1663c745ffd",
  • "yrn": "urn:yaas:saasag:caasproduct:product:apistage;631b4bfe61f5e1663c745ffd"
}
Partially updating a product
Partially updates a specified product.




Required scopes


    

  • product.product_manage
    • 

  • 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. 

  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. 

  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.
    4. 



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_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.


 
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. 

  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. 

  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. 

  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.  "
    5. 



 
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. 

  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. 

  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.
    4. 



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": {
    }
}