POST /checkout/cart

Intialize an empty cart or pass in a list of SKUs to generate a pre-filled cart. API Reference: Create Cart


Cart creation takes the following optional parameters:


Intializes your cart with the provided base currency. By default a cart is created in USD.


A list of SKUs for the products you want to initialize the cart with

Cart creation takes the following optional query parameters:


This parameter lets you map the order in Violet to an existing order record within your system.


A string that can be passed in to track referrals and map them to id’s in your system.

curl -X POST \
-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", "skus": [{"sku_id": 999, "quantity": 1}]}'


    "id": 20956,
    "token": "c8f17e9e6fec4268bc9188f039ec68ad",
    "user_id": 10397,
    "app_id": 10382,
    "developer_id": 10292,
    "bags": [
            "id": 20440,
            "order_id": 20956,
            "merchant_id": 10000,
            "app_id": 10382,
            "status": "IN_PROGRESS",
            "fulfillment_status": "PROCESSING",
            "financial_status": "UNPAID",
            "skus": [
                    "id": 24987,
                    "merchant_id": 10000,
                    "app_id": 10382,
                    "product_id": "0ff55c5cda7447118d6ae1c8395f8f11",
                    "sku_id": 10064,
                    "external_id": "13884047425654",
                    "name": "GoPro - Karma Quadcopter with HERO6 Black - White - White",
                    "brand": "GoPro",
                    "thumbnail": "",
                    "quantity": 1,
                    "price": 84999,
                    "weight": 13.45,
                    "available": true,
                    "status": "IN_PROGRESS",
                    "line_price": 84999
            "taxes": [],
            "sub_total": 84999,
            "transactions": [],
            "external_checkout": true,
            "commission_rate": 15.0,
            "date_created": "2022-05-11T16:17:16+0000",
            "remorse_period_ends": "2022-06-10T16:17:16+0000",
            "currency": "USD",
            "external_currency": "USD",
            "channel": "APP",
            "platform": "SHOPIFY",
            "fulfillments": [],
            "merchant_name": "Violet-Besties"
    "sub_total": 84999,
    "status": "IN_PROGRESS",
    "date_created": "2022-05-11T16:17:16+0000",
    "date_last_modified": "2022-05-11T16:17:16+0000",
    "priced": false,
    "currency": "USD",
    "errors": [],
    "channel": "APP",
    "currency_symbol": "$",
    "stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
    "guest": true

Currency Considerations

When creating a cart, if you pass in the base_currency query parameter the currency in the Cart object will match what was passed in, this is also the currency that the shopper will pay in. The default currency when no parameter is provided is USD.

All the bags on the order will be converted to the currency on the Cart at the time of Cart submission. When looking at the Bag object you will see currency and external_currency. The currency will match the Order currency, while the external_currency is what the merchant has their currency set to on their e-commerce store.

The exchange rate is calculated as external_currency → currency. The exchange rate is then applied to all amounts so they reflect currency.

As an example, on a Bag, if the external_currency is USD and the currency is GBP the exchange_rate would be ~ 0.85 which each of the totals would be multiplied by. So if the external item was 100 inthemerchantscurrencyof USD thetotalwouldbeconvertedto 100 in the merchants currency of USD the total would be converted to 85 to reflect GBP on the cart.

Was this page helpful?