Price Service Tutorials

How to set up your first price

Take a look at the relationships between prices and other resources in the Emporix Digital Commerce Platform. Click the diagram to enlarge it:

This tutorial will walk you through the following steps:

1. Specifying accepted currencies.
2. Creating a price model.
3. Retrieving a tier ID.
4. Defining a price.

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.

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

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

Define the price

How to implement different pricing strategies

Implementing any pricing strategy is a process made up of three steps:

1. Creating a PriceModel object through the Creating a price model endpoint.
2. Retrieving IDs of the model's pricing tiers through the Retrieving a price model endpoint.
3. Creating a Price object through the Creating a price endpoint.

Before you start

Make sure you have already finished the How to set up your first price tutorial.

Basic pricing

• Set the tierDefinition.tierType field to "BASIC".
• Add a single tier to the tiers array and set its quantity field to 0.

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"
        }
      }
    ]
  }
}

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

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"
        }
      }
    ]
  }
}

• 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 Digital Commerce Platform:

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 Digital Commerce Platform. Click the diagram to enlarge it:

Before you start

Make sure you have already finished the How to set up your first price tutorial.

Create a price list

Prices in a list can be expressed in a different currency than originally defined for the list's products.

Create a price in the list

Prices in lists are structured differently from catalog prices¹ — 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.

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 the targetCurrency through the Creating 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 to true.

To find out how the price matching functionality works in detail, check out the flowchart.

Click the diagram to enlarge it:

Influence of price lists on price matching

Price lists take precedence over catalog prices¹. 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. Click the diagram to enlarge it:

Before you start

Make sure you have already finished the How to set up your first price tutorial.

Create a product

Define 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

Check the best price for both one kilogram and ten kilograms of bananas:

How to calculate gross prices between countries

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.

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

Calculate the price for the desired country

How to retrieve a price in another currency

Before you start

Make sure you have already finished the How to set up your first price tutorial.

Add a new currency

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

Retrieve a price in the desired currency

How to configure a site to express all prices as net values

To retrieve prices as gross or net based on their sites' settings, you need to retrieve them with the price matching functionality.

You can manage your sites through the Emporix API Site Settings Service.

Update your site's includesTax field