Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Products

Manage products. Supported product types include:

  • BASIC — standalone products

  • BUNDLE — groups of products sold together

  • PARENT_VARIANT — products with automatically generated variants defined by a template

  • VARIANT — individual variants of a PARENT_VARIANT product

  • DYNAMIC_VARIANT — products forming a flexible variant hierarchy of up to 4 levels. Each variant stores its own ownVariantAttributes (the attributes that distinguish it from its parent). A root DYNAMIC_VARIANT product stores a denormalized flat map of all descendants in its variants field with accumulated attributes. Use the /recalculate endpoint to rebuild variant trees after bulk imports.

Searching for products

post

Search a list of products.

Additional scope information

  • The product.product_read_unpublished scope is only required if the response should contain unpublished products.

  • The product.product_read_by_vendor scope is only required to fetch products belonging to the vendor.

Required scopes
This endpoint requires the following scopes:
  • : Needed to retrieve unpublished products.
  • : The scope allows vendor to read products with assigned vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant 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. You can combine multiple values, for example expand=template,parentVariant,brand,labels.

Possible values:

  • template
  • parentVariant
  • brand
  • labels
rawValuebooleanOptional

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

  • If set to true, the result contains values from both the variant and its parent variant.
  • If set to false, the result contains only 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
or
or
or
or
post/product/{tenant}/products/search
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": "SmartphoneX21415269949943",
    "name": "Smartphone 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"
      }
    ],
    "customerSegmentIds": [
      "689591c74ac99162678ae78f",
      "689591c74ac99162678ae78g"
    ],
    "categoryIds": [
      "631c6adac2d4ea73be34f0d4",
      "631c6adac2d4ea73be34f0d5"
    ],
    "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/emporix-docs/product.v2",
      "mixins": {
        "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json",
        "productTemplateAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/633d774f37937d425ce5570f_templateAttributes_v1.json",
        "productVariantAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/633d774f37937d425ce5570f_variantAttributes_v1.json"
      }
    }
  }
]

Retrieving all products

get

Retrieves a list of products.

Additional scope information

  • The product.product_read_unpublished scope is only required if the response should contain unpublished products.

  • The product.product_read_by_vendor scope is only required to fetch products belonging to the vendor.

  • The product.product_manage_by_vendor scope is only required to manage products belonging to the vendor.

Required scopes
This endpoint requires the following scopes:
  • : Needed to retrieve unpublished products.
  • : The scope allows vendor to read products with assigned vendor.
  • : The scope allows vendor to manage products with assigned vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant 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. You can combine multiple values, for example expand=template,parentVariant,brand,labels.

Possible values:

  • template
  • parentVariant
  • brand
  • labels
rawValuebooleanOptional

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

  • If set to true, the result contains values from both the variant and its parent variant.
  • If set to false, the result contains only 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
or
or
or
or
get/product/{tenant}/products
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": "SmartphoneX21415269949943",
    "name": "Smartphone 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"
      }
    ],
    "customerSegmentIds": [
      "689591c74ac99162678ae78f",
      "689591c74ac99162678ae78g"
    ],
    "categoryIds": [
      "631c6adac2d4ea73be34f0d4",
      "631c6adac2d4ea73be34f0d5"
    ],
    "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/emporix-docs/product.v2",
      "mixins": {
        "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json",
        "productTemplateAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/633d774f37937d425ce5570f_templateAttributes_v1.json",
        "productVariantAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/633d774f37937d425ce5570f_variantAttributes_v1.json"
      }
    }
  }
]

Creating a new product

post

Creates a new product.

Additional scope information

  • The product.product_manage_by_vendor scope is only required for vendor employeesto manage products belonging to the vendor.

  • The product.product_publish scope is only required if you want to publish the product when creating it.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage products.
  • : Needed to publish products.
  • : The scope allows vendor to manage products with assigned vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant 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
skipRelatedItemsValidationbooleanOptional

If set to true, the validation that checks whether related products exist is skipped. This is useful during data loading, where related products may not yet exist and will be created later. This parameter is only respected when the allowToSkipRelatedProductsValidation system setting is set to true. Otherwise, it is disregarded.

Default: false
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 interprets the localized fields as being provided in the default language or the 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 is rejected.

Body
or
or
or
or
Responses
201

The resource has been successfully created.

application/json
idstringOptional
yrnstringOptional

In YaaS, a global resource identifier is a Uniform Resource Name (URN) with a custom YaaS schema and is called a YaaS Resource Name, or YRN.

It is a unique identifier, which stores information about a resource, such as its type, ID or name of the tenant.

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

{
  "name": "Smartphone X2",
  "code": "BASIC001",
  "description": "The world best camera and camcorder in a waterproof smartphone.",
  "published": false,
  "taxClasses": {
    "EN": "STANDARD"
  },
  "productType": "BASIC"
}
{
  "id": "631b4bfe61f5e1663c745ffd",
  "yrn": "urn:yaas:saasag:caasproduct:product:apistage;631b4bfe61f5e1663c745ffd"
}

Creating multiple products

post

Creates products in a bulk. The maximum batch size is 200.

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

Additional scope information

  • The product.product_manage_by_vendor scope is only required for vendor employees to manage products belonging to the vendor.

  • The product.product_publish scope is only required if you want to publish the product when creating it.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage products.
  • : Needed to publish products.
  • : The scope allows vendor to manage products with assigned vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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
skipRelatedItemsValidationbooleanOptional

If set to true, the validation that checks whether related products exist is skipped. This is useful during data loading, where related products may not yet exist and will be created later. This parameter is only respected when the allowToSkipRelatedProductsValidation system setting is set to true. Otherwise, it is disregarded.

Default: false
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 interprets the localized fields as being provided in the default language or the 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 is rejected.

Bodyone of[]
or
or
or
or
Responses
207

Example response

indexintegerOptional

Index of the processed product, matching the price position in request body.

idstringOptional

Product unique identifier.

codeintegerOptional

HTTP Status Code.

errorCodestringOptional

Error specific errorCode.

statusstringOptional

HTTP Status description.

messagestringOptional

Error message.

detailsstring[]Optional

Error message details.

post/product/{tenant}/products/bulk
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. The maximum batch size is 200.

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

Additional scope information

  • The product.product_manage_by_vendor scope is only required for vendor employees to manage products belonging to the vendor.

  • The product.product_publish scope is only required if you want to publish the product when updating it.

  • The product.product_unpublish scope is only required if you want to unpublish the product when updating it.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage products.
  • : Needed to publish products.
  • : Needed to unpublish products.
  • : The scope allows vendor to manage products with assigned vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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
skipRelatedItemsValidationbooleanOptional

If set to true, the validation that checks whether related products exist is skipped. This is useful during data loading, where related products may not yet exist and will be created later. This parameter is only respected when the allowToSkipRelatedProductsValidation system setting is set to true. Otherwise, it is disregarded.

Default: false
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 interprets the localized fields as being provided in the default language or the 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 is rejected.

Bodyone of[]
or
or
or
or
Responses
207

Example response

application/json
indexintegerOptional

Index of the processed product, matching the price position in request body.

idstringOptional

Product unique identifier.

codeintegerOptional

HTTP Status Code.

errorCodestringOptional

Error specific errorCode.

statusstringOptional

HTTP Status description.

messagestringOptional

Error message.

detailsstring[]Optional

Error message details.

put/product/{tenant}/products/bulk
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"
  }
]

Triggering dynamic variant recalculation

post

Triggers asynchronous recalculation of the variant tree for one or more DYNAMIC_VARIANT products. Accepts up to 1000 product IDs at any hierarchy level — the system automatically resolves the root for each ID and creates one recalculation job per unique root product.

This endpoint is intended to be called after a batch of products has been fully ingested, not per individual product write. For single product writes, the variant tree is updated synchronously inline.

If a recalculation job for a given root is already PENDING or PROCESSING, the corresponding IDs are returned in skippedProductIds and the existing job is referenced in the jobs list.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage products.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

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

Request body for triggering dynamic variant recalculation. Accepts up to 1000 product IDs at any level of the hierarchy — the system resolves the root for each ID automatically. Intended to be called after a batch of products has been fully ingested, not per individual product write.

productIdsstring[] · min: 1 · max: 1000Required

List of product IDs (variants at any hierarchy level) for which recalculation should be triggered. The system groups IDs by their root product and creates one job per unique root.

Responses
202

Recalculation jobs accepted. One job is created per unique root product resolved from the submitted IDs.

application/json

Response returned when recalculation is triggered. Contains one job per unique root product resolved from the submitted IDs, plus any IDs that were skipped (for example, because a job for that root is already PENDING or PROCESSING).

skippedProductIdsstring[]Optional

Product IDs that were not processed because a recalculation job for their root is already active (PENDING or PROCESSING). The existing job ID is available in the jobs list.

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

{
  "productIds": [
    "mobile-15-pro-l1",
    "mobile-15-pro-l2-retail",
    "mobile-16-pro-l1"
  ]
}
{
  "jobs": [
    {
      "id": "job-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "parentRoot": "mobile-15-pro",
      "requestedByIds": [
        "mobile-15-pro-l1",
        "mobile-15-pro-l2-retail"
      ],
      "status": "PENDING",
      "createdAt": "2024-01-15T10:10:00.000Z",
      "processingStartedAt": null,
      "finishedAt": null,
      "error": null,
      "attempts": 0
    },
    {
      "id": "job-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "parentRoot": "mobile-16-pro",
      "requestedByIds": [
        "mobile-16-pro-l1"
      ],
      "status": "PENDING",
      "createdAt": "2024-01-15T10:10:00.000Z",
      "processingStartedAt": null,
      "finishedAt": null,
      "error": null,
      "attempts": 0
    }
  ],
  "skippedProductIds": []
}

Listing recalculation jobs

get

Retrieves a list of dynamic variant recalculation jobs for the tenant. Optionally filtered by job status.

Jobs are retained for approximately 30 days after reaching a terminal state (FINISHED, FAILED, or FAILED_PERMANENT) and are then automatically removed by a TTL index.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage products.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
statusstring · enumOptional

Current status of a dynamic variant recalculation job.

Possible values:
Responses
200

Jobs retrieved successfully.

application/json

Represents a single dynamic variant recalculation job. One job is created per unique root product. Jobs remain queryable until automatically removed approximately 30 days after reaching a terminal state.

idstringOptional

Unique identifier of the recalculation job.

parentRootstringOptional

Identifier of the root product whose variant tree is being recalculated.

requestedByIdsstring[]Optional

List of product IDs that were submitted in the recalculation request and resolved to this root.

statusstring · enumOptional

Current status of a dynamic variant recalculation job.

Possible values:
createdAtstring · date-timeOptional

Timestamp when the job was created.

processingStartedAtstring · date-timeOptional

Timestamp when a subscriber picked up the job and started processing. Null while the job is still PENDING.

finishedAtstring · date-timeOptional

Timestamp when the job reached a terminal state (FINISHED, FAILED, or FAILED_PERMANENT).

errorstringOptional

Error message if the job failed. Null for successful jobs.

attemptsintegerOptional

Number of processing attempts made for this job. Incremented on each delivery from the pub/sub subscription.

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

[
  {
    "id": "job-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "parentRoot": "mobile-15-pro",
    "requestedByIds": [
      "mobile-15-pro-l1",
      "mobile-15-pro-l2-retail"
    ],
    "status": "FINISHED",
    "createdAt": "2024-01-15T10:10:00.000Z",
    "processingStartedAt": "2024-01-15T10:10:03.000Z",
    "finishedAt": "2024-01-15T10:10:07.000Z",
    "error": null,
    "attempts": 1
  },
  {
    "id": "job-b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "parentRoot": "mobile-16-pro",
    "requestedByIds": [
      "mobile-16-pro-l1"
    ],
    "status": "PENDING",
    "createdAt": "2024-01-15T10:10:00.000Z",
    "processingStartedAt": null,
    "finishedAt": null,
    "error": null,
    "attempts": 0
  }
]

Retrieving a recalculation job

get

Retrieves the current status and details of a specific dynamic variant recalculation job. Use this endpoint to poll for job completion after triggering recalculation.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage products.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

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

Unique identifier of the recalculation job.

Responses
200

Job retrieved successfully.

application/json

Represents a single dynamic variant recalculation job. One job is created per unique root product. Jobs remain queryable until automatically removed approximately 30 days after reaching a terminal state.

idstringOptional

Unique identifier of the recalculation job.

parentRootstringOptional

Identifier of the root product whose variant tree is being recalculated.

requestedByIdsstring[]Optional

List of product IDs that were submitted in the recalculation request and resolved to this root.

statusstring · enumOptional

Current status of a dynamic variant recalculation job.

Possible values:
createdAtstring · date-timeOptional

Timestamp when the job was created.

processingStartedAtstring · date-timeOptional

Timestamp when a subscriber picked up the job and started processing. Null while the job is still PENDING.

finishedAtstring · date-timeOptional

Timestamp when the job reached a terminal state (FINISHED, FAILED, or FAILED_PERMANENT).

errorstringOptional

Error message if the job failed. Null for successful jobs.

attemptsintegerOptional

Number of processing attempts made for this job. Incremented on each delivery from the pub/sub subscription.

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

{
  "id": "job-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parentRoot": "mobile-15-pro",
  "requestedByIds": [
    "mobile-15-pro-l1",
    "mobile-15-pro-l2-retail"
  ],
  "status": "FINISHED",
  "createdAt": "2024-01-15T10:10:00.000Z",
  "processingStartedAt": "2024-01-15T10:10:03.000Z",
  "finishedAt": "2024-01-15T10:10:07.000Z",
  "error": null,
  "attempts": 1
}

Retrieving a product

get

Retrieves a specified product details.

Additional scope information

  • The product.product_read_unpublished scope is only required if the product has not been published.

  • The product.product_read_by_vendor scope is only required to fetch products belonging to the vendor.

  • The product.product_manage_by_vendor scope is only required to manage products belonging to the vendor.

Required scopes
This endpoint requires the following scopes:
  • : Needed to retrieve unpublished products.
  • : The scope allows vendor to read products with assigned vendor.
  • : The scope allows vendor to manage products with assigned vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
productIdstringRequired

Product unique identifier generated when the product is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant 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. You can combine multiple values, for example expand=template,parentVariant,brand,labels.

Possible values:

  • template
  • parentVariant
  • brand
  • labels
rawValuebooleanOptional

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

  • If set to true, the result contains values from both the variant and its parent variant.
  • If set to false, the result contains only 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
or
or
or
or
get/product/{tenant}/products/{productId}
GET /product/{tenant}/products/{productId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "name": "Smartphone X2",
  "code": "SmartphoneX21415269949943",
  "description": "The world's best camera and camcorder in a waterproof smartphone.",
  "id": "545b4e3dfaee4c10def3db24",
  "productType": "BASIC",
  "yrn": "urn:yaas:saasag:caasproduct:product:myshop;545b4e3dfaee4c10def3db24",
  "taxClasses": {
    "EN": "STANDARD"
  },
  "published": false,
  "template": {
    "id": "633d774f37937d425ce5570f",
    "version": 1
  },
  "relatedItems": [
    {
      "refId": "631c6adac2d4ea73be34f0d1",
      "type": "ACCESSORY"
    }
  ],
  "customerSegmentIds": [
    "689591c74ac99162678ae78f",
    "689591c74ac99162678ae78g"
  ],
  "categoryIds": [
    "631c6adac2d4ea73be34f0d4",
    "631c6adac2d4ea73be34f0d5"
  ],
  "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/emporix-docs/product.v2",
    "mixins": {
      "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/productCustomAttributesMixIn-v38.json",
      "productTemplateAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/633d774f37937d425ce5570f_templateAttributes_v1.json",
      "productVariantAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/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.

Additional scope information

  • The product.product_manage_by_vendor scope is only required for vendor employees to manage products belonging to the vendor.

  • The product.product_publish scope is only required if you want to publish the product when updating it.

  • The product.product_unpublish scope is only required if you want to unpublish the product when updating it.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage products.
  • : Needed to publish products.
  • : Needed to unpublish products.
  • : The scope allows vendor to manage products with assigned vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
productIdstringRequired

Product unique identifier generated when the product is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
partialbooleanOptional
OptionDescription
trueA partial product update is performed.
falseA full product replacement is 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
skipRelatedItemsValidationbooleanOptional

If set to true, the validation that checks whether related products exist is skipped. This is useful during data loading, where related products may not yet exist and will be created later. This parameter is only respected when the allowToSkipRelatedProductsValidation system setting is set to true. Otherwise, it is disregarded.

Default: false
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 interprets the localized fields as being provided in the default language or the 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 is rejected.

Body
or
or
or
or
Responses
201

The resource has been successfully created.

application/json
idstringOptional
yrnstringOptional

In YaaS, a global resource identifier is a Uniform Resource Name (URN) with a custom YaaS schema and is called a YaaS Resource Name, or YRN.

It is a unique identifier, which stores information about a resource, such as its type, ID or name of the tenant.

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

{
  "name": "Smartphone 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/emporix-docs/productCustomAttributesMixIn.v29.json",
      "salePricesData": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/salePriceData.json"
    }
  }
}
{
  "id": "631b4bfe61f5e1663c745ffd",
  "yrn": "urn:yaas:saasag:caasproduct:product:apistage;631b4bfe61f5e1663c745ffd"
}

Deleting a product

delete

Deletes a specified product.

Additional scope information

  • The product.product_manage_by_vendor scope is only required for vendor employees to delete products belonging to the vendor.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage products.
  • : The scope allows vendor to manage products with assigned vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
productIdstringRequired

Product unique identifier generated when the product is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

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

Removing a parent variant product also removes all of its child variants. This applies to both PARENT_VARIANT roots with VARIANT children and DYNAMIC_VARIANT parent products with all descendant dynamic variants in the tree. This operation has to be confirmed by setting force=true.

Default: false
doIndexbooleanOptional

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

Default: true
Body
objectOptional
Responses
204

The resource has been successfully deleted.

No content
delete/product/{tenant}/products/{productId}
DELETE /product/{tenant}/products/{productId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}
No content

Partially updating a product

patch

Partially updates a specified product.

Additional scope information

  • The product.product_manage_by_vendor scope is only required for vendor employees to manage products belonging to the vendor.

  • The product.product_publish scope is only required if you want to publish the product when updating it.

  • The product.product_unpublish scope is only required if you want to unpublish the product when updating it.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage products.
  • : Needed to publish products.
  • : Needed to unpublish products.
  • : The scope allows vendor to manage products with assigned vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
productIdstringRequired

Product unique identifier generated when the product is created.

tenantstring · min: 3 · max: 16Required

Your Emporix tenant 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
skipRelatedItemsValidationbooleanOptional

If set to true, the validation that checks whether related products exist is skipped. This is useful during data loading, where related products may not yet exist and will be created later. This parameter is only respected when the allowToSkipRelatedProductsValidation system setting is set to true. Otherwise, it is disregarded.

Default: false
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 interprets the localized fields as being provided in the default language or the 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 is rejected.

Body
nameone ofOptional

Product name.

stringOptional
or
codestring · min: 1Optional

Unique product identifier, defined by the user.

descriptionone ofOptional

Product description.

stringOptional
or
publishedbooleanOptional

Flag indicating whether the product has been published or not.

Default: false
weightDependentbooleanOptional

Mark the product as weight-dependent if the line item price could change after packaging, as this is necessary to ensure that credit card payments can be authorized.

brandIdstringOptional

ID of brand.

labelIdsstring[]Optional

Collection of label IDs.

Responses
204

The resource has been successfully updated.

No content
patch/product/{tenant}/products/{productId}
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
PreviousProduct
NextProduct Templates

Last updated

Was this helpful?