Understanding tariffs

This page details how tariffs are handled at SupplierXM and how to use them in the APIs.

This page explains what tariffs are, how they're structured, and what statuses they can have.

What is a tariff?

A tariff is an entity that holds both price information and information linking it to one or more products.
Tariff structure

Tariff structure

A tariff is an entity composed of two elements:
Tariff-specific data: a set of attributes defining the general conditions of the tariff such as the name, the start and end dates, the currency, etc.

      "status": "PUBLISHED",
      "name": "Tariff 2021",
      "sourceOrganization": {
        "nameLegal": "Manufacturer A"
      "data": {
      	"orderStartDate": "2021-01-01",
      	"orderEndDate": "2021-12-31",
      	"targetCountryList": [{"targetCountryCode": {"code": "FR"}}],
      	"incotermCode": {"code": "EXW"},
      	"tariffNumber": "df5gdf",
      	"tariffCurrency": {"code": "EUR"},
      	"priceWaterfallBasisQuantityNumber": [{"data": 1, "expressedIn": {"code": "BX"}}],
      	"priceWaterfalls": [{
        	"bracketUnit": {"code": "ctn"},
          "brackets": [{"min": 1}, {"min": 10}]
  • Information about one or multiple products linked to the tariff: these are all the products included in the tariff.
    "gtin": "01234567891231",
    "supplierId": "123456",
    "data": {
      "contractNumber": "1234-12345-12",
      "hierarchyProduct": {
        "gtin": "11234567891238"
      "priceWaterfalls": [{
        "brackets": [{
          "min": 1
        }, {
          "min": 10
        "levels": [{
          "items": [{
            "values": [{
              "value": "10"
            }, {
              "value": "9"

Tariff Lifecycle


When a tariff is created, its status is set to DRAFT.
Once the tariff is considered ready, it can be set to PUBLISHED. After the tariff is published, it can be ACCEPTED or REJECTED.

Here is a more detailed description of each status:

When a tariff is created, its status is set to DRAFT. The tariff and any associated listings are not shared.

Once the tariff is considered ready, it can be published. Publishing a tariff also publishes and synchronizes all the products linked to this tariff. Before publishing a tariff, every linked product must be validated and shared. Note: Once a tariff has been published, its data (except the end date) can no longer be updated.

A retailer can reject a tariff so the manufacturer can update it.
The retailer must add a message explaining the rejection reason.
An event is generated for each user in the manufacturer organization, so they can receive an email about the tariff rejection.
Manufacturers can update a rejected tariff (tariff-specific data and linked products) and republish it.
Updates are not visible from the retailer side except the end date.
The rejection reasons are visible in the status history of the tariff.

Tariffs with this status can be exported by retailers to their systems.

A tariff is set to ARCHIVED as soon as the end date is in the past.

What’s Next

These sections document all the endpoints that allow interaction with tariff information: