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.
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.
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"
}]
...
}
Deprecated: Use request body instead.
Deprecated: Use request body instead.
Deprecated: Use request body instead.
Optional data to initialize the cart with upon creation.
Base currency that the cart should operate in.
USD
Associate the cart with a user or affiliate in your system. This value can also be added later on cart submission.
Associate the cart with an order record in your system. This value can also be added later on cart submission.
Boolean denoting whether or not this order will be placed through a wallet based payment mechanism such as apple pay.
false
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"
}
{
"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
}
Last updated
Was this helpful?