Products

Manage Products

Searching for products

post

Search a list of products.

---

Required scopes

• product.product_read_unpublished Note: Only required if the response should contain unpublished products.

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

pageNumberintegerOptional

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.

pageSizeintegerOptional

The number of documents being retrieved on the page.

Default: 60

sortstringOptional

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.

fieldsstringOptional

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: name,code

expandstringOptional

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

Possible values:

• template
• parentVariant

rawValuebooleanOptional

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-CountbooleanOptional

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

Accept-LanguagestringOptional

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.

Body

qstringOptional

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

See: Standard practises - Query parameter

Responses

200

Resources have been retrieved successfully.

application/json

Responseone of

all of[]Optional

List of products of the BASIC type.

and

and

and

and

anyOptional

and

or

all of[]Optional

List of products of the BUNDLE type.

and

and

and

and

anyOptional

and

or

all of[]Optional

List of products of the PARENT_VARIANT type.

and

and

and

and

anyOptional

and

or

all of[]Optional

List of products of the VARIANT type.

and

and

and

and

anyOptional

and

401

Unauthorized

application/json

403

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

application/json

500

Internal Server Error.

application/json

post

HTTPcURLJavaScriptPython

POST /product/{tenant}/products/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "q": "code:(A705197727 OR A705197726)"
}

[
  {
    "id": "545b4e3dfaee4c10def3db24",
    "yrn": "urn:yaas:saasag:caasproduct:product:myshop;545b4e3dfaee4c10def3db24",
    "code": "SmartphoneZonyYperiaX21415269949943",
    "name": "Smartphone Zony Yperia X2",
    "description": "The world's best camera and camcorder in a waterproof smartphone.",
    "published": false,
    "template": {
      "id": "633d774f37937d425ce5570f",
      "version": 1
    },
    "taxClasses": {
      "EN": "STANDARD"
    },
    "productType": "BASIC",
    "relatedItems": [
      {
        "refId": "631c6adac2d4ea73be34f0d1",
        "type": "ACCESSORY"
      }
    ],
    "mixins": {
      "productCustomAttributes": {
        "pricingMeasurePrice": 13,
        "unitPricingMeasure": {
          "value": 133,
          "unitCode": "GRM"
        },
        "unitPricingBaseMeasure": {
          "value": 133,
          "unitCode": "GRM"
        },
        "pricingMeasure": {
          "value": 133,
          "unitCode": "GRM"
        },
        "orderUnit": "H87",
        "minOrderQuantity": 2,
        "maxOrderQuantity": 10,
        "defaultOrderQuantity": 2,
        "taxClass": "Vat_23"
      }
    },
    "metadata": {
      "version": 1,
      "createdAt": "2022-03-31T09:52:15.423Z",
      "modifiedAt": "2022-03-31T09:52:15.423Z",
      "schema": "https://res.cloudinary.com/saas-ag/raw/upload/v123456789/schemata/CAAS/product.v2",
      "mixins": {
        "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/CAAS/productCustomAttributesMixIn-v38.json",
        "productTemplateAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/tenant/633d774f37937d425ce5570f-templateAttributes_v1.json",
        "productVariantAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/tenant/633d774f37937d425ce5570f-variantAttributes_v1.json"
      }
    }
  }
]

Retrieving all of products

get

Retrieves a list of products.

---

Required scopes

• product.product_read_unpublished Note: Only required if the response should contain unpublished products.

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

pageNumberintegerOptional

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.

pageSizeintegerOptional

The number of documents being retrieved on the page.

Default: 60

sortstringOptional

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.

qstringOptional

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

See: Standard practises - Query parameter

Example: name:{productName}

fieldsstringOptional

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: name,code

expandstringOptional

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

Possible values:

• template
• parentVariant

rawValuebooleanOptional

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-CountbooleanOptional

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

Accept-LanguagestringOptional

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.

application/json

Responseone of

all of[]Optional

List of products of the BASIC type.

and

and

and

and

anyOptional

and

or

all of[]Optional

List of products of the BUNDLE type.

and

and

and

and

anyOptional

and

or

all of[]Optional

List of products of the PARENT_VARIANT type.

and

and

and

and

anyOptional

and

or

all of[]Optional

List of products of the VARIANT type.

and

and

and

and

anyOptional

and

401

Unauthorized

application/json

403

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

application/json

500

Internal Server Error.

application/json

get

HTTPcURLJavaScriptPython

GET /product/{tenant}/products HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "545b4e3dfaee4c10def3db24",
    "yrn": "urn:yaas:saasag:caasproduct:product:myshop;545b4e3dfaee4c10def3db24",
    "code": "SmartphoneZonyYperiaX21415269949943",
    "name": "Smartphone Zony Yperia X2",
    "description": "The world's best camera and camcorder in a waterproof smartphone.",
    "published": false,
    "template": {
      "id": "633d774f37937d425ce5570f",
      "version": 1
    },
    "taxClasses": {
      "EN": "STANDARD"
    },
    "productType": "BASIC",
    "relatedItems": [
      {
        "refId": "631c6adac2d4ea73be34f0d1",
        "type": "ACCESSORY"
      }
    ],
    "mixins": {
      "productCustomAttributes": {
        "pricingMeasurePrice": 13,
        "unitPricingMeasure": {
          "value": 133,
          "unitCode": "GRM"
        },
        "unitPricingBaseMeasure": {
          "value": 133,
          "unitCode": "GRM"
        },
        "pricingMeasure": {
          "value": 133,
          "unitCode": "GRM"
        },
        "orderUnit": "H87",
        "minOrderQuantity": 2,
        "maxOrderQuantity": 10,
        "defaultOrderQuantity": 2,
        "taxClass": "Vat_23"
      }
    },
    "metadata": {
      "version": 1,
      "createdAt": "2022-03-31T09:52:15.423Z",
      "modifiedAt": "2022-03-31T09:52:15.423Z",
      "schema": "https://res.cloudinary.com/saas-ag/raw/upload/v123456789/schemata/CAAS/product.v2",
      "mixins": {
        "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/CAAS/productCustomAttributesMixIn-v38.json",
        "productTemplateAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/tenant/633d774f37937d425ce5570f-templateAttributes_v1.json",
        "productVariantAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/tenant/633d774f37937d425ce5570f-variantAttributes_v1.json"
      }
    }
  }
]

Creating a new product

post

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.

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

skipVariantGenerationbooleanOptional

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

Default: false

doIndexbooleanOptional

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

Default: true

Header parameters

Content-LanguagestringOptional

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.

Body

any ofOptional

all ofOptional

Schema for creating products of the BASIC type.

and

and

and

anyOptional

or

all ofOptional

Schema for creating products of the BUNDLE type.

and

and

and

anyOptional

or

all ofOptional

Schema for creating products of the PARENT_VARIANT type.

and

and

and

anyOptional

or

all ofOptional

Schema for creating products of the VARIANT type.

and

and

and

anyOptional

Responses

201

The resource has been successfully created.

application/json

400

Resources cannot be created due to an error.

application/json

401

Unauthorized

application/json

403

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

application/json

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.

application/json

500

Internal Server Error.

application/json

post

HTTPcURLJavaScriptPython

POST /product/{tenant}/products HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1035

{
  "name": "Smartphone Zony Yperia X2",
  "code": "BASIC001",
  "description": "The world's best camera and camcorder in a waterproof smartphone.",
  "published": false,
  "taxClasses": {
    "EN": "STANDARD"
  },
  "productType": "BASIC",
  "template": {
    "id": "634cea2740033d7c2e7b03a8",
    "version": 1
  },
  "relatedItems": [
    {
      "refId": "634cea2740033d7c2e7b03a9",
      "type": "CONSUMABLE"
    }
  ],
  "mixins": {
    "salePricesData": [
      {
        "salePriceStart": "2021-07-20T22:00:00.000+0000",
        "salePriceAmount": 6.7,
        "salePriceEnd": "2021-07-25T21:59:59.000+0000",
        "enabled": false
      }
    ],
    "productCustomAttributes": {
      "pricingMeasurePrice": 13,
      "unitPricingMeasure": {
        "value": 133,
        "unitCode": "GRM"
      },
      "unitPricingBaseMeasure": {
        "value": 100,
        "unitCode": "GRM"
      },
      "pricingMeasure": {
        "value": 100,
        "unitCode": "GRM"
      },
      "orderUnit": "H87",
      "minOrderQuantity": 2,
      "maxOrderQuantity": 10,
      "defaultOrderQuantity": 5
    }
  },
  "metadata": {
    "mixins": {
      "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/productCustomAttributesMixIn.v29.json",
      "salePricesData": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/salePriceData.json"
    }
  }
}

BASIC Product CreationBUNDLE Product CreationPARENT VARIANT Product CreationVARIANT Product Creation

{
  "productId": "631b4bfe61f5e1663c745ffd",
  "yrn": "urn:yaas:saasag:caasproduct:product:apistage;631b4bfe61f5e1663c745ffd"
}

Creating multiple products

post

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.

Authorizations

Path parameters

tenantstringRequired

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

Query parameters

skipVariantGenerationbooleanOptional

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

Default: false

doIndexbooleanOptional

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

Default: true

Header parameters

Content-LanguagestringOptional

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.

Body

itemsone ofOptional

all ofOptional

Schema for creating products of the BASIC type.

and

and

and

anyOptional

or

all ofOptional

Schema for creating products of the BUNDLE type.

and

and

and

anyOptional

or

all ofOptional

Schema for creating products of the PARENT_VARIANT type.

and

and

and

anyOptional

or

all ofOptional

Schema for creating products of the VARIANT type.

and

and

and

anyOptional

Responses

207

Example response

application/jsonapplication/xml

400

Resources cannot be created due to an error.

application/json

401

Unauthorized

application/json

403

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

application/json

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.

application/json

500

Internal Server Error.

application/json

post

HTTPcURLJavaScriptPython

POST /product/{tenant}/products/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 241

[
  {
    "id": "abc-123",
    "code": "532432412331",
    "name": "Product 1",
    "productType": "BASIC"
  },
  {
    "id": "abc-124",
    "code": "532432412332",
    "name": "Product 2",
    "productType": "BASIC"
  },
  {
    "id": "abc-125",
    "code": "532432412333",
    "name": "Product 3",
    "productType": "BASIC"
  }
]

[
  {
    "index": 0,
    "id": "62d65a15088ed94ebf093d7d",
    "code": 201,
    "status": "CREATED"
  },
  {
    "index": 1,
    "id": "62d65a15088ed94ebf093d8d",
    "code": 201,
    "status": "CREATED"
  }
]

Upserting multiple products

put

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.

Authorizations

Path parameters

tenantstringRequired

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

Query parameters

skipVariantGenerationbooleanOptional

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

Default: false

doIndexbooleanOptional

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

Default: true

Header parameters

Content-LanguagestringOptional

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.

Body

itemsone ofOptional

all ofOptional

Schema for updating products of the BASIC type in bulk.

and

and

and

anyOptional

and

and

anyOptional

or

all ofOptional

Schema for updating products of the BUNDLE type in bulk.

and

and

and

anyOptional

and

and

anyOptional

or

all ofOptional

Schema for updating products of the PARENT_VARIANT type in bulk.

and

and

and

anyOptional

and

and

anyOptional

or

all ofOptional

Schema for updating products of the VARIANT type in bulk.

and

and

and

anyOptional

and

and

anyOptional

Responses

207

Example response

application/json

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

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

application/json

500

Internal Server Error.

application/json

put

HTTPcURLJavaScriptPython

PUT /product/{tenant}/products/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 250

[
  {
    "id": "abc-123",
    "code": "532432412331",
    "name": "Product 1",
    "metadata": {
      "version": 1
    }
  },
  {
    "id": "abc-124",
    "code": "532432412332",
    "name": "Product 2",
    "metadata": {
      "version": 1
    }
  },
  {
    "id": "abc-125",
    "code": "532432412333",
    "name": "Product 3",
    "metadata": {
      "version": 1
    }
  }
]

[
  {
    "index": 0,
    "id": "62d65a15088ed94ebf093d7d",
    "code": 204,
    "status": "NO_CONTENT"
  },
  {
    "index": 1,
    "id": "62d65a15088ed94ebf093d8d",
    "code": 204,
    "status": "NO_CONTENT"
  }
]

Retrieving a product

get

Retrieves a specified product's details.

---

Required scopes

• product.product_read_unpublished Note: Only required if the product has not been published.

Authorizations

Path parameters

productIdstringRequired

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

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

fieldsstringOptional

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: name,code

expandstringOptional

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

Possible values:

• template
• parentVariant

rawValuebooleanOptional

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-LanguagestringOptional

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.

application/json

Responseone of

all ofOptional

Schema for retrieving products of the BASIC type.

and

and

and

and

anyOptional

and

or

all ofOptional

Schema for retrieving products of the BUNDLE type.

and

and

and

and

anyOptional

and

or

all ofOptional

Schema for retrieving products of the PARENT_VARIANT type.

and

and

and

and

anyOptional

and

or

all ofOptional

Schema for retrieving products of the VARIANT type.

and

and

and

and

anyOptional

and

401

Unauthorized

application/json

403

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

application/json

404

Resource has not been found.

application/json

500

Internal Server Error.

application/json

get

HTTPcURLJavaScriptPython

GET /product/{tenant}/products/{productId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "545b4e3dfaee4c10def3db24",
  "yrn": "urn:yaas:saasag:caasproduct:product:myshop;545b4e3dfaee4c10def3db24",
  "code": "SmartphoneZonyYperiaX21415269949943",
  "name": "Smartphone Zony Yperia X2",
  "description": "The world's best camera and camcorder in a waterproof smartphone.",
  "published": false,
  "template": {
    "id": "633d774f37937d425ce5570f",
    "version": 1
  },
  "taxClasses": {
    "EN": "STANDARD"
  },
  "productType": "BASIC",
  "relatedItems": [
    {
      "refId": "631c6adac2d4ea73be34f0d1",
      "type": "ACCESSORY"
    }
  ],
  "mixins": {
    "productCustomAttributes": {
      "pricingMeasurePrice": 13,
      "unitPricingMeasure": {
        "value": 133,
        "unitCode": "GRM"
      },
      "unitPricingBaseMeasure": {
        "value": 133,
        "unitCode": "GRM"
      },
      "pricingMeasure": {
        "value": 133,
        "unitCode": "GRM"
      },
      "orderUnit": "H87",
      "minOrderQuantity": 2,
      "maxOrderQuantity": 10,
      "defaultOrderQuantity": 2,
      "taxClass": "Vat_23"
    }
  },
  "metadata": {
    "version": 1,
    "createdAt": "2022-03-31T09:52:15.423Z",
    "modifiedAt": "2022-03-31T09:52:15.423Z",
    "schema": "https://res.cloudinary.com/saas-ag/raw/upload/v123456789/schemata/CAAS/product.v2",
    "mixins": {
      "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/CAAS/productCustomAttributesMixIn-v38.json",
      "productTemplateAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/tenant/633d774f37937d425ce5570f-templateAttributes_v1.json",
      "productVariantAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/tenant/633d774f37937d425ce5570f-variantAttributes_v1.json"
    }
  }
}

Upserting a product

put

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.

Authorizations

Path parameters

productIdstringRequired

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

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

partialbooleanOptional

Option	Description
true	A partial product update will be performed.
false	A full product replacement will be performed.

Default: false

skipVariantGenerationbooleanOptional

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

Default: false

doIndexbooleanOptional

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

Default: true

Header parameters

Content-LanguagestringOptional

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.

Body

one ofOptional

all ofOptional

Schema for updating products of the BASIC type.

and

and

anyOptional

and

or

all ofOptional

Schema for updating products of the BUNDLE type.

and

and

anyOptional

and

or

all ofOptional

Schema for updating products of the PARENT_VARIANT type.

and

and

anyOptional

and

or

all ofOptional

Schema for updating products of the VARIANT type.

and

and

anyOptional

and

Responses

201

The resource has been successfully created.

application/json

204

The resource has been successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

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

application/json

404

Resource has not been found.

application/json

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.

application/json

500

Internal Server Error.

application/json

put

HTTPcURLJavaScriptPython

PUT /product/{tenant}/products/{productId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1027

{
  "name": "Smartphone Zony Yperia X2",
  "code": "TESTDOC000",
  "description": "The world's best camera and camcorder in a waterproof smartphone.",
  "published": false,
  "taxClasses": {
    "EN": "STANDARD"
  },
  "template": {
    "id": "634cea2740033d7c2e7b03a8",
    "version": 1
  },
  "relatedItems": [
    {
      "refId": "634cea2740033d7c2e7b03a9",
      "type": "CONSUMABLE"
    }
  ],
  "mixins": {
    "salePricesData": [
      {
        "salePriceStart": "2021-07-20T22:00:00.000+0000",
        "salePriceAmount": 6.7,
        "salePriceEnd": "2021-07-25T21:59:59.000+0000",
        "enabled": false
      }
    ],
    "productCustomAttributes": {
      "pricingMeasurePrice": 13,
      "unitPricingMeasure": {
        "value": 133,
        "unitCode": "GRM"
      },
      "unitPricingBaseMeasure": {
        "value": 100,
        "unitCode": "GRM"
      },
      "pricingMeasure": {
        "value": 100,
        "unitCode": "GRM"
      },
      "orderUnit": "H87",
      "minOrderQuantity": 2,
      "maxOrderQuantity": 10,
      "defaultOrderQuantity": 5
    }
  },
  "metadata": {
    "version": 1,
    "mixins": {
      "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/productCustomAttributesMixIn.v29.json",
      "salePricesData": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/salePriceData.json"
    }
  }
}

BASIC Product UpdateBUNDLE Product UpdatePARENT VARIANT Product UpdateVARIANT Product Update

{
  "productId": "631b4bfe61f5e1663c745ffd",
  "yrn": "urn:yaas:saasag:caasproduct:product:apistage;631b4bfe61f5e1663c745ffd"
}

Deleting a product

delete

Deletes a specified product.

---

Required scopes

• product.product_manage

Authorizations

Path parameters

productIdstringRequired

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

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

forcebooleanOptional

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.

Default: false

doIndexbooleanOptional

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

Default: true

Responses

204

The resource has been successfully deleted.

401

Unauthorized

application/json

403

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

application/json

500

Internal Server Error.

application/json

delete

HTTPcURLJavaScriptPython

DELETE /product/{tenant}/products/{productId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Partially updating a product

patch

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.

Authorizations

Path parameters

productIdstringRequired

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

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

skipVariantGenerationbooleanOptional

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

Default: false

doIndexbooleanOptional

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

Default: true

Header parameters

Content-LanguagestringOptional

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.

Body

all ofOptional

and

Responses

204

The resource has been successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

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

application/json

404

The requested resource does not exist.

application/json

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.

application/json

500

Internal Server Error.

application/json

patch

HTTPcURLJavaScriptPython

PATCH /product/{tenant}/products/{productId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "published": true
}

No content

Deprecated

Searching for products by YRNs

post

Searches for specified products by their YRNs.

This endpoint is deprecated. Please use the /product/{tenant}/products/search instead.

---

Required scopes

• product.product_read_unpublished Note: Only required if the response should contain unpublished products.

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

expandstringOptional

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

Possible values:

• template

fieldsstringOptional

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: name,code

Header parameters

Accept-LanguagestringOptional

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.

Body

yrnsstring[]Required

List of YRNs. Each YRN identifies a separate product.

Responses

200

Search query result has been successfully retrieved.

application/json

Responseone of

all of[]Optional

List of products of the BASIC type.

and

and

and

and

anyOptional

and

or

all of[]Optional

List of products of the BUNDLE type.

and

and

and

and

anyOptional

and

or

all of[]Optional

List of products of the PARENT_VARIANT type.

and

and

and

and

anyOptional

and

or

all of[]Optional

List of products of the VARIANT type.

and

and

and

and

anyOptional

and

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

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

application/json

500

Internal Server Error.

application/json

post

HTTPcURLJavaScriptPython

POST /product/{tenant}/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 377

{
  "yrns": [
    "urn:yaas:saasag:caasproduct:product:myshop;4474e3dfaee4c10def3d9b24",
    "urn:yaas:saasag:caasproduct:product:myshop;54cc453dfaee4c10def3db24",
    "urn:yaas:saasag:caasproduct:product:myshop;346764e3dfaee4c10defb477",
    "urn:yaas:saasag:caasproduct:product:myshop;5710b72dd2ef7d001d099fbf;57ad7bfae12690001d568a3f"
  ],
  "params": {
    "product": {
      "fields": [
        "name",
        "code",
        "description"
      ]
    }
  }
}

[
  {
    "id": "4474e3dfaee4c10def3d9b24",
    "yrn": "urn:yaas:saasag:caasproduct:product:myshop;54cc453dfaee4c10def3db24",
    "code": "code1",
    "name": "Product1",
    "description": "desc"
  },
  {
    "id": "5710b72dd2ef7d001d099fbf",
    "yrn": "urn:yaas:saasag:caasproduct:product:myshop;5710b72dd2ef7d001d099fbf",
    "code": "code2",
    "name": "Product2",
    "description": "desc2"
  }
]