# 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.

{% hint style="info" %}
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`.
{% endhint %}

**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.

{% hint style="info" %}
If you do not intend to submit a cart we recommend that you [delete the cart](https://docs.violet.io/api-reference/orders-and-checkout/carts/delete-cart). This will ensure that no external carts are orphaned or abandoned in the merchants store(s).
{% endhint %}

***

### 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.

<sub>Example: Response when single-bag cart creation fails due to a</sub> <sub>`500 Internal Server Error`</sub> <sub>being returned by the commerce platform.</sub>

```json
{
  "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.

<sub>Example: Response when multi-bag cart submission fails due to a Sku being out of stock in the external commerce platform. When the</sub> <sub>`entity_type`</sub> <sub>is</sub> <sub>`SKU`</sub><sub>, the</sub> <sub>`entity_id`</sub> <sub>property will to the</sub> <sub>`sku_id`</sub> <sub>that was provided in the cart creation request.</sub>

```json
{
  ...
  "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"
  }]
  ...
}
```

{% openapi src="<https://3937396275-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8lXIp71Ct5qCUhXjko2q%2Fuploads%2Fgit-blob-8ab007712b2fb1063fba6d0d5fac84738eef8644%2Forder-service.yaml?alt=media>" path="/checkout/cart" method="post" expanded="true" %}
[order-service.yaml](https://3937396275-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8lXIp71Ct5qCUhXjko2q%2Fuploads%2Fgit-blob-8ab007712b2fb1063fba6d0d5fac84738eef8644%2Forder-service.yaml?alt=media)
{% endopenapi %}