search

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.

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

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.

circle-info

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

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

hashtag
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
      }
    ]
  }
}

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

hashtag
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

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
chevron-right
200

create cart success

application/json

Violet Order Entity

idinteger · int64Read-onlyOptional

ID of the Violet cart or order.

tokenstringRead-onlyOptionalDeprecated

An alternative UUID that can be used as an ID to reference the cart or order.

user_idinteger · int64OptionalDeprecated

ID of the User placing the order

app_idinteger · int32Optional

ID of the App responsible for the creation and submission of this Order.

developer_idinteger · int32Optional

ID of the Developer responsible for the creation and submission of this Order.

sub_totalinteger · int32Optional

The price of the Order in the base currency before discounts, shipping, duties, taxes, and tips. In Cents.

Default: 0
shipping_totalinteger · int32Optional

The sum of all shipping methods applied to the Order in the base currency. In Cents.

Default: 0
tax_totalinteger · int32Optional

The sum of all the taxes applied to the Order in the base currency. In Cents.

Default: 0
discount_totalinteger · int32Optional

The total discounts applied to the price of the Order in the base currency. In Cents.

Default: 0
totalinteger · int32Optional

The sum of all item prices, discounts, shipping, and taxes applied to the Order in the base currency. In Cents.

Default: 0
app_customer_idstring · nullableOptional

App Customer ID. This should be used to map the order to the ID of the customer in your application.

app_order_idstring · nullableOptional

App Order ID. This should be set to a unique identifier in your system. While not enforced unique in Violet's system, it is strongly recommended that unique values are used for each cart to help correlate identifiers between Violet's system and yours.

statusstring · enumRead-onlyOptional

Status of the Order

Possible values:
is_guestbooleanRead-onlyOptional

Order is Guest

Default: true
date_createdstring · date-timeRead-onlyOptional

Date of order creation

date_last_modifiedstring · date-timeRead-onlyOptional

Indicates when the order was last modified. This timestamp is updated only when a property on the Order entity itself changes. Modifications to related entities (e.g., Bags) will not update this timestamp unless the change also triggers an update to the Order entity.

date_submittedstring · date-time · max: 24 · nullableRead-onlyOptional

Date the Order was last submitted in Violet. This value is captured immediately after the Order is successfully validated and before the nested Bag(s) are submitted to the external commerce platforms.

pricedbooleanRead-onlyOptional

Is the cart priced

Default: false
wallet_based_checkoutbooleanOptional

Is this cart going to be placed through wallet-based checkout

Default: false
currencystringOptional

Base currency of cart

Default: USD
referral_idstring · nullableOptional

Optional value used to represent an identifier in your system. This value is not required to represent a referral. It can represent the ID of anything in your system and can be used to filter order lookup results. Max length of 128 characters.

currency_symbolstringOptional

Symbol representing the currency the Order operates in.

app_namestringOptional

Name of app that originated the order. Use the "extended" query param when looking up orders to include this value.

stripe_keystringOptional

Stripe publishable key. Use for tokenizing payment methods.

payment_intent_client_secretstringOptional

Payment intent client secret. Use for payment intent based payment capture and external captures

order_statusstring · enumOptionalPossible values:
guestbooleanOptional
intent_based_checkoutbooleanOptional

Boolean indicating if the cart/order will be payed using a payment intent.

order_idinteger · int64Optional
post
/checkout/cart
PreviousCartsNextGet Cart by ID

Last updated

Was this helpful?