> 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/resources/tutorials/multiplier-pricing-advice.md).

# Multiplier Pricing Advice

{% hint style="info" icon="rocket-launch" %}

### Prerequisites

* A valid Bearer JWT token
* Your `tenantCode` — the brand identifier used throughout the platform
* Familiarity with [Tutorial 1](/pricing-advisor-api/resources/tutorials/standard-pricing-advice.md) — Standard Pricing Advice is helpful but not required
  {% endhint %}

***

{% tabs %}
{% tab title="Code Walkthrough" %}
{% @code-walkthrough/code-walkthrough title="Sample Response" language="json" filename="Multiplier Pricing Advice" code="{
// Store this ID for audit/archived retrieval
"id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",

// Compare against cached version to detect changes
"version": "17",

"tenantIdentifier": "my-brand-001",
"countryIso": "JP",
"lastUpdated": "2025-03-14T10:30:00Z",

"categories": \[
{
// Match this to your product's category field
"id": "ApparelAccessories",

```
  "multipliers": [
    {
      "fromCurrencyIso": "EUR",   // Source: brand prices in EUR
      "toCurrencyIso": "JPY",     // Target: Japan prices in JPY

      // Full multiplier — all rates included
      // Use only if source price has zero embedded rates
      "value": 168.432,

      // Pricing-model-aware multiplier — only adds what's not already in source price
      // Use this in almost all cases
      "adjustedValue": 139.587
    }
  ],

  // Round JPY prices up to nearest whole number (JPY has no decimal places)
  "roundingConfigurations": [
    {
      "currencyIso": "JPY",
      "currencyExponent": 0,
      "direction": "Up",
      "model": "Standard"
    }
  ],

  // Display JPY with ¥ symbol, no decimal places, comma thousands separator
  "currencyDisplays": [
    {
      "currencyIso": "JPY",
      "currencySymbol": "¥",
      "currencyExponent": 0,
      "decimalSeparator": ".",
      "thousandSeparator": ",",
      "showTrailingZeros": false,
      "configurationString": "¥ #,##0"
    }
  ]
},
{
  "id": "Electronics",
  "multipliers": [
    {
      "fromCurrencyIso": "EUR",
      "toCurrencyIso": "JPY",

      // Electronics has lower duty than Apparel — reflected in a different multiplier
      "value": 154.211,
      "adjustedValue": 127.804
    }
  ],
  "roundingConfigurations": [
    {
      "currencyIso": "JPY",
      "currencyExponent": 0,
      "direction": "Up",
      "model": "Standard"
    }
  ],
  "currencyDisplays": [
    {
      "currencyIso": "JPY",
      "currencySymbol": "¥",
      "currencyExponent": 0,
      "decimalSeparator": ".",
      "thousandSeparator": ",",
      "showTrailingZeros": false,
      "configurationString": "¥ #,##0"
    }
  ]
}
```

]
}" steps="\[
{"label":"Store the config ID","description":"<code>id</code> is a stable UUID — store it on every order record so you can retrieve the exact config version that priced it during audits or disputes.","lines":"2-3","tip":"Pair the ID with a session/request ID so you can reconstruct exactly which config priced a given order"},
{"label":"Detect config changes","description":"Compare <code>version</code> against your locally cached copy on every fetch. If it has incremented, invalidate your cache and re-sync — multipliers or rounding rules may have changed.","lines":"5-6","tip":"Cache {id, version} together and skip a full re-parse when neither has changed"},
{"label":"Scope fields","description":"<code>tenantIdentifier</code> scopes this config to one brand, <code>countryIso</code> to one market (JP here). <code>lastUpdated</code> is useful for logging but is not a substitute for the version counter.","lines":"8-10","tip":"Index configs by tenantIdentifier + countryIso if you serve multiple brands or markets"},
{"label":"Match category to your product","description":"<code>id</code> inside each category block must match exactly the category field on your product record — this selects the entire pricing ruleset for that product.","lines":"14-15","tip":"Fall back to a default category rather than throwing when no match is found"},
{"label":"Identify the currency direction","description":"<code>fromCurrencyIso</code> is where brand prices originate (EUR), <code>toCurrencyIso</code> is the market target (JPY). Find the multiplier whose pair matches your conversion direction.","lines":"19-20","tip":"Store the resolved currency pair on the order line for auditability"},
{"label":"Full multiplier — use with care","description":"<code>value: 168.432</code> is the all-in multiplier with every rate included. Only use it when the source price carries zero embedded rates.","lines":"22-24","tip":"If in doubt, use adjustedValue — using value on a price with embedded rates will double-count costs"},
{"label":"Adjusted multiplier — use almost always","description":"<code>adjustedValue: 139.587</code> only adds rates not already embedded in the source price, making it safe for the vast majority of pricing models.","lines":"26-28","tip":"Log which path was taken (adjustedValue vs value) alongside every converted price for auditability"},
{"label":"Apply rounding","description":"<code>currencyExponent: 0</code> means JPY has no decimal places. <code>direction: Up</code> always rounds up to the nearest whole number — required because JPY cannot represent sub-unit values.","lines":"32-40","tip":"Always round as the very last step — rounding mid-calculation compounds error"},
{"label":"Format for display","description":"Use <code>currencySymbol: ¥</code>, <code>thousandSeparator: ,</code>, and <code>currencyExponent: 0</code> to render the final price with no decimals. <code>configurationString: ¥ #,##0</code> is a machine-readable pattern for i18n libraries.","lines":"42-53","tip":"Cross-check formatter output against configurationString in unit tests to catch locale regressions"},
{"label":"Category-specific duty rates","description":"Electronics carries a lower <code>adjustedValue: 127.804</code> than ApparelAccessories <code>139.587</code> because import duty differs by category. Each category block is fully independent — never share a multiplier across them.","lines":"62-64","tip":"Audit multiplier deltas between categories whenever a new version arrives — unexpected changes signal a duty or tax policy update"}
]" fullWidth="false" %}
{% endtab %}
{% endtabs %}

{% stepper %}
{% step %}

### When to Use Multiplier Advice

Multiplier Advice is the right choice when you want to localize prices with the minimum possible integration complexity. Rather than fetching individual rate components and building a calculation engine, you fetch a multiplier and apply it directly.

{% tabs %}
{% tab title="Use Multiplier Advice when" %}

* You need to apply pricing across a large product catalogue quickly, with no per-product rate logic
* Your pricing system can take a multiplier and apply it uniformly across a category
* You want the platform to manage the pricing model complexity (i.e. which rates to include or exclude based on what is already in the source price)
* Throughput and simplicity matter more than per-component visibility
  {% endtab %}

{% tab title="Use Standard Advice instead when" %}

* You need to display an itemized breakdown of duty, tax, and fee to the end customer
* You are building a bespoke pricing engine that handles each component separately
* You need to audit or explain individual rate components
* Your integration requires different handling for different rate types
  {% endtab %}
  {% endtabs %}
  {% endstep %}

{% step %}

### The Three Access Patterns

| Pattern                   | Endpoint                                                  | Use case                                        |
| ------------------------- | --------------------------------------------------------- | ----------------------------------------------- |
| All countries for a brand | `GET /api/4.0/MultiplierAdvice/{tenantCode}`              | Bootstrap or refresh your full multiplier table |
| One country for a brand   | `GET /api/4.0/MultiplierAdvice/{tenantCode}/{countryIso}` | Fetch or refresh a specific market              |
| Specific archived record  | `GET /api/4.0/MultiplierAdvice/{id}/archived`             | Retrieve a historical version by its unique ID  |

All endpoints are read-only `GET` requests and require a Bearer JWT.

```http
Authorization: Bearer <your_jwt_token>
```

{% endstep %}

{% step %}

### Fetch Multiplier Advice for All Countries

Returns an array of `MultiplierAdviceResponse` objects — one per country the brand has active multiplier advice for.

```http
GET /api/4.0/MultiplierAdvice/{tenantCode}
Authorization: Bearer <token>
```

**Path parameters:**

| Parameter    | Type   | Required | Description              |
| ------------ | ------ | -------- | ------------------------ |
| `tenantCode` | string | ✅        | Your brand's tenant code |

**Example:**

```http
GET /api/4.0/MultiplierAdvice/my-brand-001
Authorization: Bearer <token>
```

**Responses:**

| Status            | Meaning                                                      |
| ----------------- | ------------------------------------------------------------ |
| `200 OK`          | Array of `MultiplierAdviceResponse` — one object per country |
| `400 Bad Request` | Invalid `tenantCode` format                                  |

{% hint style="info" %}
**When to use this:** call on startup or cache refresh to load multiplier data for all markets in one round trip. Store keyed by `countryIso` for fast lookup.
{% endhint %}
{% endstep %}

{% step %}

### Fetch Multiplier Advice for a Single Country

Returns a single `MultiplierAdviceResponse` for the latest available advice for a specific brand and country.

```http
GET /api/4.0/MultiplierAdvice/{tenantCode}/{countryIso}
Authorization: Bearer <token>
```

**Path parameters:**

| Parameter    | Type   | Required | Description                                                  |
| ------------ | ------ | -------- | ------------------------------------------------------------ |
| `tenantCode` | string | ✅        | Your brand's tenant code                                     |
| `countryIso` | string | ✅        | ISO 3166-1 alpha-2 country code, e.g. `"JP"`, `"AU"`, `"CA"` |

**Example:**

```http
GET /api/4.0/MultiplierAdvice/my-brand-001/JP
Authorization: Bearer <token>
```

**Responses:**

| Status            | Meaning                                                       |
| ----------------- | ------------------------------------------------------------- |
| `200 OK`          | A single `MultiplierAdviceResponse` for the requested country |
| `400 Bad Request` | Invalid `tenantCode` or `countryIso`                          |
| `404 Not Found`   | No multiplier advice configured for this brand/country        |
| {% endstep %}     |                                                               |

{% step %}

### Fetch a Specific Archived Record by ID

Returns a `MultiplierAdviceResponse` for a historical version of the advice, identified by its unique `id`.

```http
GET /api/4.0/MultiplierAdvice/{id}/archived
Authorization: Bearer <token>
```

**Path parameters:**

| Parameter | Type   | Required | Description                                         |
| --------- | ------ | -------- | --------------------------------------------------- |
| `id`      | string | ✅        | The unique identifier of the specific advice record |

**Example:**

```http
GET /api/4.0/MultiplierAdvice/f9e8d7c6-b5a4-3210-fedc-ba9876543210/archived
Authorization: Bearer <token>
```

**Responses:**

| Status          | Meaning                                              |
| --------------- | ---------------------------------------------------- |
| `200 OK`        | The archived `MultiplierAdviceResponse` with that ID |
| `404 Not Found` | No record found with that ID                         |

{% hint style="info" %}
**When to use this:** retrieve the exact multipliers that were active when a particular price was calculated. Store the `id` from each response alongside any price you compute so you can reconstruct the calculation later.
{% endhint %}
{% endstep %}

{% step %}

### The Full `MultiplierAdviceResponse`

```json
{
  "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "version": "17",
  "tenantIdentifier": "my-brand-001",
  "countryIso": "JP",
  "lastUpdated": "2025-03-14T10:30:00Z",
  "categories": [ ... ]
}
```

<details>

<summary><strong>Top-level fields:</strong></summary>

| Field              | Type                                  | Description                                                                                       |
| ------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `id`               | string                                | Unique identifier for this specific piece of advice — store this for archived retrieval and audit |
| `version`          | string                                | Monotonically increasing version number — compare against cached version to detect updates        |
| `tenantIdentifier` | string                                | The brand/tenant this advice belongs to                                                           |
| `countryIso`       | string                                | ISO 3166-1 alpha-2 country code this advice applies to                                            |
| `lastUpdated`      | string (ISO 8601 UTC)                 | UTC timestamp of the last update                                                                  |
| `categories`       | array of `MultiplierCategoryResponse` | Per-product-category multiplier data                                                              |

</details>

> **Note:** unlike `PricingAdviceResponse`, `MultiplierAdviceResponse` does not include `fxRates` or `merchandisePricingModel` at the top level. The FX rate and pricing model adjustments are already baked into the multiplier values inside `categories`.
> {% endstep %}

{% step %}

### Understanding `MultiplierCategoryResponse`

Each entry in `categories` represents one product category and contains the multipliers, rounding rules, and currency display configuration for that category in this country.

json

{% code expandable="true" %}

```json
"categories": [
  {
    "id": "ApparelAccessories",
    "multipliers": [ ... ],
    "roundingConfigurations": [ ... ],
    "currencyDisplays": [ ... ]
  },
  {
    "id": "Electronics",
    "multipliers": [ ... ],
    "roundingConfigurations": [ ... ],
    "currencyDisplays": [ ... ]
  }
]
```

{% endcode %}

<details>

<summary><strong><code>MultiplierCategoryResponse</code> fields:</strong></summary>

| Field                    | Type                                     | Description                                                                        |
| ------------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------- |
| `id`                     | string                                   | Product category identifier — match against your product's `category` field        |
| `multipliers`            | array of `MultiplierResponse`            | One or more multipliers for this category — each covering a specific currency pair |
| `roundingConfigurations` | array of `RoundingConfigurationResponse` | How to round the final price for this category/currency — see Tutorial 5           |
| `currencyDisplays`       | array of `CurrencyDisplayResponse`       | How to format and display prices for this category — see Tutorial 5                |

</details>
{% endstep %}

{% step %}

### &#x20;`value` vs `adjustedValue`&#x20;

Each entry in the `multipliers` array is a `MultiplierResponse` representing a single currency-pair conversion:

```json
"multipliers": [
  {
    "fromCurrencyIso": "EUR",
    "toCurrencyIso": "JPY",
    "value": 168.432,
    "adjustedValue": 139.587
  }
]
```

<details>

<summary><strong><code>MultiplierResponse</code> fields:</strong></summary>

| Field             | Type            | Description                                                                                                                                              |
| ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fromCurrencyIso` | string          | The source currency ISO code (your brand's home currency)                                                                                                |
| `toCurrencyIso`   | string          | The destination currency ISO code (the country's local currency)                                                                                         |
| `value`           | number (double) | The **full** multiplier — includes FX rate, retailer adjustment, estimated duty, estimated tax, and estimated fee for this category                      |
| `adjustedValue`   | number (double) | The **pricing-model-aware** multiplier — includes FX rate, retailer adjustment, and only the rates that are **not** already embedded in the source price |

</details>

#### What Each Multiplier Includes

| Component           | Included in `value` | Included in `adjustedValue`        |
| ------------------- | ------------------- | ---------------------------------- |
| FX rate             | ✅ Always            | ✅ Always                           |
| Retailer adjustment | ✅ Always            | ✅ Always                           |
| Estimated duty      | ✅ Always            | ✅ Only if NOT in `applicableRates` |
| Estimated tax       | ✅ Always            | ✅ Only if NOT in `applicableRates` |
| Estimated fee       | ✅ Always            | ✅ Only if NOT in `applicableRates` |

In Standard Advice terms:

* `value` is equivalent to applying **all** category rates regardless of the pricing model
* `adjustedValue` is equivalent to the calculation that respects `merchandisePricingModel.applicableRates` — it only adds what is not already in the source price

{% tabs %}
{% tab title="When to use adjustedValue " %}
**Use `adjustedValue` in almost all cases.** It is the multiplier for converting a source price into a localized destination price. It accounts for what is already embedded in the source price.
{% endtab %}

{% tab title="When to use value" %}
**Use `value` only when:**

* Your source price is known to be a fully raw, ex-all price (zero rates embedded) **and** you want to verify this matches the platform's full rate calculation
* You are building an audit tool that needs to show the total theoretical multiplier before any pricing model adjustments
  {% endtab %}
  {% endtabs %}

The difference between `value` and `adjustedValue` corresponds to the rates listed in the equivalent Standard Advice `merchandisePricingModel.applicableRates`. If `applicableRates` is empty (no rates pre-embedded), `value` and `adjustedValue` will be equal.

Suppose your brand sells a leather wallet with a EUR home price of **€100**, shipping to Japan:

```ruby
fromCurrencyIso: "EUR"
toCurrencyIso:   "JPY"
value:           168.432   ← includes all rates
adjustedValue:   139.587   ← duty and tax already in source price, so not added again
```

| Approach                        | Calculation    | Result  |
| ------------------------------- | -------------- | ------- |
| Using `value` (all rates)       | €100 × 168.432 | ¥16,843 |
| Using `adjustedValue` (correct) | €100 × 139.587 | ¥13,959 |

#### Multiple Multipliers per Category

A category may have more than one entry in `multipliers` — for example, if a country supports multiple source currencies or payment currencies. Select the entry where `fromCurrencyIso` matches your source price currency and `toCurrencyIso` matches the country's display currency.
{% endstep %}

{% step %}

### Rounding and Currency Display

Each `MultiplierCategoryResponse` includes `roundingConfigurations` and `currencyDisplays` — the same structures present in Standard Advice categories.

* `roundingConfigurations` — defines the rounding direction (`"Up"`, `"Down"`, `"Nearest"`) and model (`"Standard"`, `"Psychological"`) per currency
* `currencyDisplays` — defines decimal/thousand separators, currency symbol, exponent, trailing zeros, and a formatting string per currency
  {% endstep %}

{% step %}

### Caching and Freshness

Multiplier Advice uses the same `version` and `lastUpdated` fields as Standard Advice for freshness tracking.

```json
{
  "version": "17",
  "lastUpdated": "2025-03-14T10:30:00Z"
}
```

**Recommended caching pattern:**

```
On startup:     GET /MultiplierAdvice/{tenantCode}           → cache all countries
Every N mins:   GET /MultiplierAdvice/{tenantCode}/{country} → poll for version change
On version bump: invalidate cached multipliers for that country
                 recalculate any pre-computed localised prices
```

{% endstep %}
{% endstepper %}

***

### Common Errors

| Status            | Likely Cause                                                                   | Action                                                                                          |
| ----------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| `400 Bad Request` | Malformed `tenantCode` or `countryIso`                                         | Confirm `countryIso` is a valid ISO 3166-1 alpha-2 code; check `tenantCode` for typos           |
| `404 Not Found`   | No multiplier advice for this brand/country, or no archived record for this ID | Confirm the market is enabled for your brand; verify the `id` was obtained from a real response |


---

# 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/resources/tutorials/multiplier-pricing-advice.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.