Create Cart

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 occasionally 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 multi-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"
  }]
  ...
}

Create Cart

post

Query parameters

app_order_idstringOptionalDeprecated

Deprecated: Use request body instead.

base_currencystringOptionalDeprecated

Deprecated: Use request body instead.

referral_idstringOptionalDeprecated

Deprecated: Use request body instead.

Header parameters

X-Violet-TokenstringRequired

X-Violet-App-SecretstringRequired

X-Violet-App-Idinteger · int32Required

Body

application/json

Optional data to initialize the cart with upon creation.

base_currencystring · nullableOptional

Base currency that the cart should operate in.

Default: USD

referral_idstring · nullableOptional

Associate the cart with a user or affiliate in your system. This value can also be added later on cart submission.

app_order_idstring · nullableOptional

Associate the cart with an order record in your system. This value can also be added later on cart submission.

wallet_based_checkoutbooleanOptional

Boolean denoting whether or not this order will be placed through a wallet based payment mechanism such as apple pay.

Default: false

Responses

200

create cart success

application/json

202

create cart with error

application/json

400

bad request

application/json

422

unprocessable entity

application/json

post

/checkout/cart

HTTPcURLJavaScriptPython

POST /v1/checkout/cart HTTP/1.1
Host: sandbox-api.violet.io
X-Violet-Token: text
X-Violet-App-Secret: text
X-Violet-App-Id: 1
Content-Type: application/json
Accept: */*
Content-Length: 23

{
  "base_currency": "USD"
}

Create CartCreate Populated CartCreate Cart with Discounts

{
  "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
}