Price Service Tutorials
How to set up your first price
Take a look at the relationships between prices and other resources in the Emporix Commerce Engine.
This tutorial will walk you through the following steps:
info
The tutorial skips the step of creating a new measurement unit as your Emporix tenant is configured with the most commonly used measurement units out-of-the-box.
To learn more about measurement units in the Emporix Commerce Engine, check out the Measurement units guide.
Specify accepted currencies
Each currency accepted by your business is stored as a separate object that can be managed through the Emporix API Currency Service.
To add a new entry to your configuration of currencies, you need to send a request to theCreate a price model
A price model defines a repeatable way to sell products. You can create separate price models depending on measurement units for which prices are expressed or depending on products' pricing strategies.
info
To learn more about price models in the Emporix Commerce Engine, check out the Pricing guide.
Retrieve a tier ID
When specifying a price for a product, you need to reference two values from a corresponding price model:
- ID of the price model
- ID of the model's relevant pricing tier
tierDefinition.tiers.id
field. Define the price
To define a new price for a product, you need to send a request to theHow to implement different pricing strategies
info
To learn more about pricing strategies available in the Emporix Commerce Engine, check out the Pricing guide.
Implementing any pricing strategy is a process made up of three steps:
- Creating a
PriceModel
object through theCreating a price model endpoint. - Retrieving IDs of the model's pricing tiers through the
Retrieving a price model endpoint. - Creating a
Price
object through theCreating a price endpoint.
Before you start
Make sure you have already finished the How to set up your first price tutorial.
Basic pricing
To define basic pricing in aPriceModel
object, you need to perform the following actions:- Set the
tierDefinition.tierType
field to"BASIC"
. - Add a single tier to the
tiers
array and set itsquantity
field to0
.
Here's an example of a request body for a basic price model:
{
"name": "Basic pricing - per piece.",
"description": "Basic price model for goods sold by the piece.",
"includesTax": true,
"includesMarkup": false,
"measurementUnit": {
"quantity": 1,
"unitCode": "pc"
},
"tierDefinition": {
"tierType": "BASIC",
"tiers": [
{
"minQuantity": {
"quantity": 0,
"unitCode": "pc"
}
}
]
}
}
Price
object for basic pricing, you need to perform the following actions:- Set the
priceModelId
field to the basic price model's ID. - Retrieve the price model's
tierDefinition.tiers.id
value. - Add a single object to the
tierValues
array.
Here's an example of a request body for a basic price:
{
"itemId": {
"itemType": "PRODUCT",
"id": "624c3a5c3c4f072b9460bb7a"
},
"currency": "EUR",
"location": {
"countryCode": "DE"
},
"priceModelId": "624c28503406122baacc7e92",
"restrictions": {
"validity": {
"from": "2022-04-01T00:00:00Z"
},
"siteCodes": [
"main"
]
},
"tierValues": [
{
"id": "425e4055-1720-4933-a789-6076a455f255",
"priceValue": "629.00"
}
]
}
Tiered and volume pricing
To create a price model for tiered or volume pricing, you need to perform the following actions:
- Set the
tierDefinition.tierType
field to"TIERED"
or"VOLUME"
, respectively. - Define quantities for pricing tiers in the
tiers
array.
warning
PriceModel
object:- Each
minQuantity.quantity
field must contain a unique value. - The tiers must be defined in an ascending order based on their
quantity
value. - The
quantity
field in the first tier must be set to0
. - All
unitCode
fields must contain the same value.
Here are examples of request bodies for tiered and volume price model:
{
"name": "Tiered pricing - per kilogram",
"description": "Tiered price model for goods sold by the kilogram.",
"includesTax": true,
"includesMarkup": false,
"measurementUnit": {
"quantity": 1,
"unitCode": "kg"
},
"tierDefinition": {
"tierType": "TIERED",
"tiers": [
{
"minQuantity": {
"quantity": 0,
"unitCode": "kg"
}
},
{
"minQuantity": {
"quantity": 5,
"unitCode": "kg"
}
},
{
"minQuantity": {
"quantity": 10,
"unitCode": "kg"
}
}
]
}
}
{
"name": "Volume pricing - per 100 gram",
"description": "Volume price model for goods sold by 100 gram.",
"includesTax": true,
"includesMarkup": false,
"measurementUnit": {
"quantity": 100,
"unitCode": "g"
},
"tierDefinition": {
"tierType": "VOLUME",
"tiers": [
{
"minQuantity": {
"quantity": 0,
"unitCode": "g"
}
},
{
"minQuantity": {
"quantity": 500,
"unitCode": "g"
}
},
{
"minQuantity": {
"quantity": 1000,
"unitCode": "g"
}
}
]
}
}
Price
object for tiered or volume pricing, you need to perform the following actions:- Set the
priceModelId
field to the corresponding price model's ID. - Retrieve the price model's
tierDefinition.tiers.id
values. - Add an object for each tier to the
tierValues
array.
Here's an example of a request body for a tiered and volume-based price:
{
"itemId": {
"itemType": "PRODUCT",
"id": "624c3a5c3c4f072b9460bb7a"
},
"currency": "EUR",
"location": {
"countryCode": "DE"
},
"restrictions": {
"validity": {
"from": "2022-04-01T00:00:00.000Z"
},
"siteCodes": [
"main"
]
},
"priceModelId": "624ec1b03406122baacc7e94",
"tierValues": [
{
"id": "bad42e2f-37d1-49df-8ad9-1045e4c09e9b",
"priceValue": "3.00"
},
{
"id": "474fb617-02f7-47d2-91a6-a4a602b73518",
"priceValue": "2.00"
},
{
"id": "7b819c35-2dc6-4a27-ae1d-2a4d7dc1d5b1",
"priceValue": "1.00"
}
]
}
How to personalize prices
Take a look at the relationship between prices and customers in the Emporix Commerce Engine:
principals
array inside an applicable Price
object.info
Customer
objects are managed through the Emporix API Customer Service.Here's an example of a customer-restricted price:
{
"itemId": {
"itemType": "PRODUCT",
"id": "5f5a1fe55bac380024b936ad"
},
"currency": "EUR",
"location" : {
"countryCode": "DE"
},
"priceModelId": "624db246d2730b6011dbfd74",
"restrictions": {
"principals": [
{
"type": "CUSTOMER",
"id": "71842741" // customer's ID generated by the Customer Service
}
],
"siteCodes": [
"main"
]
},
"tierValues": [
{
"id": "7b819c35-2dc6-4a27-ae1d-2a4d7dc1d5b1",
"priceValue": "2.34"
}
]
}
How to configure a price list
Price lists allow you to create personalized sets of prices for selected products. You can manage price lists and their prices through the Emporix API Price Service.
Take a look at the relationships between price lists and other resources in the Emporix Commerce Engine.
attention
Countries and regions are predefined in the Emporix API Country Service. You can check which countries and regions are available by sending requests to the following endpoints:
Before you start
Make sure you have already finished the How to set up your first price tutorial.
Create a price list
Price lists are site-specific. You can restrict a price list to particular groups of customers with thecountries
, regions
, and customerGroups
fields, and make the list time-limited with the validity
field.Prices in a list can be expressed in a different currency than originally defined for the list's products.
To create a new price list, you need to send a request to thewarning
currency
field in the request body. Otherwise, the endpoint will respond with a 400
error.Create a price in the list
Prices in lists are structured differently from catalog prices1 — while each catalog price can be personalized on its own, the validity of all prices in a list is determined by the list's restrictions. A price in a price list needs to reference a relevant product, price model, and pricing tiers.
warning
includesTax
value in their indicated price models.Bulk price creation
How to use the price matching functionality
The price matching functionality compares all prices defined for specified products and retrieves the best ones based on a set of criteria. The criteria include:
targetCurrency
— Currency in which the prices should be returned.warning
If you want the price matching functionality to compare prices expressed in multiple currencies, you need to define exchange rates between these currencies and thetargetCurrency
through theCreating a new exchange rate endpoint.siteCode
— Site for which the prices will be matched. The price matching functionality will only compare prices assigned to this site.targetLocation
— Country for which the prices should be returned.items
— List of products (and their quantities) for which the prices should be compared.principal
— Customer to whom the prices should apply. When specified, the price matching functionality will compare both non-personalized prices as well as the ones offered exclusively to the specified customer.useFallback
— 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 totrue
.
Prices are stored in the system as defined in the price model, with no initial net or gross calculations. Calculations occur during the PriceMatch and PriceSearch algorithms. However, PriceSearch is related to catalog prices only.
TheincludesTax
setting, defined at the site or price model level, determines if the algorithm returns net or gross prices. The tax service then manages specific cases:- Gross to Net: Returns a net price from a gross price for a specific country.
- Net to Gross: Converts a net price to a gross price using a country's specific tax class.
- Gross to Gross: Adjusts a gross price between countries by first converting to net, then applying the destination country's tax class.
To find out how the price matching functionality works in detail, check out the flowchart.
attention
The process shown in the flowchart is repeated for each product indicated in the request.
To find out how the price matching functionality works in detail, check out the flowchart.
info
To check out the flowchart for the Look for the best price in price lists subprocess, check out the Influence of price lists on price matching section.
Influence of price lists on price matching
Price lists take precedence over catalog prices1. If there are price lists that match the request criteria, the price matching algorithm checks whether these lists contain prices for requested products before searching through catalog prices.
To find out how the price matching functionality handles price lists, check out the flowchart.
Before you start
Make sure you have already finished the How to set up your first price tutorial.
Create a product
Create a sample product through theDefine multiple prices
Now, define a couple of prices that the price matching functionality will be able to compare.
Start with defining a price model where the bananas' price per kilogram is constant regardless of the ordered quantity:
Now, retrieve the automatically-generated ID of the pricing tier:
Once you know the tier ID, define a price for the bananas:
Then, define a price model where the price per kilogram changes based on the ordered quantity:
Now, retrieve the automatically-generated IDs of the pricing tiers:
Once you know the tier IDs, define another price for the bananas.
Find the best price
Now that you have defined multiple prices for the bananas, you can send a request to theCheck the best price for both one kilogram and ten kilograms of bananas:
priceId
fields. The total price for defined quantities is returned in the totalValue
fields.How to calculate gross prices between countries
You can calculate gross prices between countries through theinfo
Price
objects.To learn how to calculate gross prices between countries based on specific values, check out How to calculate gross values between countries tutorial in the Tax classes — Developer Guide.
Before you start
Make sure you have already finished the How to set up your first price tutorial.
Define sales tax rates for the desired country
Gross prices between countries are calculated based on these countries' sales tax rates.
Define sales tax rates for the desired country by sending a request to theUpdate the product's tax classes
When calculating a gross price for another country, the price matching functionality checks tax classes assigned to the product that the original price is defined for.
To update a product with applicable tax classes, send a request to theCalculate the price for the desired country
To calculate a gross price between countries, send a request to thetotalValue
field.How to retrieve a price in another currency
You can calculate a price's value in another currency through theBefore you start
Make sure you have already finished the How to set up your first price tutorial.
Add a new currency
Add the currency in which the price will be retrieved to your configuration of currencies by sending a request to theDefine a currency exchange rate
When calculating a price in another currency, the price matching functionality checks the defined exchange rate between the desired currency and the one in which price is originally expressed.
Important
Currently, the exchange rates are defined statically and are not influenced by actual currency exchange rates. If you want the statically defined exchange rates to reflect the actual rates more closely, you will need to manually update these on a regular basis.
Retrieve a price in the desired currency
To retrieve a price in the desired currency, send a request to thetotalValue
field.How to configure a site to express all prices as net values
When you retrieve prices through theincludesTax
value specified in these prices' models.To retrieve prices as gross or net based on their sites' settings, you need to retrieve them with the price matching functionality.
To always retrieve prices for a particular site as net values, you need to set that site'sincludesTax
field to false
.attention
includesTax
value, the price matching functionality will return a price as gross or net based on the includesTax
value specified in the price's model.You can manage your sites through the Emporix API Site Settings Service.
Update your site's includesTax
field
To add or update the includesTax
field in your site's settings, you need to send a request to the - Prices defined for products in
Price
objects, as opposed toPriceListPrice
objects.