Price Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

Manage price information for products.

Note Some endpoints are currently available in two versions:

  • v1
  • v2

You can define which version do you want to access by setting the X-Version header to v1 or v2, respectively. If you don't specify the version when sending a request, it will be sent to the v1 version by default.

Key Features:

  • Net / gross prices
  • Customer-specific prices
  • Tiered / volume prices
  • Price based on measurement units (such as weight or length)
  • Indicative prices, e.g. £5 per kg

Key Benefits:

  • Depending on customers, show prices either with tax included or excluded
  • Add an extra service level by selling products not only by the piece, but also in exactly the required quantity - by weight, length, or other measurement units
  • Sell products with approximate prices / indicative prices

Price lists

Retrieving all price lists

Retrieves all price lists assigned to the tenant. You can filter the results with query parameters.

This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.

Required scopes

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

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
pageNumber
integer >= 1
Default: 1

Page number to be retrieved. The number of the first page is 1.

Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

sort
string

List of properties used to sort the results, separated by commas. The order of properties indicates their priority in sorting.

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

If the sorting direction is not specified, the fields are sorted in ascending order.

Example: sort=name,code:desc
name
string

Price list's name.

effectiveDate
string

Date on which retrieved prices should be valid, compliant with the ISO 8601 standard. Format:date-fullyear "-" date-month "-" date-mday "T" partial-time time-offset

Example: effectiveDate=2022-01-01T00:00:00Z
currency
string

Code of the currency in which the prices are expressed, as defined in the Currency Service.

country
string

Code of the country to which the price list applies, as defined in the Country Service.

siteCode
string

Code of the site to which the price list applies.

customerGroups
string

Comma separated list of IDs of the customer groups to which the price list applies.

region
string

Code of the region to which the price list applies.

header Parameters
X-Version
string [ 2 .. 3 ] characters ^v[1-9][0-9]?$
Default: v2

Version of the Price Service to which the request should be sent. Possible values:

  • v1
  • v2
Accept-Language
string

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as a map of single translation, where the key is a language code and the value is in a respective language.
  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the header is empty, localized fields are retrieved as maps of single translation, where the key is a language code and the value is in a respective language. The endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.
X-Total-Count
boolean
Default: false

Flag indicating whether the total count of retrieved items should be returned.

Responses
200

The request was successful. A list of price lists is returned.

401

Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

500

Some server-side error occurred. Details are provided in the response payload.

get/{tenant}/price-lists
Request samples 
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Creating a new price list
Creates a new price list.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Content-Language
string
List of languages in which localized fields in the request body are provided.


    

  • 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, then the localized fields should be provided as a map of single translation, where the key is a language code and the value is in a respective language.
    • 

  • If the Content-Language header is empty, then the localized fields should be provided as maps of single translation, where the key is a language code and the value is in a respective language. The endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



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


 
Request Body schema: application/json
id
string
Custom price list identifier. If not provided, it is automatically generated.


 
name
required
object
Price list name. It should be a brief, human-readable name that describes the purpose of the price list, specified in a form of a map of translations.


    

  • If the Content-Language header is set to *, then the name should be provided as a map of translations, where each key is a language code and the value is the name in its respective language.
    • 

  • If the Content-Language header is set to a specific language, then the name should be provided as a map of single translation, where the key is a language code and the value is the name in its respective language.
    • 

  • If the Content-Language header is empty, then the name should be provided as a map of single translation, where the key is a language code and the value is the name in its respective language. The endpoint will asume that the name is provided in the default language defined in the Configuration Service.
    • 



Note: You can provide the names only in languages defined in the Configuration Service. In case the name is provided in a language that is not defined in the Configuration Service, the request will be rejected.


 
currency
string (currency) [A-Z]{3}
Currency code, compliant with the ISO 4217 standard.


 
countries
Array of strings
Codes of countries to which the price list applies, as defined in the Country Service.


Note If not specified, the price list will be applicable to users from all locations.


 
regions
Array of strings
List of the regions to which the price list applies.


Note If not specified, the price list will be applicable to users from all locations.


 
customerGroups
Array of strings
List of customer groups' ids for whom the price list is valid.


Note: If not specified, the price list will be applicable to all customer groups.


Note: This is a preview field - the system does not fully operate on the customer groups concept yet.


 
siteCode
required
string
Code of the site to which the price list applies.


 
object
Date range in which the object is valid.


 
object
Map of custom price lists attributes.


 
object
 
Responses 
201
The request was successful. The price list has been created.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


post/{tenant}/price-lists
Request samples 
application/json
{
  • "name": {
    },
  • "currency": "EUR",
  • "countries": [
    ],
  • "customerGroups": [
    ],
  • "siteCode": "example-site-1",
  • "validity": {
    }
}
Response samples 
application/json
{
  • "id": "6245a8f578a8576e338fa9c2"
}
Retrieving a price list
Retrieves a specified price lists's details.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_read
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as a map of single translation, where the key is a language code and the value is in a respective language.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved as maps of single translation, where the key is a language code and the value is in a respective language. The endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



 
Responses 
200
The request was successful. The price list is returned.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
The requested price list could not be found.


500
Some server-side error occurred. Details are provided in the response payload.


get/{tenant}/price-lists/{priceListId}
Request samples 
Response samples 
application/json
{
  • "id": "example-id-1",
  • "name": {
    },
  • "currency": "EUR",
  • "countries": [
    ],
  • "customerGroups": [
    ],
  • "siteCode": "example-site-1",
  • "validity": {
    },
  • "metadata": {
    }
}
Updating a price list
Updates a specified price list.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Content-Language
string
List of languages in which localized fields in the request body are provided.


    

  • 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, then the localized fields should be provided as a map of single translation, where the key is a language code and the value is in a respective language.
    • 

  • If the Content-Language header is empty, then the localized fields should be provided as maps of single translation, where the key is a language code and the value is in a respective language. The endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



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


 
Request Body schema: application/json
id
string
Custom price list identifier. If not provided, it is automatically generated.


 
name
required
object
Price list name. It should be a brief, human-readable name that describes the purpose of the price list, specified in a form of a map of translations.


    

  • If the Content-Language header is set to *, then the name should be provided as a map of translations, where each key is a language code and the value is the name in its respective language.
    • 

  • If the Content-Language header is set to a specific language, then the name should be provided as a map of single translation, where the key is a language code and the value is the name in its respective language.
    • 

  • If the Content-Language header is empty, then the name should be provided as a map of single translation, where the key is a language code and the value is the name in its respective language. The endpoint will asume that the name is provided in the default language defined in the Configuration Service.
    • 



Note: You can provide the names only in languages defined in the Configuration Service. In case the name is provided in a language that is not defined in the Configuration Service, the request will be rejected.


 
currency
string (currency) [A-Z]{3}
Currency code, compliant with the ISO 4217 standard.


 
countries
Array of strings
Codes of countries to which the price list applies, as defined in the Country Service.


Note If not specified, the price list will be applicable to users from all locations.


 
regions
Array of strings
List of the regions to which the price list applies.


Note If not specified, the price list will be applicable to users from all locations.


 
customerGroups
Array of strings
List of customer groups' ids for whom the price list is valid.


Note: If not specified, the price list will be applicable to all customer groups.


Note: This is a preview field - the system does not fully operate on the customer groups concept yet.


 
siteCode
required
string
Code of the site to which the price list applies.


 
object
Date range in which the object is valid.


 
object
Map of custom price lists attributes.


 
object
 
Responses 
204
The request was successful. The price list has been updated.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
The requested price list could not be found.


500
Some server-side error occurred. Details are provided in the response payload.


put/{tenant}/price-lists/{priceListId}
Request samples 
application/json
{
  • "name": {
    },
  • "currency": "EUR",
  • "countries": [
    ],
  • "customerGroups": [
    ],
  • "siteCode": "example-site-1",
  • "validity": {
    },
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "fault": {
    }
}
Deleting a price list
Deletes a specified price list.


Important: All prices assigned to the price list will be deleted as well, in an asynchronous manner.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Responses 
204
The request was successful. The price list has been deleted.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


delete/{tenant}/price-lists/{priceListId}
Request samples 
Response samples 
application/json
{
  • "fault": {
    }
}
Price matching
Matching prices for specific attributes
Finds the best price based on specified criteria.


In simplification, the price matching algorithm is made up of the following steps:


    

  1. All prices that match the specified criteria are fetched.
    2. 

  2. A unified originalValue is calculated for each price.
    3. 

  3. The price with the lowest originalValue is returned.
    4. 



To use the price matching functionality, you need to define appropriate tax classes in the Tax Service and then assign them to products for which prices will be matched through the Product Service.


Special cases:


    

  • If the matched price currency is different than the requested currency, the price is calculated based on exchange rates.
    

    Note: To calculate prices in different currencies, you need to define their exchange rates in the Currency Service.
    

    • 

  • If the matched price location is different than the requested location, the price is calculated based on tax classes.
    

    Note: To calculate prices for different locations, you need to assign their tax classes to the product for which the price is matched. Tax classes need to be defined in the Tax Service and then assigned to the product through the Product Service.
    

    • 



The endpoint returns the best price as a gross or net depending on the following cases:


    

  • If requested site's includesTax field is specified (through the Site Settings Service):
      

    • If the includesTax field is set to true, the matched price is returned as a gross value.
      • 

    • If the includesTax field is set to false, the matched price is returned as a net value.
      • 

    

    • 

  • If requested site's includesTax field is not specified:
      

    • If the includesTax field in the price model associated with the price is set to true, the matched price is returned as a gross value.
      • 

    • If the includesTax field in the price model associated with the price is set to false, the matched price is returned as a net value.
      • 

    

    • 



This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.




Required scopes


    

  • price.price_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Request Body schema: application/json
targetCurrency
required
string
Code of the currency in which the prices should be matched, as defined in the Currency Service.


Note: If the matched price is defined in another currency, a currency exchange algorithm will be used, but only if exchange rates between the two currencies have been defined.


 
siteCode
required
string
Code of the site to which the matched prices should apply.


 
required
object
 
required
Array of objects
List of items (products or prices) for which the prices should be matched.


 
object
Customer or customer group for whom the matched prices should be valid.


 
useFallback
boolean
If no price that matches the criteria is found for the specified site, the price matching functionality will try to find the best price for the main site. To enable this option, this field needs to be set to true.


Note: Using the fallback mechanism may impact the performance as the price matching has to run a second time. If the fallback mechanism is used, the response's siteCode field will be set to main.


 
Responses 
200
OK


400
Bad Request


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
Not Found


500
Some server-side error occurred. Details are provided in the response payload.


post/{tenant}/match-prices
Request samples 
application/json
{
  • "targetCurrency": "EUR",
  • "siteCode": "1111",
  • "targetLocation": {
    },
  • "items": [
    ]
}
Response samples 
application/json
{
  • "priceId": "6245aa0a78a8576e338fa9c4",
  • "itemId": {
    },
  • "site": {
    },
  • "currency": "EUR",
  • "location": {
    },
  • "originalValue": 13.55,
  • "effectiveValue": 13.55,
  • "totalValue": 1355,
  • "quantity": {
    },
  • "includesTax": true,
  • "priceModel": {
    },
  • "tax": {
    },
  • "tierValues": [
    ],
  • "metadata": {
    }
}
Matching prices for session context
Finds the best price based on information retrieved from the session context.


The behavior of the logic is the same as of the /{tenant}/match-prices (function/mechanism?). The only exception is that the criteria are created based on the information retrieved from the session details assigned to the access-token in the Session-context Service`.


The list of items is also needed as body parameter (similar to the other endpoint).


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


SecurityCustomerAccessToken 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Request Body schema: application/json
Array of objects
List of items (products or prices) for which the prices should be matched.


 
Responses 
200
The prices were successfully matched.


400
Bad Request


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
Not Found


500
Some server-side error occurred. Details are provided in the response payload.


post/{tenant}/match-prices-by-context
Request samples 
application/json
{
  • "items": [
    ]
}
Response samples 
application/json
{
  • "priceId": "6245aa0a78a8576e338fa9c4",
  • "itemId": {
    },
  • "site": {
    },
  • "currency": "EUR",
  • "location": {
    },
  • "originalValue": 13.55,
  • "effectiveValue": 13.55,
  • "totalValue": 1355,
  • "quantity": {
    },
  • "includesTax": true,
  • "priceModel": {
    },
  • "tax": {
    },
  • "tierValues": [
    ],
  • "metadata": {
    }
}
Price models
Creating a new price model
Creates a new price model.


A price model can be defined as a repeatable way to sell products in a market with the intention of making a profit. Price models define basic structures for prices, including whether the prices are expressed as gross or net or the measurement units for which prices are defined.


Each price model can specify one of three pricing strategies:


    

  • Basic pricing, where the price per unit is constant, regardless of the ordered quantity.
    • 

  • Volume pricing, where the price per unit depends on the ordered quantity.
    • 

  • Tiered pricing, where the price per unit depends on the tiers that the ordered quantity falls into.
    • 



This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricemodel_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
header Parameters
Content-Language
string
List of languages in which localized fields in the request body are provided.


    

  • 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 asume that the localized fields are provided in the default language 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.


 
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Request Body schema: application/json
id
string
Custom price model identifier. If not provided, it is automatically generated.


 
includesTax
required
boolean
Flag indicating whether prices assigned to the price model will be expressed as net or gross.






Value
Description





true
Prices will be expressed as gross values.




false
Prices will be expressed as net values.





 
includesMarkup
boolean
Flag indicating whether prices assigned to the price model include markup.


Note: This is a preview field.


 
default
boolean
Indicates whether the price model is default one or not.


 
required
object or string
Price model name. It should be a brief, human-readable name that describes purposes of the model.


    

  • If the Content-Language header is set to *, then the name should be provided as a map of translations, where each key is a language code and the value is the name in its respective language.
    • 

  • If the Content-Language header is set to a specific language, the name should be provided as a string.
    • 

  • If the Content-Language header is empty, the endpoint will asume that the name is provided in the default language defined in the Configuration Service.
    • 



Note: You can provide the names only in languages defined in the Configuration Service. In case the name is provided in a language that is not defined in the Configuration Service, the request will be rejected.


 
object or string
Price model description. It can contain details about the price model.


    

  • If the Content-Language header is set to *, then the description should be provided as a map of translations, where each key is a language code and the value is the description in its respective language.
    • 

  • If the Content-Language header is set to a specific language, the description should be provided as a string.
    • 

  • If the Content-Language header is empty, the endpoint will asume that the description is provided in the default language defined in the Configuration Service.
    • 



Note: You can provide the descriptions only in languages defined in the Configuration Service. In case the description is provided in a language that is not defined in the Configuration Service, the request will be rejected.


 
required
object
Definition of pricing tiers.


 
required
object
Measurement unit and quantity for which the price is defined.


For example, if a product is sold by the piece, the field should contain 1 pc. If products relevant to this price model are sold per kilogram, this field should contain 1 kg.


 
Responses 
201
The request was successful. The price model has been created.


400
Request was syntactically incorrect. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


post/{tenant}/priceModels
Request samples 
application/json
{
  • "includesTax": true,
  • "includesMarkup": true,
  • "name": "Piece price model",
  • "description": "Sample description",
  • "tierDefinition": {
    },
  • "measurementUnit": {
    }
}
Response samples 
application/json
{
  • "id": "string"
}
Retrieving all price models
Retrieves all price models assigned to the tenant. You can filter the results with query parameters.


A price model can be defined as a repeatable way to sell products in a market with the intention of making a profit. Price models define basic structures for prices.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricemodel_read
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
query Parameters
pageNumber
integer  >= 1 
 Default:  1
Page number to be retrieved. The number of the first page is 1.


Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
pageSize
integer  >= 1 
 Default:  60
Number of items to be retrieved per page.


 
sort
string
List of properties used to sort the results, separated by commas. The order of properties indicates their priority in sorting.


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
    • 



If the sorting direction is not specified, the fields are sorted in ascending order.


 
 Example:  sort=name,code:desc
includesTax
boolean
Flag indicating whether prices assigned to the price model are expressed as net or gross.






Value
Description





true
Prices are expressed as gross values.




false
Prices are expressed as net values.





 
includesMarkup
boolean
Flag indicating whether prices assigned to the price model include markup.


Note: This is a preview field.


 
tierType
string
Pricing strategy applicable to the price model. Possible values:


    

  • BASIC
    • 

  • VOLUME
    • 

  • TIERED
    • 



 
name
string
Price model's name.


 
description
string
Price model's description.


 
unitcode
string
Filter price models by unit code


 
header Parameters
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
    • 



 
X-Total-Count
boolean
 Default:  false
Flag indicating whether the total count of retrieved items should be returned.


 
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Responses 
200
The request was successful. A list of price models is returned.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


get/{tenant}/priceModels
Request samples 
Response samples 
[
  • {
    }
]
Retrieving a price model
Retrieves a specified price model's details.


A price model can be defined as a repeatable way to sell products in a market with the intention of making a profit. Price models define basic structures for prices.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricemodel_read
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceModelId
required
string
Price model's unique identifier, generated when the price model is created.


 
header Parameters
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
    • 



 
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Responses 
200
The request was successful. The price model is returned.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
The requested resource does not exist.


get/{tenant}/priceModels/{priceModelId}
Request samples 
Response samples 
[
  • {
    }
]
Updating a price model
Updates a specified price model's details.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricemodel_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceModelId
required
string
Price model's unique identifier, generated when the price model is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Content-Language
string
List of languages in which localized fields in the request body are provided.


    

  • 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 asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



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


 
Request Body schema: application/json
id
string
Custom price model identifier. If not provided, it is automatically generated.


 
includesTax
required
boolean
Flag indicating whether prices assigned to the price model will be expressed as net or gross.






Value
Description





true
Prices will be expressed as gross values.




false
Prices will be expressed as net values.





 
includesMarkup
boolean
Flag indicating whether prices assigned to the price model include markup.


Note: This is a preview field.


 
default
boolean
Indicates whether the price model is default one or not.


 
required
object or string
Price model name. It should be a brief, human-readable name that describes purposes of the model.


    

  • If the Content-Language header is set to *, then the name should be provided as a map of translations, where each key is a language code and the value is the name in its respective language.
    • 

  • If the Content-Language header is set to a specific language, the name should be provided as a string.
    • 

  • If the Content-Language header is empty, the endpoint will asume that the name is provided in the default language defined in the Configuration Service.
    • 



Note: You can provide the names only in languages defined in the Configuration Service. In case the name is provided in a language that is not defined in the Configuration Service, the request will be rejected.


 
object or string
Price model description. It can contain details about the price model.


    

  • If the Content-Language header is set to *, then the description should be provided as a map of translations, where each key is a language code and the value is the description in its respective language.
    • 

  • If the Content-Language header is set to a specific language, the description should be provided as a string.
    • 

  • If the Content-Language header is empty, the endpoint will asume that the description is provided in the default language defined in the Configuration Service.
    • 



Note: You can provide the descriptions only in languages defined in the Configuration Service. In case the description is provided in a language that is not defined in the Configuration Service, the request will be rejected.


 
required
object
Definition of pricing tiers.


 
required
object
Measurement unit and quantity for which the price is defined.


For example, if a product is sold by the piece, the field should contain 1 pc. If products relevant to this price model are sold per kilogram, this field should contain 1 kg.


 
Responses 
204
The request was successful. The price model has been updated.


400
Request was syntactically incorrect. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
The requested resource does not exist.


put/{tenant}/priceModels/{priceModelId}
Request samples 
application/json
{
  • "id": "6245a8f578a8576e338fa9c2",
  • "name": "Tiered price model",
  • "includesTax": true,
  • "includesMarkup": true,
  • "measurementUnit": {
    },
  • "tierDefinition": {
    },
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Tenant in the header is not matching with the one provided in the URI."
}
Deleting a price model
Deletes a specified price model.


Important: If you want to delete a price model that has prices assigned to it, you need to set the forceDelete query parameter to true. In this case, all prices assigned to the price model will be deleted as well, in an asynchronous manner.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricemodel_manage
    

    • 

  • price.pricemodel_manage_admin
    

    Note: The price.pricemodel_manage_admin scope is only required if you want to delete a price model that has prices assigned to it.
    

    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceModelId
required
string
Price model's unique identifier, generated when the price model is created.


 
query Parameters
forceDelete
boolean
    

  • If set to true and the price model has prices assigned to it, both the price model and the prices will be deleted.
    

    Important: To set this parameter to true, your access token needs to have the price.pricemodel_manage_admin scope granted.
    

    • 

  • If set to false or not specified and the price model has prices assigned to it, the endpoint will respond with a 400 error.
    

    • 



 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Responses 
204
The request was successful. The price model has been deleted.


400
Request was syntactically incorrect. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


delete/{tenant}/priceModels/{priceModelId}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Tenant in the header is not matching with the one provided in the URI."
}
Prices
Creating a new price
Creates a new price for a specified product.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.




Required scopes


    

  • price.price_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Content-Language
string
List of languages in which localized fields in the request body are provided.


    

  • 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 asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



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


 
Request Body schema: application/json
id
required
string
Custom price identifier. If not provided, it is automatically generated.


 
required
object
Item for which the price is defined.


 
itemYrn
string
Product's uniform resource name.


 
currency
required
string (currency) [A-Z]{3}
Currency code, compliant with the ISO 4217 standard.


 
required
object
 
object
 
object
Restrictions that limit the validity of the price model and prices assigned to it.


 
priceModelId
required
string
ID of the price model to which the price should assigned.


 
required
Array of objects
Prices for tiers specified in the price model. The prices will be assigned to tiers based on the entered order (the first value will be assigned to the first tier, the second value to second tier).


Note: If this field does not contain values for all tiers defined in the price model, the endpoint will response error.


 
mixins
object
Map of custom price attributes.


 
object
 
Responses 
201
The request was successful. The price has been created.


400
Bad Request


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


post/{tenant}/prices
Request samples 
application/json
{
  • "id": "6245aa0a78a8576e338fa9c4",
  • "itemId": {
    },
  • "currency": "EUR",
  • "location": {
    },
  • "priceModelId": "6245a8f578a8576e338fa9c3",
  • "restrictions": {
    },
  • "tierValues": [
    ]
}
Response samples 
application/json
{
  • "id": "624c3e7c3406122baacc7e93"
}
Retrieving all prices
Retrieves all prices assigned to the tenant. You can filter the results with query parameters.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.




Required scopes


No specific scopes are required.


SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
query Parameters
siteCode
string
 Default:  "main"
Codes of sites for which prices should be retrieved.


 
currency
string
Codes of currencies in which prices should be retrieved.


 
effectiveDate
string
 Default:  "2022-01-01T00:00:00Z"
Date on which retrieved prices should be valid, compliant with the ISO 8601 standard. Format:date-fullyear "-" date-month "-" date-mday "T" partial-time time-offset


 
sort
string
List of properties used to sort the results, separated by commas. The order of properties indicates their priority in sorting.


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
    • 



If the sorting direction is not specified, the fields are sorted in ascending order.


 
pageNumber
integer  >= 1 
 Default:  1
Page number to be retrieved. The number of the first page is 1.


Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
pageSize
integer  >= 1 
 Default:  60
Number of items to be retrieved per page.


 
principalId
string
IDs of customers for whom the retrieved prices should be valid.


Note: This parameter is only available in the v2 version of the Price Service.


 
priceModelId
string
ID of the price model to which the retrieved prices should be assigned.


Note: This parameter is only available in the v2 version of the Price Service.


 
itemId
string
IDs of products for which prices should be retrieved.


Note: This parameter is only available in the v2 version of the Price Service.


 
itemType
string
Item types for which prices should be retrieved. Possible values:


    

  • PRODUCT
    

    • 

  • SKU
    

    Note: The SKU value is a preview value - the system does not fully operate on the SKU concept yet.
    

    • 



Note: This parameter is only available in the v2 version of the Price Service.


 
country
string
Codes of countries for which prices should be retrieved.


Note: This parameter is only available in the v2 version of the Price Service.


 
itemName
string
A product or SKU name. This attribute is available only for Price v2


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
    • 



 
Responses 
200
The request was successful. A list of prices is returned.


400
Request was syntactically incorrect. Details are provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


500
Some server-side error occurred. Details are provided in the response payload.


get/{tenant}/prices
Request samples 
Response samples 
application/json
[
  • {
    }
]
Creating multiple prices
Creates multiple prices.


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


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.




Required scopes


    

  • price.price_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Content-Language
string
List of languages in which localized fields in the request body are provided.


    

  • 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 asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



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


 
Request Body schema: application/json
 Array 
id
required
string
Custom price identifier. If not provided, it is automatically generated.


 
required
object
Item for which the price is defined.


 
itemYrn
string
Product's uniform resource name.


 
currency
required
string (currency) [A-Z]{3}
Currency code, compliant with the ISO 4217 standard.


 
required
object
 
object
 
object
Restrictions that limit the validity of the price model and prices assigned to it.


 
priceModelId
required
string
ID of the price model to which the price should assigned.


 
required
Array of objects
Prices for tiers specified in the price model. The prices will be assigned to tiers based on the entered order (the first value will be assigned to the first tier, the second value to second tier).


Note: If this field does not contain values for all tiers defined in the price model, the endpoint will response error.


 
mixins
object
Map of custom price attributes.


 
object
 
Responses 
207
Multi-Status


400
Bad Request


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


post/{tenant}/prices/bulk
Request samples 
application/json
[
  • {
    },
  • {
    }
]
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Updating multiple prices
Updates multiple prices.


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


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.




Required scopes


    

  • price.price_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Content-Language
string
List of languages in which localized fields in the request body are provided.


    

  • 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 asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



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


 
Request Body schema: application/json
 Array 
id
string
A price identifier.


 
object
Item for which the price is defined.


 
itemYrn
string
Product's uniform resource name.


 
currency
string
Currency code, as defined in the Currency Service.


 
object
 
object
 
priceModelId
string
ID of the price model to which the price is assigned.


 
object (restrictions) 
Restrictions that limit the validity of the price model and prices assigned to it.


 
Array of objects (tierValueRetrieval) 
 
mixins
object
Custom price attributes.


 
object (priceMetadata) 
 
object (priceModelExpand) 
Price model to which the price is assigned.


Note: This field is only returned if the extendWithPriceModel query param is set to true when retrieving a price by ID.


 
Responses 
207
Multi-Status


400
Bad Request


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


put/{tenant}/prices/bulk
Request samples 
application/json
[
  • {
    },
  • {
    }
]
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Retrieving a price
Retrieves a specified price's details.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.




Required scopes


No specific scopes are required.


SecurityOAuth2 
Request 
path Parameters
priceId
required
string
Price's unique identifier, generated when the price is created.


 
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
query Parameters
extendWithPriceModel
boolean
 Default:  false
If set to true, the response will also include the price model's details.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
    • 



 
Responses 
200
The request was successful. Price details are returned.


400
Request was syntactically incorrect. Details are provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


404
The requested resource does not exist.


500
Some server-side error occurred. Details are provided in the response payload.


get/{tenant}/prices/{priceId}
Request samples 
Response samples 
application/json
{
  • "id": "62468170bddc000efeb10781",
  • "itemId": {
    },
  • "currency": "EUR",
  • "location": {
    },
  • "priceModelId": "6245a8f578a8576e338fa9c3",
  • "restrictions": {
    },
  • "tierValues": [
    ],
  • "metadata": {
    }
}
Updating a price
Updates a specified price's details.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.




Required scopes


    

  • price.price_manage
    • 



SecurityOAuth2 
Request 
path Parameters
priceId
required
string
Price's unique identifier, generated when the price is created.


 
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
query Parameters
partial
required
boolean
Note: This parameter is only supported for legacy pricing. To use it, you need to set the X-Version header to v1 or not set it at all.






Value
Description





true
A partial update will be performed.




false
A full product replacement will be performed.





 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Content-Language
string
List of languages in which localized fields in the request body are provided.


    

  • 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 asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



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


 
Request Body schema: application/json
id
string
A price identifier.


 
object
Item for which the price is defined.


 
itemYrn
string
Product's uniform resource name.


 
currency
string
Currency code, as defined in the Currency Service.


 
object
 
object
 
priceModelId
string
ID of the price model to which the price is assigned.


 
object (restrictions) 
Restrictions that limit the validity of the price model and prices assigned to it.


 
Array of objects (tierValueRetrieval) 
 
mixins
object
Custom price attributes.


 
object (priceMetadata) 
 
object (priceModelExpand) 
Price model to which the price is assigned.


Note: This field is only returned if the extendWithPriceModel query param is set to true when retrieving a price by ID.


 
Responses 
200
The request was successful. The price has been updated.


400
Request was syntactically incorrect. Details are provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
The requested resource does not exist.


409
The request could not be completed due to a conflict with the current state of the target resource.


500
Some server-side error occurred. Details are provided in the response payload.


put/{tenant}/prices/{priceId}
Request samples 
application/json
{
  • "id": "62468170bddc000efeb10781",
  • "itemId": {
    },
  • "currency": "EUR",
  • "location": {
    },
  • "priceModelId": "6245a8f578a8576e338fa9c3",
  • "restrictions": {
    },
  • "tierValues": [
    ],
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Tenant in the header is not matching with the one provided in the URI."
}
Deleting a price
Deletes a specified price.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.




Required scopes


    

  • price.price_manage
    • 



SecurityOAuth2 
Request 
path Parameters
priceId
required
string
Price's unique identifier, generated when the price is created.


 
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Responses 
204
The request was successful. The price has been updated.


400
Request was syntactically incorrect. Details are provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
The requested resource does not exist.


500
Some server-side error occurred. Details are provided in the response payload.


delete/{tenant}/prices/{priceId}
Request samples 
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Tenant in the header is not matching with the one provided in the URI."
}
Prices assigned to price lists
Retrieving all prices assigned to a price list
Retrieves all prices assigned to a specified price list. You can filter the results with query parameters.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_read
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
query Parameters
pageNumber
integer  >= 1 
 Default:  1
Page number to be retrieved. The number of the first page is 1.


Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.


 
pageSize
integer  >= 1 
 Default:  60
Number of items to be retrieved per page.


 
sort
string
List of properties used to sort the results, separated by commas. The order of properties indicates their priority in sorting.


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
    • 



If the sorting direction is not specified, the fields are sorted in ascending order.


 
 Example:  sort=name,code:desc
priceModelId
string
ID of the price model to which the retrieved prices should be assigned.


 
itemId
string
IDs of products for which prices should be retrieved.


 
itemType
string
Item types for which prices should be retrieved. Possible values:


    

  • PRODUCT
    

    • 

  • SKU
    

    Note: The SKU value is a preview value - the system does not fully operate on the SKU concept yet.
    

    • 



 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as a map of single translation, where the key is a language code and the value is in a respective language.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved as maps of single translation, where the key is a language code and the value is in a respective language. The endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



 
X-Total-Count
boolean
 Default:  false
Flag indicating whether the total count of retrieved items should be returned.


 
Responses 
200
The request was successful. A list of prices is returned.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


get/{tenant}/price-lists/{priceListId}/prices
Request samples 
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Adding a new price to a price list
Creates a new price for a specified price list.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Request Body schema: application/json
required
object
Item for which the price is defined.


 
priceModelId
required
string
ID of the price model to which the price is assigned.


 
required
Array of objects
 
id
string
Custom price identifier. If not provided, it is automatically generated.


 
Responses 
201
The request was successful. The price has been created and added to the price list.


400
The request was incorrect. Details are provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


post/{tenant}/price-lists/{priceListId}/prices
Request samples 
application/json
{
  • "itemId": {
    },
  • "priceModelId": "6245a8f578a8576e338fa9c3",
  • "tierValues": [
    ]
}
Response samples 
application/json
{
  • "id": "6245a8f578a8576e338fa9c2"
}
Deleting multiple prices from a price list
Deletes multiple prices from a specified price list.


To indicate which prices should be deleted from the price list, you need to put their IDs in an array of strings and send it through the request body. The request body should look like this: ["exampleID1", "exampleID2"]


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Responses 
204
Price list's prices have successfully been deleted.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


delete/{tenant}/price-lists/{priceListId}/prices/bulk
Request samples 
Response samples 
application/json
{
  • "fault": {
    }
}
Creating multiple prices for a price list
Creates multiple prices for a specified price list.


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


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Request Body schema: application/json
 Array 
required
object
Item for which the price is defined.


 
priceModelId
required
string
ID of the price model to which the price is assigned.


 
required
Array of objects
 
id
string
Custom price identifier. If not provided, it is automatically generated.


 
Responses 
207
Multiple status response. The details are provided in a form of a list of responses within the body.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


post/{tenant}/price-lists/{priceListId}/prices/bulk
Request samples 
application/json
[
  • {
    },
  • {
    }
]
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Updating multiple prices in a price list
Updates multiple prices in a specified price list.


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


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Request Body schema: application/json
 Array 
id
required
string
Unique identifier of the price that belongs to a price list, generated when the price is created and added to the price list.


 
required
object
Item for which the price is defined.


 
priceModelId
required
string
ID of the price model to which the price is assigned.


 
required
Array of objects
 
required
object
 
Responses 
207
Multiple status response. The details are provided in a form of a list of responses within the body.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


put/{tenant}/price-lists/{priceListId}/prices/bulk
Request samples 
application/json
[
  • {
    },
  • {
    }
]
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Retrieving a price list's price details
Retrieves details for a specified price that belongs to a price list.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_read
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
priceId
required
string
Price list price's unique identifier, generated when the price list's price is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as a map of single translation, where the key is a language code and the value is in a respective language.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved as maps of single translation, where the key is a language code and the value is in a respective language. The endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



 
Responses 
200
The request was successful. The price list's price is returned.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
The requested price list's price could not be found.


500
Some server-side error occurred. Details are provided in the response payload.


get/{tenant}/price-lists/{priceListId}/prices/{priceId}
Request samples 
Response samples 
application/json
{
  • "id": "example-priceListPrice-id-1",
  • "itemId": {
    },
  • "priceModelId": "6245a8f578a8576e338fa9c3",
  • "tierValues": [
    ],
  • "metadata": {
    }
}
Updating a price in a price list
Updates a specified price list's price.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
priceId
required
string
Price list price's unique identifier, generated when the price list's price is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Content-Language
string
List of languages in which localized fields in the request body are provided.


    

  • 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, then the localized fields should be provided as a map of single translation, where the key is a language code and the value is in a respective language.
    • 

  • If the Content-Language header is empty, then the localized fields should be provided as maps of single translation, where the key is a language code and the value is in a respective language. The endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



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


 
Request Body schema: application/json
id
required
string
Unique identifier of the price that belongs to a price list, generated when the price is created and added to the price list.


 
required
object
Item for which the price is defined.


 
priceModelId
required
string
ID of the price model to which the price is assigned.


 
required
Array of objects
 
required
object
 
Responses 
204
The request was successful. The price list's price has been updated.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


404
The requested price list's price could not be found.


500
Some server-side error occurred. Details are provided in the response payload.


put/{tenant}/price-lists/{priceListId}/prices/{priceId}
Request samples 
application/json
{
  • "id": "example-priceListPrice-id-1",
  • "itemId": {
    },
  • "priceModelId": "6245a8f578a8576e338fa9c3",
  • "tierValues": [
    ],
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "fault": {
    }
}
Deleting a price from a price list
Deletes a specified price list's price.


This endpoint is available for the Price Service in version : v2. Make sure you send X-Version: v2 header.


Required scopes


    

  • price.pricelist_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
priceListId
required
string
Price list's unique identifier, generated when the price list is created.


 
priceId
required
string
Price list price's unique identifier, generated when the price list's price is created.


 
header Parameters
X-Version
string  [ 2 .. 3 ] characters ^v[1-9][0-9]?$
 Default:  v2
Version of the Price Service to which the request should be sent. Possible values:


    

  • v1
    • 

  • v2
    • 



 
Responses 
204
The request was successful. The price has been deleted from the price list.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details are provided in the response payload.


403
Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.


500
Some server-side error occurred. Details are provided in the response payload.


delete/{tenant}/price-lists/{priceListId}/prices/{priceId}
Request samples 
Response samples 
application/json
{
  • "fault": {
    }
}