POST
/
checkout
/
cart
curl --request POST \
  --url https://sandbox-api.violet.io/v1/checkout/cart \
  --header 'Content-Type: application/json' \
  --data '{
  "base_currency": "USD"
}'
{
  "id": 10000,
  "token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
  "user_id": 10000,
  "app_id": 10000,
  "developer_id": 10000,
  "customer": null,
  "bags": null,
  "shipping_address": null,
  "billing_address": null,
  "payment_method": null,
  "sub_total": 0,
  "shipping_total": 0,
  "tax_total": 0,
  "discount_total": 0,
  "total": 0,
  "app_order_id": "00100100",
  "status": "IN_PROGRESS",
  "is_guest": true,
  "date_created": "2017-06-15T01:01:01+0000",
  "date_last_modified": "2017-06-15T01:01:01+0000",
  "priced": false,
  "wallet_based_checkout": false,
  "currency": "USD",
  "channel": "APP",
  "currency_symbol": "$",
  "stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
  "payment_intent_client_secret": "pi_vw8krrsvposl347c5l7x1nt5_secret_vbcw5t2bze37iptq430tmx7s",
  "payment_transactions": null,
  "intent_based_checkout": true,
  "guest": true,
  "order_id": 11111
}

Creates a new Cart in Violet.

The id property returned in the response is what we refer to as the Cart ID and will be required for each subsequent call when building and submitting the cart.

Carts are dynamic in Violet. Not all fields my be populated at any given point in time. If there are any issues during the Checkout process, errors will be present in the errors field on the Cart.

​
External Carts

For most ecommerce platforms this action will also result in the creation of equivalent external carts. One external cart will be created for each merchant that is included in the Violet cart. Each nested Bag in the Violet cart will be directly linked to the external cart and will contain all of the Sku’s that are unique to that merchant.

If you do not intend to submit a cart we recommend that you delete the cart. This will ensure that no external carts are orphaned or abandoned in the merchants store(s).

​
Handling Cart Creation Errors

While we strive to ensure that cart creation succeeds, there may occassionally be scenarios where cart creations fails in a way where it cannot be automatically reconciled. The following examples show what to expect when cart creation failure occurs for single-bag and multi-bag carts.

​
Single Bag Cart Creation Errors

When the creation of a Violet cart containing a single Bag results in a failed creation in the external platform, the error will be surfaced as an API Exception in the response body. This error will typically be surface with a 400 or 422 HTTP status.

Example: Response when single-bag cart creation fails due to a 500 Internal Server Error being returned by the commerce platform. 
{
  "message": "SHOPIFY returned a Server Error, preventing the creation of the external cart. Please retry your request.",
  "error": "external_cart_creation_failure",
  "code": 2503,
  "data": {
    "cause": "ORDER_ERROR",
    "skus": [
      {
        "message": "Unable to add item to cart due to cart creation failure.",
        "name": "Nintendo Entertainment System",
        "sku_id": 99999
      }
    ]
  }
}

​
Multi-Bag Cart Creation Errors

When the creation of a Violet cart containing multiple Bag’s results in one or more failed creations in the external platforms, any error(s) will be nested in the "errors": [] array on the Cart object.

Example: Response when mult-bag cart submission fails due to a Sku being out of stock in the external commerce platform. When the entity_type is SKU, the entity_id property will to the sku_id that was provided in the cart creation request. 
{
  ...
  "errors": [{
    "id": 55555,
    "order_id": 66666,
    "bag_id": 77777,
    "entity_id": "99999",
    "entity_type": "SKU",
    "type": "EXTERNAL_CREATE_CART",
    "message": "This item is no longer available for purchase.",
    "date_created": "2023-11-07T05:31:56Z",
    "platform": "SHOPIFY"
  }]
  ...
}

Headers

​
X-Violet-Token
string
​
X-Violet-App-Secret
string
​
X-Violet-App-Id
integer

Query Parameters

​
app_order_id
string
deprecated

Deprecated: Use request body instead.

​
base_currency
string
deprecated

Deprecated: Use request body instead.

​
referral_id
string
deprecated

Deprecated: Use request body instead.

Body

application/json

Optional data to initialize the cart with upon creation.

Response

200
application/json
create cart success

Violet Order Entity