POST
/
checkout
/
cart
/
{cart_id}
/
submit
{
  "id": 123,
  "token": "<string>",
  "errors": [
    {
      "id": 123,
      "order_id": 123,
      "bag_id": 123,
      "entity_id": "<string>",
      "entity_type": "ORDER",
      "type": "EXTERNAL_CREATE_CART",
      "message": "<string>",
      "date_created": "2023-11-07T05:31:56Z",
      "platform": "OTHER"
    }
  ],
  "user_id": 123,
  "app_id": 123,
  "developer_id": 123,
  "customer": {
    "user_id": 123,
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "external_id": "<string>",
    "shipping_address": {
      "name": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "phone": "<string>",
      "type": "SHIPPING",
      "email": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "first_name": "<string>",
      "last_name": "<string>"
    },
    "billing_address": {
      "name": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "postal_code": "<string>",
      "phone": "<string>",
      "type": "SHIPPING",
      "email": "<string>",
      "address_1": "<string>",
      "address_2": "<string>",
      "first_name": "<string>",
      "last_name": "<string>"
    },
    "same_address": true,
    "name": "<string>"
  },
  "bags": [
    {
      "id": 123,
      "order_id": 123,
      "merchant_id": 123,
      "app_id": 123,
      "external_id": "<string>",
      "status": "IN_PROGRESS",
      "fulfillment_status": "PROCESSING",
      "financial_status": "UNPAID",
      "skus": [
        {
          "id": 123,
          "offer_id": 123,
          "merchant_id": 123,
          "app_id": 123,
          "product_id": "<string>",
          "sku_id": 123,
          "external_id": "<string>",
          "name": "<string>",
          "brand": "<string>",
          "thumbnail": "<string>",
          "quantity": 123,
          "price": 123,
          "weight": 123,
          "height": 123,
          "width": 123,
          "length": 123,
          "available": true,
          "status": "IN_PROGRESS",
          "product_type": "PHYSICAL",
          "custom": true,
          "custom_properties": [
            {
              "name": "engraving",
              "value": "Happy Birthday!"
            }
          ],
          "quantity_fulfilled": 123,
          "line_price": 123
        }
      ],
      "shipping_method": {
        "type": "CALCULATED",
        "Carrier": "OTHER",
        "label": "<string>",
        "price": 123,
        "custom": true,
        "min_subtotal": 123,
        "max_subtotal": 123,
        "min_weight": 123,
        "max_weight": 123,
        "external_id": "<string>",
        "id": 123,
        "shipping_method_id": "<string>",
        "bag_id": 123,
        "merchant_id": 123,
        "tracking_number": "<string>"
      },
      "taxes": [
        {
          "order_id": 123,
          "merchant_id": 123,
          "skus": [
            "<string>"
          ],
          "state": "<string>",
          "postal_code": "<string>",
          "rate": 123,
          "amount": 123,
          "description": "<string>"
        }
      ],
      "sub_total": 123,
      "shipping_total": 123,
      "tax_total": 123,
      "discount_total": 123,
      "total": 123,
      "taxes_included": true,
      "transactions": [
        {
          "id": 123,
          "merchant_id": 123,
          "app_id": 123,
          "order_id": 123,
          "bag_id": 123,
          "payment_method_id": 123,
          "gateway_transaction_id": "<string>",
          "gateway": "<string>",
          "amount": 123,
          "currency": "<string>",
          "type": "AUTHORIZATION",
          "error_code": "<string>",
          "status": "PROCESSING",
          "test": true,
          "date_created": "2023-11-07T05:31:56Z",
          "date_last_modified": "2023-11-07T05:31:56Z",
          "order_payment_method": {
            "brand": "<string>",
            "last_four": "<string>",
            "exp_month": 123,
            "exp_year": 123,
            "cardholder_name": "<string>",
            "payment_method_id": 123,
            "default": true
          }
        }
      ],
      "external_checkout": true,
      "commission_rate": 123,
      "date_created": "2023-11-07T05:31:56Z",
      "date_last_modified": "2023-11-07T05:31:56Z",
      "date_last_consolidated": "2023-11-07T05:31:56Z",
      "remorse_period_ends": "2023-11-07T05:31:56Z",
      "currency": "<string>",
      "external_currency": "<string>",
      "currency_exchange_rate": 123,
      "channel": "APP",
      "app_order_id": "<string>",
      "platform": "OTHER",
      "fulfillments": [
        {
          "id": 123,
          "bag_id": 123,
          "external_id": "<string>",
          "carrier": "OTHER",
          "raw_carrier": "<string>",
          "status": "PENDING",
          "carrier_status": "PENDING",
          "tracking_number": "<string>",
          "tracking_url": "<string>",
          "skus": [
            {
              "id": 123,
              "fulfillment_id": 123,
              "order_sku_id": 123,
              "quantity_fulfilled": 123
            }
          ]
        }
      ],
      "discounts": [
        {
          "id": 123,
          "bag_id": 123,
          "status": "PENDING",
          "type": "CODE",
          "value_type": "AMOUNT",
          "target_type": "ORDER",
          "code": "<string>",
          "external_id": "<string>",
          "amount": 123,
          "percentage": 123,
          "amount_total": 123,
          "date_created": "2023-11-07T05:31:56Z",
          "date_last_modified": "2023-11-07T05:31:56Z",
          "email": "<string>"
        }
      ],
      "wallet_based_checkout": true,
      "app_name": "<string>",
      "bag_id": 123,
      "bag_status": "IN_PROGRESS",
      "merchant_name": "<string>"
    }
  ],
  "shipping_address": {
    "name": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "type": "SHIPPING",
    "email": "<string>",
    "address_1": "<string>",
    "address_2": "<string>",
    "first_name": "<string>",
    "last_name": "<string>"
  },
  "billing_address": {
    "name": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "postal_code": "<string>",
    "phone": "<string>",
    "type": "SHIPPING",
    "email": "<string>",
    "address_1": "<string>",
    "address_2": "<string>",
    "first_name": "<string>",
    "last_name": "<string>"
  },
  "payment_method": {
    "brand": "<string>",
    "last_four": "<string>",
    "exp_month": 123,
    "exp_year": 123,
    "cardholder_name": "<string>",
    "payment_method_id": 123,
    "default": true
  },
  "sub_total": 123,
  "shipping_total": 123,
  "tax_total": 123,
  "discount_total": 123,
  "total": 123,
  "app_customer_id": "<string>",
  "app_order_id": "<string>",
  "status": "IN_PROGRESS",
  "is_guest": true,
  "date_created": "2023-11-07T05:31:56Z",
  "date_last_modified": "2023-11-07T05:31:56Z",
  "priced": true,
  "wallet_based_checkout": true,
  "currency": "<string>",
  "referral_id": "<string>",
  "currency_symbol": "<string>",
  "app_name": "<string>",
  "stripe_key": "<string>",
  "payment_intent_client_secret": "<string>",
  "payment_transactions": [
    {
      "id": 123,
      "order_id": 123,
      "payment_provider": "<string>",
      "payment_provider_transaction_id": "<string>",
      "payment_method_id": 123,
      "payment_provider_payment_method_id": "<string>",
      "payment_intent_client_secret": "<string>",
      "amount": 123,
      "metadata": {},
      "related_bags": [
        "<string>"
      ],
      "related_refunds": [
        "<string>"
      ],
      "currency": "<string>",
      "status": "PROCESSING",
      "errors": [
        {
          "id": 123,
          "error_code": 123,
          "error_message": "<string>",
          "payment_transaction_id": 123
        }
      ],
      "date_created": "2023-11-07T05:31:56Z",
      "date_last_modified": "2023-11-07T05:31:56Z"
    }
  ],
  "order_id": 123,
  "guest": true,
  "order_status": "IN_PROGRESS",
  "intent_based_checkout": true
}

Submit a Cart given its cart_id. This submits carts to any relevant E-Commerce platforms.

​
Handling Cart Submission Errors

While we strive to ensure that cart submission succeeds, there may occassionally be scenarios where cart submission fails in a way where it cannot be automatically reconciled. The following examples show what to expect when submission failure occurs for single-bag and multi-bag carts.

​
Single Bag Cart Submission Errors

When the submission of a Violet cart containing a single bag results in a failed sumission, 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 submission fails due to a Sku being out of stock in the external commerce platform. 
{
  "message": "Could not complete external cart: One or more items in the cart are no longer available for purchase.",
  "error": "external_cart_completion_error",
  "code": 2503,
  "data": {
    "skus": [
      {
        "message": "This item is no longer available for purchase.",
        "name": "Sample Product",
        "sku_id": 99999,
        "order_sku_id": 88888,
        "bag_id": 77777
      }
    ]
  }
}

​
Multi-Bag Cart Submission Errors

When the submission of a Violet cart containing multible bags results in one or more failed sumissions, any error(s) will be nested in the "errors": [] array on the Order object.

Example: Response when mult-bag cart submission fails due to a Sku being out of stock in the external commerce platform. 
{
  ...
  "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"
  }]
  ...
}

Headers

X-Violet-Token
string
X-Violet-App-Secret
string
X-Violet-App-Id
integer

Path Parameters

cart_id
integer
required

Body

application/json

Properties for cart submission.

referral_id
string | null

Associate the order with a user or affiliate in your system

app_order_id
string | null

Map the order in Violet to an order record within your system.

app_transaction_id
string | null

Transaction ID representing a transaction in the channels system.. This property only applies to channels approved for external payment processing.

app_transaction_gateway
string | null

Gateway used to submit the order. This property only applies to channels approved for external payment processing.

order_customer
object | null

The Customer Placing the Order

Response

200 - application/json

Violet Order Entity

id
integer
token
string
errors
object[]

Errors on the Order. During checkout, if there was an error or issue on one of the order's bags, there will be an error added to this list describing the issue. The checkout API will return 200 with the order object in the response even if there was an issue with a bag so you must always check the response for errors in this list to know if there was an issue on the order.

user_id
integer
deprecated

ID of the User placing the order

app_id
integer

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

developer_id
integer

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

customer
object | null

The Customer Placing the Order

bags
object[]

One or more Bags that make up the Order. Each Bag will contain the Sku's, shipping methods, and totals unique to a merchant. Each merchant in an Order will have their own Bag.

shipping_address
object

The shipping or billing address of a user placing an order

billing_address
object

The shipping or billing address of a user placing an order

payment_method
object | null

Payment Method belonging to an Order

sub_total
integer

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

shipping_total
integer

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

tax_total
integer

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

discount_total
integer

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

total
integer

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

app_customer_id
string

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

app_order_id
string

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.

status
enum<string>
required

Status of the Order

Available options:
IN_PROGRESS,
PROCESSING,
COMPLETED,
CANCELED,
PARTIALLY_REFUNDED,
REFUNDED,
REQUIRES_ACTION
is_guest
boolean

Order is Guest

date_created
string

Date of order creation

date_last_modified
string

Date of last order update

priced
boolean

Is the cart priced

wallet_based_checkout
boolean

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

currency
string

Base currency of cart

referral_id
string

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_symbol
string

Symbol representing the currency the Order operates in.

app_name
string

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

stripe_key
string

Stripe publishable key. Use for tokenizing payment methods.

payment_intent_client_secret
string

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

payment_transactions
object[]

Payment Transactions associated to the bags on this Cart

order_id
integer
guest
boolean
order_status
enum<string>
Available options:
IN_PROGRESS,
PROCESSING,
COMPLETED,
CANCELED,
PARTIALLY_REFUNDED,
REFUNDED,
REQUIRES_ACTION
intent_based_checkout
boolean

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

Was this page helpful?

Price CartGet Order Refunds