Contextual Pricing

Contextual prices are any prices that are explicitly defined using criteria such as a currency code or region. Using contextual prices a merchant can set prices on their products that override traditional exchange rates. The most common form of this is presentment currencies, where prices are explicitly defined on a product for various currencies instead of using traditional exchange rates.

Supported Platforms

At this time contextual pricing is limited to merchants on the SHOPIFY, BIGCOMMERCE, and COMMERCETOOLS platforms. Support for additional platforms is currently in development.

Enabling Contextual Pricing

The syncing and usage of contextual pricing can be enabled on a per-merchant basis using the Toggle Global Feature Flag endpoint in the Merchant Configuration API.

---

Using Contextual Prices

When contextual prices are enabled for a merchant Violet will begin consuming any contextual prices during product syncs. These will be persisted internally and will not imemdiately impact the standard prices returned on a Violet Offer or Sku.

When using a endpoint that supports a "Base Currency" parameter, these presentment currencies will be activated if the base currency value provided by your request does not match the merchants default currency and if there is a presentment currency that matches the base currency you provided.

If a merchant does not have a presentment currency value that matches the provided base currency value then tranditional exchange rates will be used to calculate the prices.

Catalog

Contextual pricing can be used with the following catalog endpoints.

Get Merchant Offers

When retrieving paginated merchant offers include the base_currency query parameter with your desired currency code as the value. Example: ?base_currency=USD.

curl -L POST https://sandbox-api.violet.io/v1/catalog/offers/merchants/{merchant_id}?base_currency=USD \
-H "X-Violet-App-Id: your-app-id-here" \
-H "X-Violet-App-Secret: your-app-secret-here" \
-H "X-Violet-Token: your-token-here" \
-H "Content-type: application/json"

Get Offer by ID

When retrieving an indivudual offer include the base_currency query parameter with your desired currency code as the value. Example: ?base_currency=USD.

curl -L POST https://sandbox-api.violet.io/v1/catalog/offers/{offer_id}?base_currency=USD \
-H "X-Violet-App-Id: your-app-id-here" \
-H "X-Violet-App-Secret: your-app-secret-here" \
-H "X-Violet-Token: your-token-here" \
-H "Content-type: application/json"

---

Orders

Contextual pricing can be used with the following order endpoints.

Estimate Order

When estimating a cart or order include the base_currency requst body parameter with your desired currency code as the value.

curl -L POST https://sandbox-api.violet.io/v1/carts/estimate \
-H "X-Violet-App-Id: your-app-id-here" \
-H "X-Violet-App-Secret: your-app-secret-here" \
-H "X-Violet-Token: your-token-here" \
-H "Content-type: application/json" \
-d '{
    "base_currency": "USD", // define your base currency here
    "skus": [
        {
            "sku_id": 11111,
            "quantity": 1
        }
    ],
    "shipping_address": {
        "city": "Seattle",
        "state": "WA",
        "country": "US",
        "postal_code": "98121",
        "phone": "1234567890",
        "address_1": "2815 Elliott Ave, Unit 100",
        "first_name": "Super",
        "last_name": "Mario"
    }
}'

Create Order

When creating an order (Direct Order Submission) include the order[currency] requst body parameter with your desired currency code as the value.

The order will be written into the merchants system using this currency if the merchant has enabled this presentment currency in their store. If the merchant has not enabled this presentment currency the prices will be converted using real-time exchange rates and then written into the merchants systems using the merchants default currency.

curl -L POST https://sandbox-api.violet.io/v1/orders \
-H "X-Violet-App-Id: your-app-id-here" \
-H "X-Violet-App-Secret: your-app-secret-here" \
-H "X-Violet-Token: your-token-here" \
-H "Content-type: application/json" \
-d '{
  "payment_method": {
    "type": "SINGLE_USE_CARD_TOKEN",
    "payment_provider": "STRIPE",
    "token": "tok_i1s2h8a9nyg1ukrju12h31kj212kh"
  },
  "order": {
    "currency": "USD", // define your base currency here
    "app_order_id": "mario-test-1",
    "customer": {
      "first_name": "Super",
      "last_name": "Mario",
      "email": "[email protected]"
    },
    "bags": [
      {
        "skus": [
          {
            "sku_id": 11111,
            "price": 9999
          }
        ],
        "shipping_method": {
          "carrier": "OTHER",
          "label": "Teleportation",
          "price": 999
        },
        "tax_total": 899
      }
    ],
    "shipping_address": {
        "city": "Seattle",
        "state": "WA",
        "country": "US",
        "postal_code": "98121",
        "phone": "1234567890",
        "address_1": "2815 Elliott Ave, Unit 100",
        "first_name": "Super",
        "last_name": "Mario"
    },
    "billing_address": {
        "city": "Seattle",
        "state": "WA",
        "country": "US",
        "postal_code": "98121",
        "phone": "1234567890",
        "address_1": "2815 Elliott Ave, Unit 100",
        "first_name": "Super",
        "last_name": "Mario"
    }
  }
}'

If you have any questions regarding contextual pricing please reach out to your Violet account representative or submit a support ticket.