Adding Items to Cart

Adding an item to a Cart is the first step of the Checkout process. You can do this either during Cart creation or through a dedicated API during the checkout process.

Violet recommends adding SKUs during cart creation. This is because any call that changes a cart also makes an underlying call to relevant merchant stores and impacts your rate limits.

Create Cart + Add Item to Cart

In addition to other inputs, the Create Cart endpoint also takes in a list of SKUs along with their quantity as seen below:

"skus": [
    {
        "sku_id": 10000,
        "quantity": 1
    }
  ]

If provided, the Cart created will include these these items. In the example response below, an item was added from The Violet Garden, one of the stores we have available in sandbox to place orders against.

{
    "id": 74909,
    "token": "f43a41f11ea34a06a1c247934f038d0f",
    "user_id": 10397,
    "app_id": 10382,
    "developer_id": 10292,
    "bags": [
        {
            "id": 60593,
            "order_id": 74909,
            "merchant_id": 10189,
            "app_id": 10382,
            "status": "IN_PROGRESS",
            "fulfillment_status": "PROCESSING",
            "financial_status": "UNPAID",
            "skus": [
                {
                    "id": 79315,
                    "merchant_id": 10189,
                    "app_id": 10382,
                    "product_id": "87f88388d8a44de6b7ea74d1b822926f",
                    "sku_id": 196585,
                    "external_id": "45101059440941",
                    "name": "Pastel Flower Land - Extra-Large / Design Three / Blue",
                    "brand": "The Violet Garden",
                    "thumbnail": "https://cdn.shopify.com/s/files/1/0758/9363/7421/files/wealthy_floral_design_tshirt_with_a_blue_pastel_colour_backgrou_caefa8e2-b19a-4eb7-84a1-1855591d017b.png",
                    "quantity": 1,
                    "price": 3500,
                    "weight": 3.0,
                    "available": true,
                    "status": "IN_PROGRESS",
                    "product_type": "PHYSICAL",
                    "line_price": 3500
                }
            ],
            "taxes": [],
            "sub_total": 3500,
            "taxes_included": false,
            "transactions": [],
            "external_checkout": true,
            "commission_rate": 25.0,
            "date_created": "2023-09-14T19:49:51+0000",
            "remorse_period_ends": "2023-10-14T19:49:51+0000",
            "currency": "USD",
            "external_currency": "USD",
            "channel": "APP",
            "platform": "SHOPIFY",
            "fulfillments": [],
            "discounts": [],
            "wallet_based_checkout": false,
            "bag_id": 60593,
            "bag_status": "IN_PROGRESS",
            "merchant_name": "the violet garden"
        }
    ],
    "sub_total": 3500,
    "status": "IN_PROGRESS",
    "is_guest": true,
    "date_created": "2023-09-14T19:49:51+0000",
    "date_last_modified": "2023-09-14T19:49:51+0000",
    "priced": false,
    "wallet_based_checkout": false,
    "currency": "USD",
    "errors": [],
    "channel": "APP",
    "currency_symbol": "$",
    "stripe_key": "pk_test_UHg8oLvg4rrDCbvtqfwTE8qd",
    "order_id": 74909,
    "intent_based_checkout": false,
    "guest": true,
    "order_status": "IN_PROGRESS"
}

---

Add Item to Cart

The Add SKU to Cart API lets you add items to a cart at any point up until a Cart has been submitted.

In this scenario, only one SKU can be added at a time. A sample body can be seen below:

{
      "sku_id": 10000,
      "quantity": 1
}

The response for this call will be similar to the one above.

When adding a Sku to a cart, a line item entity called an OrderSku is created. When making modifications to a line item in a cart, you will be interacting with the OrderSku, which has a different id to the original Sku. You can find the id of the original Sku in the sku_id property of the OrderSku.

---

Custom Properties

Custom properties, also commonly referred to as "metadata", can be applied to any new line item or existing line in in a cart.

• Any endpoint that allows for the addition or modification of an OrderSku will accept a list of one or more custom properties.

• Custom properties can be removed from an OrderSku by setting the value of custom_properties to null or [].

Custom properties have the following structure.

{
  "name": "string", // required
  "value": "string" // required
}

The following example shows how custom properties can be applied to a new OrderSku while it's being added to a cart.

POST /v1/checkout/cart/{cart_id}/skus

{
  "sku_id": 99999,
  "quantity": 1,
  "custom_properties": [
    {
      "name": "sample name",
	  "value": "sample value"
	}
  ]
}

Some commerce platforms do not support the concept of custom properties on a line item. For these platforms, the data will persist on the Violet OrderSku, but will not be forwarded to the commerce platform. Because these platforms do not support custom properties, there will be no merchants on these platforms with requirements for custom properties. These platforms currently include BIGCOMMERCE, WIX, and DEMANDWARE (also known as Salesforce Commerce Cloud).