Product Templates

Manage Product Templates

Retrieving all product templates

get

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

Authorizations

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

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:

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 is used for sorting the name property. The language suffix takes precedence over Accept-Language header.
If a localized field does not contain information about a language, then the Accept-Language header is used. For example name:ASC and Accept-Language: de. In that case de is used for sorting the name property.
If a localized field does not contain information about language and Accept-Language header contains *, then the default language from configuration service is used as a language. For example name:ASC and Accept-Language: * and default language is pl then pl is used as a language for name property.
If a localized field does not contains information about language and Accept-Language header does not exists in the request, then the default language from configuration service is used. "

qstringOptional

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

200Success

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

get

/product/{tenant}/product-templates

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

[
  {
    "id": "634cea2740033d7c2e7b03a8",
    "name": {
      "en": "T-shirt"
    },
    "attributes": [
      {
        "key": "color",
        "name": {
          "en": "Color",
          "pl": "Kolor"
        },
        "type": "TEXT",
        "metadata": {
          "mandatory": false,
          "variantAttribute": true,
          "defaultValue": "GREEN"
        },
        "values": [
          {
            "key": "GREEN"
          },
          {
            "key": "RED"
          }
        ]
      }
    ],
    "metadata": {
      "variantAttributesSchema": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/testTenant/634cea2740033d7c2e7b03a8-variantAttributes_v1.json",
      "templateAttributesSchema": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/saastest2/634cea2740033d7c2e7b03a8-templateAttributes_v1.json",
      "createdAt": "2022-03-31T09:52:15.423Z",
      "modifiedAt": "2022-03-31T09:52:15.423Z",
      "version": 1
    }
  }
]

Creating a new product template

post

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

Authorizations

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]+$

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

all ofOptional

Responses

201Success

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

post

/product/{tenant}/product-templates

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

{
  "id": "545b4e3dfaee4c10def3db24",
  "name": {
    "en": "T-shirt"
  },
  "attributes": [
    {
      "key": "color",
      "name": {
        "en": "Color",
        "pl": "Kolor"
      },
      "type": "TEXT",
      "metadata": {
        "mandatory": false,
        "variantAttribute": true,
        "defaultValue": "GREEN"
      },
      "values": [
        {
          "key": "GREEN"
        },
        {
          "key": "RED"
        }
      ]
    }
  ]
}

{
  "id": "624c3e7c3406122baacc7e93"
}

Retrieving a product template

get

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

Authorizations

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]+$

product-template-idstringRequired

Unique identifier of the product template.

Query parameters

versionstringOptional

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

Header parameters

Accept-LanguagestringOptional

Responses

200Success

application/json

Responseall of

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

/product/{tenant}/product-templates/{product-template-id}

GET /product/{tenant}/product-templates/{product-template-id} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "634cea2740033d7c2e7b03a8",
  "name": {
    "en": "T-shirt"
  },
  "attributes": [
    {
      "key": "color",
      "name": {
        "en": "Color",
        "pl": "Kolor"
      },
      "type": "TEXT",
      "metadata": {
        "mandatory": false,
        "variantAttribute": false,
        "defaultValue": "GREEN"
      },
      "values": [
        {
          "key": "GREEN"
        },
        {
          "key": "RED"
        }
      ]
    }
  ],
  "metadata": {
    "variantAttributesSchema": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/testTenant/634cea2740033d7c2e7b03a8-variantAttributes_v1.json",
    "templateAttributesSchema": "https://res.cloudinary.com/saas-ag/raw/upload/schemata/saastest2/634cea2740033d7c2e7b03a8-templateAttributes_v1.json",
    "createdAt": "2022-03-31T09:52:15.423Z",
    "modifiedAt": "2022-03-31T09:52:15.423Z",
    "version": 1
  }
}

Updating a product template

put

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

Authorizations

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]+$

product-template-idstringRequired

Unique identifier of the product template.

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.

Body

all ofOptional

Responses

204

No Content

No content

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:

Product with given code already exists, please choose unique code for your product
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.
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

/product/{tenant}/product-templates/{product-template-id}

PUT /product/{tenant}/product-templates/{product-template-id} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 249

{
  "name": {
    "en": "T-shirt"
  },
  "attributes": [
    {
      "key": "color",
      "name": {
        "en": "Color",
        "pl": "Kolor"
      },
      "type": "TEXT",
      "metadata": {
        "mandatory": false,
        "variantAttribute": true,
        "defaultValue": "GREEN"
      },
      "values": [
        {
          "key": "GREEN"
        },
        {
          "key": "RED"
        }
      ]
    }
  ],
  "metadata": {
    "version": 1
  }
}

No content

Deleting a product template

delete

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

Authorizations

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]+$

product-template-idstringRequired

Unique identifier of the product template.

Responses

204

No Content

No content

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

/product/{tenant}/product-templates/{product-template-id}

DELETE /product/{tenant}/product-templates/{product-template-id} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

PreviousProducts NextModels

Was this helpful?