Price matching

Matching prices for specific attributes

post

Finds the best price based on specified criteria.

To simplify, the price matching algorithm is made up of the following steps:

• All prices that match the specified criteria are fetched.

• A unified originalValue is calculated for each price.

• The price with the lowest effectiveValue is returned.

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 are 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 includesTax setting, defined at the site or price model level, determines if the algorithm returns net or gross prices. 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.

Required scopes

This endpoint requires the following scopes:

• : Needed to manage prices.
• : Needed to retrieve prices.

Authorizations

OAuth2

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Body

application/json

targetCurrencystringRequired

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.

siteCodestringRequired

Code of the site to which the matched prices should apply.

useFallbackbooleanOptional

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.

legalEntityIdstringOptional

Legal entity for which price lists are included in the price match. Note: Price lists for the entity's parent legal entities are also included.

Responses

200

OK

application/json

priceIdstringOptional

Price's unique identifier, generated when the price is created.

priceListIdstringOptional

Price list's unique identifier. The property is populated only in case when the return price belongs to any price list.

currencystringOptional

Currency related to the price.

originalValuenumberOptional

Represents an original value without any discounts for a single unit of the requested item (PRODUCT or SKU). The value is a gross price (if includesTax is true) or net price (if includesTax is false).

It's worth to mention that the cent part is not limited just to two digits. For example, if the price is for one piece of screw, it could look like this: 0.0000317

effectiveValuenumberOptional

Represents a value with a discount (if applicable) for a single unit of the requested item (PRODUCT or SKU). The value is a gross price (if includesTax is true) or net price (if includesTax is false).

It's worth to mention that the cent part is not limited just to two digits. For example, if the price is for one piece of screw, it could look like this: 0.0000317

totalValuenumberOptional

Represents a total value with a discount (if applicable) for all units of the requested item (PRODUCT or SKU). The value is a gross price (if includesTax is true) or net price (if includesTax is false).

It's worth to mention that the cent part is not limited just to two digits. For example, if the price is for one piece of screw, it could look like this: 0.0000317

includesTaxbooleanOptional

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.

400

Bad Request

application/json

401

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

application/json

403

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

application/json

404

Not Found

500

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

application/json

post

/price/{tenant}/match-prices

HTTPcURLJavaScriptPython

POST /price/{tenant}/match-prices HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 199

{
  "targetCurrency": "EUR",
  "siteCode": "1111",
  "targetLocation": {
    "countryCode": "DE"
  },
  "items": [
    {
      "itemId": {
        "itemType": "PRODUCT",
        "id": "5f5a3a365bac380024b93c45"
      },
      "quantity": {
        "quantity": 10,
        "unitCode": "kg"
      }
    }
  ]
}

{
  "priceId": "6245aa0a78a8576e338fa9c4",
  "itemId": {
    "itemType": "PRODUCT",
    "id": "5f5a3a365bac380024b93c45"
  },
  "site": {
    "code": "1111"
  },
  "currency": "EUR",
  "location": {
    "countryCode": "DE"
  },
  "originalValue": 13.55,
  "effectiveValue": 13.55,
  "totalValue": 1355,
  "quantity": {
    "quantity": 10,
    "unitCode": "kg"
  },
  "includesTax": true,
  "priceModel": {
    "id": "6245a8f578a8576e338fa9c3",
    "name": {
      "en": "Tiered in grams"
    },
    "includesTax": true,
    "includesMarkup": true,
    "measurementUnit": {
      "quantity": 0.1,
      "unitCode": "kg"
    },
    "tierDefinition": {
      "tierType": "TIERED",
      "tiers": [
        {
          "minQuantity": {
            "quantity": 0,
            "unitCode": "kg"
          }
        },
        {
          "minQuantity": {
            "quantity": 0.5,
            "unitCode": "kg"
          }
        },
        {
          "minQuantity": {
            "quantity": 5,
            "unitCode": "kg"
          }
        }
      ]
    },
    "metadata": {
      "version": 1,
      "createdAt": "2022-03-31T13:13:25.816Z",
      "modifiedAt": "2022-03-31T13:13:25.816Z"
    }
  },
  "tax": {
    "taxClass": "STANDARD",
    "taxRate": 20,
    "prices": {
      "originalValue": {
        "netValue": 10.84,
        "grossValue": 13.55,
        "taxValue": 2.71
      },
      "effectiveValue": {
        "netValue": 10.84,
        "grossValue": 13.55,
        "taxValue": 2.71
      },
      "totalValue": {
        "netValue": 1084,
        "grossValue": 1355,
        "taxValue": 271
      }
    }
  },
  "tierValues": [
    {
      "id": "04e9b68bc1ea4982a42247726239e7be",
      "priceValue": 15.55
    },
    {
      "id": "04e9b68bc1ea4982a42247726239e7be",
      "priceValue": 14.55
    },
    {
      "id": "04e9b68bc1ea4982a42247726239e7be",
      "priceValue": 13.55
    }
  ],
  "metadata": {
    "version": "1",
    "createdAt": "2022-03-31T13:18:02.379Z",
    "modifiedAt": "2022-03-31T13:18:02.379Z"
  }
}

Matching prices for session context

post

Finds the best price based on information retrieved from the session context.

The behavior of the logic is the same as of the price/{tenant}/match-prices 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).

Authorizations

CustomerAccessToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Body

application/json

Responses

200

The prices were successfully matched.

application/json

priceIdstringOptional

Price's unique identifier, generated when the price is created.

priceListIdstringOptional

Price list's unique identifier. The property is populated only in case when the return price belongs to any price list.

currencystringOptional

Currency related to the price.

originalValuenumberOptional

Represents an original value without any discounts for a single unit of the requested item (PRODUCT or SKU). The value is a gross price (if includesTax is true) or net price (if includesTax is false).

It's worth to mention that the cent part is not limited just to two digits. For example, if the price is for one piece of screw, it could look like this: 0.0000317

effectiveValuenumberOptional

Represents a value with a discount (if applicable) for a single unit of the requested item (PRODUCT or SKU). The value is a gross price (if includesTax is true) or net price (if includesTax is false).

It's worth to mention that the cent part is not limited just to two digits. For example, if the price is for one piece of screw, it could look like this: 0.0000317

totalValuenumberOptional

Represents a total value with a discount (if applicable) for all units of the requested item (PRODUCT or SKU). The value is a gross price (if includesTax is true) or net price (if includesTax is false).

It's worth to mention that the cent part is not limited just to two digits. For example, if the price is for one piece of screw, it could look like this: 0.0000317

includesTaxbooleanOptional

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.

400

Bad Request

application/json

401

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

application/json

403

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

application/json

404

Not Found

500

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

application/json

post

/price/{tenant}/match-prices-by-context

HTTPcURLJavaScriptPython

POST /price/{tenant}/match-prices-by-context HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 119

{
  "items": [
    {
      "itemId": {
        "itemType": "PRODUCT",
        "id": "5f5a39d95bac380024b93c24"
      },
      "quantity": {
        "quantity": 1,
        "unitCode": "kg"
      }
    }
  ]
}

{
  "priceId": "6245aa0a78a8576e338fa9c4",
  "itemId": {
    "itemType": "PRODUCT",
    "id": "5f5a3a365bac380024b93c45"
  },
  "site": {
    "code": "1111"
  },
  "currency": "EUR",
  "location": {
    "countryCode": "DE"
  },
  "originalValue": 13.55,
  "effectiveValue": 13.55,
  "totalValue": 1355,
  "quantity": {
    "quantity": 10,
    "unitCode": "kg"
  },
  "includesTax": true,
  "priceModel": {
    "id": "6245a8f578a8576e338fa9c3",
    "name": {
      "en": "Tiered in grams"
    },
    "includesTax": true,
    "includesMarkup": true,
    "measurementUnit": {
      "quantity": 0.1,
      "unitCode": "kg"
    },
    "tierDefinition": {
      "tierType": "TIERED",
      "tiers": [
        {
          "minQuantity": {
            "quantity": 0,
            "unitCode": "kg"
          }
        },
        {
          "minQuantity": {
            "quantity": 0.5,
            "unitCode": "kg"
          }
        },
        {
          "minQuantity": {
            "quantity": 5,
            "unitCode": "kg"
          }
        }
      ]
    },
    "metadata": {
      "version": 1,
      "createdAt": "2022-03-31T13:13:25.816Z",
      "modifiedAt": "2022-03-31T13:13:25.816Z"
    }
  },
  "tax": {
    "taxClass": "STANDARD",
    "taxRate": 20,
    "prices": {
      "originalValue": {
        "netValue": 10.84,
        "grossValue": 13.55,
        "taxValue": 2.71
      },
      "effectiveValue": {
        "netValue": 10.84,
        "grossValue": 13.55,
        "taxValue": 2.71
      },
      "totalValue": {
        "netValue": 1084,
        "grossValue": 1355,
        "taxValue": 271
      }
    }
  },
  "tierValues": [
    {
      "id": "04e9b68bc1ea4982a42247726239e7be",
      "priceValue": 15.55
    },
    {
      "id": "04e9b68bc1ea4982a42247726239e7be",
      "priceValue": 14.55
    },
    {
      "id": "04e9b68bc1ea4982a42247726239e7be",
      "priceValue": 13.55
    }
  ],
  "metadata": {
    "version": "1",
    "createdAt": "2022-03-31T13:18:02.379Z",
    "modifiedAt": "2022-03-31T13:18:02.379Z"
  }
}