> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/pricing-advisor-api/pricing-advisor-api/use-cases-1.md).

# Use Cases

Six end-to-end scenarios covering how the Pricing Advisor API could be used — from building forward-priced international storefronts through checkout landed-cost calculations, multi-market price sheet generation, and new country launch validation.

***

{% hint style="info" icon="chart-mixed" %}

#### USE CASE 1

{% endhint %}

## Forward Pricing for International Storefront

A fashion retailer "NOVA" sells products priced in GBP. They need to display accurate forward prices in EUR to German shoppers, incorporating FX rates, estimated duties, taxes, and retailer adjustments — all in a single multiplier value.

APIs Involved: `MultiplierAdvice GET` (by country) — `MultiplierAdvice GET` (all countries)

Outcome: GBP base prices converted into shopper-facing EUR prices including duties, taxes, and rounding rules.

{% stepper %}
{% step %}

#### Fetch multiplier advice for Germany 

Retrieve the latest multiplier pricing advice for the DE (Germany) market. The response contains category-level multipliers that bundle FX conversion, estimated duty, estimated tax, and the retailer's own price adjustment into a single factor.

`GET /api/4.0/MultiplierAdvice/novafx/DE`

<table><thead><tr><th width="190">Parameter</th><th width="146">Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>tenantCode</code></td><td>required</td><td>Six-letter tenant identifier</td></tr><tr><td><code>countryIso</code></td><td>required</td><td>ISO 3166 delivery country code</td></tr></tbody></table>

<mark style="color:$success;">`200`</mark> OK— MultiplierAdviceResponse

{% code expandable="true" %}

```json
{
  "id": "ma-novafx-de-20260305",
  "version": "47",
  "countryIso": "DE",
  "lastUpdated": "2026-03-05T06:00:00Z",
  "tenantIdentifier": "novafx",
  "categories": [{
    "id": "ApparelAccessories",
    "multipliers": [{
      "fromCurrencyIso": "GBP",
      "toCurrencyIso": "EUR",
      "value": 1.4523,
      "adjustedValue": 1.3187
    }],
    "roundingConfigurations": [{
      "currencyIso": "EUR",
      "currencyExponent": 2,
      "direction": "Up",
      "model": "NineNinety"
    }],
    "currencyDisplays": [{
      "currencyIso": "EUR",
      "currencySymbol": "€",
      "currencyExponent": 2,
      "decimalSeparator": ",",
      "thousandSeparator": ".",
      "showTrailingZeros": true,
      "configurationString": "€{0}"
    }]
  }]
}
```

{% endcode %}
{% endstep %}

{% step %}

#### Apply the multiplier to a base product price

{% endstep %}
{% endstepper %}

***

{% hint style="warning" icon="abacus" %}

### USE CASE 2

{% endhint %}

## Checkout Landed-Cost Calculation

A shopper in Japan `JP` is purchasing a leather handbag from a US-based retailer "LUXBAG". The checkout engine needs the exact breakdown of duty, tax, fees, and FX rates to present an accurate landed cost before payment.

APIs Involved: `StandardAdvice GET` (by country) — `StandardAdvice GET` (archived)

Outcome: Itemized duty, tax, fee, FX rates, and retailer adjustment returned per product category for accurate checkout total.

{% stepper %}
{% step %}

#### Fetch standard pricing advice for Japan — StandardAdvice

Retrieve the full pricing advice breakdown for JP. Unlike the multiplier endpoint, standard advice returns each cost component separately — estimated duty, tax, fees, FX rates, and retailer adjustment — enabling a fully transparent cost breakdown at checkout.

`GET /api/4.0/StandardAdvice/luxbag/JP`

<table><thead><tr><th width="173">Parameter</th><th width="132">Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>tenantCode</code></td><td>required</td><td>Six-letter tenant identifier</td></tr><tr><td><code>countryIso</code></td><td>required</td><td>ISO 3166 delivery country</td></tr></tbody></table>

<mark style="color:$success;">`200`</mark>`OK`— PricingAdviceResponse

{% code expandable="true" %}

```json
{
  "id": "pa-luxbag-jp-20260305",
  "version": "112",
  "countryIso": "JP",
  "lastUpdated": "2026-03-05T04:30:00Z",
  "tenantIdentifier": "luxbag",
  "fxRates": [{
    "from": "USD",
    "to": "JPY",
    "rate": 149.82
  }],
  "categories": [{
    "id": "LeatherGoods",
    "estimatedDuty": 0.10,
    "estimatedTax": 0.10,
    "estimatedFee": 0.02,
    "retailerAdjustment": 0.05,
    "roundingConfigurations": [{
      "currencyIso": "JPY",
      "currencyExponent": 0,
      "direction": "Up",
      "model": "Standard"
    }],
    "currencyDisplays": [{
      "currencyIso": "JPY",
      "currencySymbol": "¥",
      "currencyExponent": 0,
      "decimalSeparator": ".",
      "thousandSeparator": ",",
      "showTrailingZeros": false,
      "configurationString": "¥{0}"
    }]
  }],
  "merchandisePricingModel": {
    "id": "ExclusiveOfTaxAndDuty",
    "applicableRates": ["estimatedDuty", "estimatedTax", "estimatedFee"]
  }
}
```

{% endcode %}
{% endstep %}

{% step %}

#### Compute itemized landed cost at checkout&#x20;

{% endstep %}
{% endstepper %}

***

{% hint style="info" icon="file-spreadsheet" %}

#### USE CASE 3 <a href="#multi-country-price-sheet-generation" id="multi-country-price-sheet-generation"></a>

{% endhint %}

## Multi-Country Price Sheet Generation <a href="#multi-country-price-sheet-generation" id="multi-country-price-sheet-generation"></a>

A merchandising team at retailer "STRIDE" needs to generate a weekly price sheet comparing product prices across all active delivery countries — for internal review, shopping feeds, and affiliate partners.

**APIs Involved:** `MultiplierAdvice GET (all countries) StandardAdvice GET (all countries)`

**Outcome:** Complete price matrix across all active countries with per-category multipliers and FX rates exported to a spreadsheet.

Outcome\
Complete price matrix across all active countries with per-category multipliers and FX rates exported to a spreadsheet.

{% stepper %}
{% step %}

#### Retrieve all multiplier advice for the brand — MultiplierAdvice GET all

Fetch every active country's multiplier pricing advice in a single call. This returns an array of `MultiplierAdviceResponse` objects — one per delivery country that the retailer has configured.

`GET /api/4.0/MultiplierAdvice/stride`

<table><thead><tr><th>Parameter</th><th width="187">Type</th><th>Notes</th></tr></thead><tbody><tr><td><code>tenantCode</code></td><td>required</td><td>Six-letter tenant identifier</td></tr></tbody></table>

<mark style="color:$success;">`200`</mark>`OK`— Array of MultiplierAdviceResponse

{% code expandable="true" %}

```json
[
  {
    "id": "ma-stride-de-20260305",
    "version": "83",
    "countryIso": "DE",
    "lastUpdated": "2026-03-05T06:00:00Z",
    "tenantIdentifier": "stride",
    "categories": [/* ... */]
  },
  {
    "id": "ma-stride-us-20260305",
    "countryIso": "US",
    "categories": [/* ... */]
  },
  {
    "id": "ma-stride-jp-20260305",
    "countryIso": "JP",
    "categories": [/* ... */]
  },
  // ... 42 more countries
]
```

{% endcode %}

{% hint style="info" %}
This endpoint returns ALL active countries in one response. For a retailer with 45 countries, you receive 45 objects. Use this to build a complete price matrix without making 45 individual calls.
{% endhint %}
{% endstep %}

{% step %}

#### Cross-reference with standard advice for detailed rate breakdown — StandardAdvice GET all

For the price sheet, the team also wants the raw duty/tax/fee breakdown alongside the multiplier. Fetch all standard advice to pair with the multiplier data.

`GET /api/4.0/StandardAdvice/stride`

<mark style="color:$success;">`200 OK`</mark>— Array of PricingAdviceResponse

{% code expandable="true" %}

```json
[
  {
    "id": "pa-stride-de-20260305",
    "countryIso": "DE",
    "fxRates": [{ "from": "GBP", "to": "EUR", "rate": 1.1732 }],
    "categories": [{
      "id": "Footwear",
      "estimatedDuty": 0.12,
      "estimatedTax": 0.19,
      "estimatedFee": 0.01,
      "retailerAdjustment": 0.03
    }],
    "merchandisePricingModel": {
      "id": "InclusiveOfTax",
      "applicableRates": ["estimatedDuty", "estimatedFee"]
    }
  },
  // ... remaining countries
]
```

{% endcode %}

{% hint style="warning" %}
Note the `merchandisePricingModel` for DE is "InclusiveOfTax" — meaning VAT is already in the GBP base price. The `applicableRates` array only lists duty and fee. Do NOT add `estimatedTax` again on top.
{% endhint %}
{% endstep %}

{% step %}

#### Build the price matrix&#x20;

{% endstep %}
{% endstepper %}

***

{% hint style="warning" %}

#### USE CASE 4

{% endhint %}

## Pricing Advice Audit & Version Comparison <a href="#pricing-advice-audit-and-version-comparison" id="pricing-advice-audit-and-version-comparison"></a>

The finance team at retailer "GLAM" noticed that product prices for France (FR) changed overnight. They need to retrieve the specific archived pricing advice version that was active during yesterday's orders and compare it to today's version to understand the delta.

APIs Involved: `StandardAdvice GET (by country)` — `StandardAdvice GET (archived by ID)` — `MultiplierAdvice GET (archived by ID)`

Outcome: Root cause identified: FX rate shift from `1.1694 to 1.1732 EUR/GBP` caused a `0.3%` price increase across all FR product prices.

{% stepper %}
{% step %}

#### Fetch the current (latest) pricing advice for France — StandardAdvice

Get today's pricing advice to establish the current baseline. Note the `id` and `version` fields — these are needed to identify the exact snapshot.

`GET /api/4.0/StandardAdvice/glamhq/FR`

<mark style="color:$success;">`200`</mark>` ``OK`— PricingAdviceResponse (current)

{% code expandable="true" %}

```json
{
  "id": "pa-glamhq-fr-20260305",
  "version": "89",
  "countryIso": "FR",
  "lastUpdated": "2026-03-05T06:00:00Z",
  "fxRates": [{ "from": "GBP", "to": "EUR", "rate": 1.1732 }],
  "categories": [{
    "id": "Cosmetics",
    "estimatedDuty": 0.065,
    "estimatedTax": 0.20,
    "estimatedFee": 0.015,
    "retailerAdjustment": 0.04
  }]
}
```

{% endcode %}

{% endstep %}

{% step %}

#### Retrieve the archived version from yesterday — StandardAdvice archived

Using the archived endpoint, pass the known ID of yesterday's pricing advice snapshot (from order records or internal logs). This returns the exact pricing advice that was active when yesterday's orders were placed.

`GET /api/4.0/StandardAdvice/pa-glamhq-fr-20260304/archived`

| Parameter | Type     | Notes                                              |
| --------- | -------- | -------------------------------------------------- |
| `id`      | required | The exact ID of the archived pricing advice entity |

<mark style="color:$success;">`200`</mark>`OK`— PricingAdviceResponse (archived)

{% code expandable="true" %}

```json
{
  "id": "pa-glamhq-fr-20260304",
  "version": "88",
  "countryIso": "FR",
  "lastUpdated": "2026-03-04T06:00:00Z",
  "fxRates": [{ "from": "GBP", "to": "EUR", "rate": 1.1694 }],
  "categories": [{
    "id": "Cosmetics",
    "estimatedDuty": 0.065,
    "estimatedTax": 0.20,
    "estimatedFee": 0.015,
    "retailerAdjustment": 0.04
  }]
}
```

{% endcode %}
{% endstep %}

{% step %}

#### Diff the two versions to identify the change

{% endstep %}

{% step %}

#### Also compare the multiplier versions for the same period — MultiplierAdvice archived

If the storefront uses multiplier-based pricing, also compare the archived multiplier to confirm the combined multiplier value shifted in line with the FX change.

`GET /api/4.0/MultiplierAdvice/ma-glamhq-fr-20260304/archived`

<mark style="color:$success;">`200`</mark>`OK`— MultiplierAdviceResponse (archived)

{% code expandable="true" %}

```json
{
  "id": "ma-glamhq-fr-20260304",
  "version": "88",
  "categories": [{
    "id": "Cosmetics",
    "multipliers": [{
      "fromCurrencyIso": "GBP",
      "toCurrencyIso": "EUR",
      "value": 1.5429,
      "adjustedValue": 1.3991
    }]
  }]
}
```

{% endcode %}
{% endstep %}
{% endstepper %}

***

{% hint style="info" icon="shop" %}

#### USE CASE 5

{% endhint %}

## New Market Launch Pricing Validation

Retailer "ZENITH" is expanding into South Korea (KR) and Brazil (BR). Before going live, the operations team needs to validate that pricing advice is correctly configured for both new countries — checking that FX rates, duty estimates, tax rates, and rounding rules all return valid data.

APIs Involved: `StandardAdvice GET (by country)` — `MultiplierAdvice GET (by country)` — `MultiplierAdvice GET (all)`

Outcome: South Korea (KR) validated and cleared for launch. Brazil (BR) flagged with missing category data — blocked until resolved.

{% stepper %}
{% step %}

#### Check that Standard Advice exists for South Korea — StandardAdvice

Query the standard advice endpoint for KR. A 200 response confirms pricing advice has been generated. A 404 means the country has not been configured yet in the Pricing Advisor system.

`GET /api/4.0/StandardAdvice/zenith/KR`

<mark style="color:$success;">`200`</mark>` ``OK`— PricingAdviceResponse

{% code expandable="true" %}

```json
{
  "id": "pa-zenith-kr-20260305",
  "version": "1",
  "countryIso": "KR",
  "lastUpdated": "2026-03-05T06:00:00Z",
  "fxRates": [{ "from": "GBP", "to": "KRW", "rate": 1742.56 }],
  "categories": [
    { "id": "ApparelAccessories", "estimatedDuty": 0.13, "estimatedTax": 0.10, "estimatedFee": 0.01, "retailerAdjustment": 0.05 },
    { "id": "Electronics", "estimatedDuty": 0.08, "estimatedTax": 0.10, "estimatedFee": 0.01, "retailerAdjustment": 0.03 },
    { "id": "Cosmetics", "estimatedDuty": 0.08, "estimatedTax": 0.10, "estimatedFee": 0.015, "retailerAdjustment": 0.04 }
  ],
  "merchandisePricingModel": {
    "id": "ExclusiveOfTaxAndDuty",
    "applicableRates": ["estimatedDuty", "estimatedTax", "estimatedFee"]
  }
}
```

{% endcode %}
{% endstep %}

{% step %}

#### Verify multiplier advice also exists for South Korea — MultiplierAdvice

If the storefront uses multiplier-based pricing, also confirm the multiplier advice is generated for KR. Both standard and multiplier advice must be available for a complete launch.

`GET /api/4.0/MultiplierAdvice/zenith/KR`

<mark style="color:$success;">`200`</mark>` ``OK`— MultiplierAdviceResponse

{% code expandable="true" %}

```json
{
  "id": "ma-zenith-kr-20260305",
  "version": "1",
  "countryIso": "KR",
  "categories": [{
    "id": "ApparelAccessories",
    "multipliers": [{
      "fromCurrencyIso": "GBP",
      "toCurrencyIso": "KRW",
      "value": 2244.12,
      "adjustedValue": 2244.12
    }]
  }]
}
```

{% endcode %}
{% endstep %}

{% step %}

#### Check Brazil — discover missing configuration — StandardAdvice

Repeat the same validation for BR. This time the API returns a 404, indicating that pricing advice has not yet been generated for Brazil.

`GET /api/4.0/StandardAdvice/zenith/BR`

<mark style="color:$danger;">`404`</mark>` ``Not Found`— ProblemDetails

{% code expandable="true" %}

```json
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "No pricing advice found for tenant 'zenith' and country 'BR'."
}
```

{% endcode %}

{% hint style="danger" %}
If Brazil (BR) is NOT configured. The operations team must request BR to be onboarded in the Pricing Advisor system before the country can go live. Do NOT launch without pricing advice — shoppers would see incorrect or zero prices.
{% endhint %}
{% endstep %}

{% step %}

#### Confirm KR appears in the full brand country list — MultiplierAdvice GET all

As a final validation step, fetch the full list of multiplier advice for the brand and confirm KR appears in the array alongside all existing countries. This ensures the new country is visible across all downstream systems that consume the "all countries" endpoint.

`GET /api/4.0/MultiplierAdvice/zenith`

<mark style="color:$success;">`200`</mark>` ``OK`— Array of MultiplierAdviceResponse

{% code expandable="true" %}

```json
[
  { "countryIso": "DE", "version": "47" },
  { "countryIso": "US", "version": "52" },
  { "countryIso": "JP", "version": "39" },
  { "countryIso": "FR", "version": "44" },
  { "countryIso": "KR", "version": "1" },
  // ... other countries
  // BR is NOT in this list (expected — not yet configured)
]
```

{% endcode %}
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.esw.com/pricing-advisor-api/pricing-advisor-api/use-cases-1.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.