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.


Platform Support

At this time contextual pricing is limited to merchants on the Shopify platform. Support for additional platforms is currently in development.


Enabling Presentment Currencies for a Merchant

Immediately following the roll-out of presentment currencies Violet will enable presentment currencies for merchants on your behalf. If you know that a merchant is utilizing presentment currencies and does not use a default currency that matches your app currency simply submit a ticket to request they are enabled for that merchant.

​
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
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
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
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
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": "super@mar.io"
    },
    "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.

Was this page helpful?

Media TransformationsOverview