Submit Cart

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

---

Submission Response Scenarios

The following sample responses are meant to prepare you for the possible success or failure scenarios.

All Bags Succeed

{
  "id": 10000,
  "token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
  "user_id": 10000,
  "app_id": 10000,
  "developer_id": 10000,
  "customer": {
    "user_id": 10000,
    "first_name": "Super",
    "last_name": "Mario",
    "email": "[email protected]",
    "name": "Super Mario"
  },
  "bags": [
    {
      "id": 11111,
      "order_id": 10000,
      "merchant_id": 10000,
      "app_id": 10000,
      "status": "ACCEPTED",
      "fulfillment_status": "PROCESSING",
      "financial_status": "PAID",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10000,
          "app_id": 10000,
          "sku_id": 99999,
          "external_id": "1234567890",
          "name": "Nintendo Entertainment System",
          "brand": "Nintendo",
          "quantity": 2,
          "price": 9999,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 19998
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "07d19139fc0f4558687c1900c696f071",
        "label": "Priority Mail",
        "price": 644
      },
      "sub_total": 19998,
      "shipping_total": 644,
      "tax_total": 2070,
      "discount_total": 0,
      "total": 22712,
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "bag_id": 22222,
      "bag_status": "ACCEPTED",
      "merchant_name": "Legacy Games"
    },
    {
      "id": 22223,
      "order_id": 10000,
      "merchant_id": 10001,
      "app_id": 10000,
      "status": "ACCEPTED",
      "fulfillment_status": "PROCESSING",
      "financial_status": "PAID",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10001,
          "app_id": 10000,
          "sku_id": 99998,
          "external_id": "1234567890",
          "name": "He-Man And The Masters Of The Universe – Castle Grayskull",
          "brand": "Mattel",
          "quantity": 1,
          "price": 10000,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 10000
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "ground-shipping",
        "label": "Ground Shipping",
        "price": 0
      },
      "sub_total": 10000,
      "shipping_total": 0,
      "tax_total": 900,
      "discount_total": 0,
      "total": 10900,
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "bag_id": 22223,
      "bag_status": "ACCEPTED",
      "merchant_name": "Retro Toys"
    }
  ],
  "shipping_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "SHIPPING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "billing_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "BILLING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "sub_total": 29998,
  "shipping_total": 644,
  "tax_total": 2970,
  "discount_total": 0,
  "total": 33612,
  "status": "COMPLETED",
  "currency": "USD",
  "channel": "APP",
  "currency_symbol": "$",
  "payment_transactions": [
    {
      "amount": 33612,
      "currency": "USD",
      "capture_status": "CAPTURED",
      "status": "CAPTURED"
    }
  ],
  "guest": true,
  "order_id": 10000
}

Some Bags Fail

{
  "id": 10000,
  "token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
  "user_id": 10000,
  "app_id": 10000,
  "developer_id": 10000,
  "customer": {
    "user_id": 10000,
    "first_name": "Super",
    "last_name": "Mario",
    "email": "[email protected]",
    "name": "Super Mario"
  },
  "bags": [
    {
      "id": 11111,
      "order_id": 10000,
      "merchant_id": 10000,
      "app_id": 10000,
      "status": "ACCEPTED",
      "fulfillment_status": "PROCESSING",
      "financial_status": "PAID",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10000,
          "app_id": 10000,
          "sku_id": 99999,
          "external_id": "1234567890",
          "name": "Nintendo Entertainment System",
          "brand": "Nintendo",
          "quantity": 2,
          "price": 9999,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 19998
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "07d19139fc0f4558687c1900c696f071",
        "label": "Priority Mail",
        "price": 644
      },
      "sub_total": 19998,
      "shipping_total": 644,
      "tax_total": 2070,
      "discount_total": 0,
      "total": 22712,
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "bag_id": 22222,
      "bag_status": "ACCEPTED",
      "merchant_name": "Legacy Games"
    },
    {
      "id": 22223,
      "order_id": 10000,
      "merchant_id": 10001,
      "app_id": 10000,
      "status": "REJECTED",
      "fulfillment_status": "PROCESSING",
      "financial_status": "VOIDED",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10001,
          "app_id": 10000,
          "sku_id": 99998,
          "external_id": "1234567890",
          "name": "He-Man And The Masters Of The Universe – Castle Grayskull",
          "brand": "Mattel",
          "quantity": 1,
          "price": 10000,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 10000
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "ground-shipping",
        "label": "Ground Shipping",
        "price": 0
      },
      "sub_total": 10000,
      "shipping_total": 0,
      "tax_total": 900,
      "discount_total": 0,
      "total": 10900,
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "bag_id": 22223,
      "bag_status": "REJECTED",
      "merchant_name": "Retro Toys"
    }
  ],
  "shipping_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "SHIPPING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "billing_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "BILLING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "sub_total": 19998,
  "shipping_total": 644,
  "tax_total": 2070,
  "discount_total": 0,
  "total": 22712,
  "status": "COMPLETED",
  "currency": "USD",
  "channel": "APP",
  "currency_symbol": "$",
  "payment_transactions": [
    {
      "amount": 22712,
      "currency": "USD",
      "capture_status": "CAPTURED",
      "status": "CAPTURED"
    }
  ],
  "guest": true,
  "order_id": 10000
}

All Bags Fail

{
  "id": 10000,
  "token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
  "user_id": 10000,
  "app_id": 10000,
  "developer_id": 10000,
  "customer": {
    "user_id": 10000,
    "first_name": "Super",
    "last_name": "Mario",
    "email": "[email protected]",
    "name": "Super Mario"
  },
  "bags": [
    {
      "id": 11111,
      "order_id": 10000,
      "merchant_id": 10000,
      "app_id": 10000,
      "status": "REJECTED",
      "fulfillment_status": "PROCESSING",
      "financial_status": "VOIDED",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10000,
          "app_id": 10000,
          "sku_id": 99999,
          "external_id": "1234567890",
          "name": "Nintendo Entertainment System",
          "brand": "Nintendo",
          "quantity": 2,
          "price": 9999,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 19998
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "07d19139fc0f4558687c1900c696f071",
        "label": "Priority Mail",
        "price": 644
      },
      "sub_total": 19998,
      "shipping_total": 644,
      "tax_total": 2070,
      "discount_total": 0,
      "total": 22712,
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "bag_id": 22222,
      "bag_status": "REJECTED",
      "merchant_name": "Legacy Games"
    },
    {
      "id": 22223,
      "order_id": 10000,
      "merchant_id": 10001,
      "app_id": 10000,
      "status": "REJECTED",
      "fulfillment_status": "PROCESSING",
      "financial_status": "VOIDED",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10001,
          "app_id": 10000,
          "sku_id": 99998,
          "external_id": "1234567890",
          "name": "He-Man And The Masters Of The Universe – Castle Grayskull",
          "brand": "Mattel",
          "quantity": 1,
          "price": 10000,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 10000
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "ground-shipping",
        "label": "Ground Shipping",
        "price": 0
      },
      "sub_total": 10000,
      "shipping_total": 0,
      "tax_total": 900,
      "discount_total": 0,
      "total": 10900,
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "bag_id": 22223,
      "bag_status": "REJECTED",
      "merchant_name": "Retro Toys"
    }
  ],
  "shipping_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "SHIPPING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "billing_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "BILLING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "sub_total": 19998,
  "shipping_total": 644,
  "tax_total": 2070,
  "discount_total": 0,
  "total": 22712,
  "status": "IN_PROGRESS",
  "currency": "USD",
  "channel": "APP",
  "currency_symbol": "$",
  "payment_transactions": [
    {
      "amount": 22712,
      "currency": "USD",
      "capture_status": "CANCELLED"
    }
  ],
  "guest": true,
  "order_id": 10000
}

---

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 multiple bags results in one or more failed submissions, 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. When the entity_type is SKU, the entity_id property will map to the sku_id property on a Sku in the Cart.}

{
  ...
  "errors": [{
    "id": 55555,
    "order_id": 66666,
    "bag_id": 77777,
    "entity_id": "99999",
    "entity_type": "SKU",
    "type": "EXTERNAL_SUBMIT_CART",
    "message": "This item is no longer available for purchase.",
    "date_created": "2023-11-07T05:31:56Z",
    "platform": "SHOPIFY"
  }]
  ...
}

---

Submit Cart

post

Path parameters

cart_idinteger · int64Required

Header parameters

X-Violet-TokenstringRequired

X-Violet-App-SecretstringRequired

X-Violet-App-Idinteger · int32Required

Body

application/json

Properties for cart submission.

referral_idstring · nullableOptional

Associate the order with a user or affiliate in your system

app_order_idstring · nullableOptional

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

app_transaction_idstring · nullableOptional

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

app_transaction_gatewaystring · nullableOptional

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

Responses

200

success

application/json

A Violet Order representing a shopping cart that progresses through checkout to become a placed order. An Order contains one or more Bags (one per merchant), a customer, shipping/billing addresses, and a payment method. The lifecycle is: create cart → add items → set addresses → apply shipping → set payment → submit. All monetary values are in the smallest currency unit (e.g. cents for USD).

idinteger · int64Read-onlyRequired

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 · int64Read-onlyOptionalDeprecated

ID of the User placing the order

app_idinteger · int32Read-onlyRequired

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

developer_idinteger · int32Read-onlyRequired

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

sub_totalinteger · int32Required

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

Default: 0

shipping_totalinteger · int32Required

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

Default: 0

tax_totalinteger · int32Required

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

Default: 0

discount_totalinteger · int32Required

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

Default: 0

totalinteger · int32Required

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 · max: 191 · nullableOptional

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

app_order_idstring · max: 64 · 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-onlyRequired

Status of the Order

Possible values:

is_guestbooleanRead-onlyRequired

Whether this is a guest checkout order. Guest orders do not create or link to a customer account in the merchant's system. Most orders placed via the Violet API are guest orders.

Default: true

date_createdstring · date-timeRead-onlyRequired

Date of order creation

date_last_modifiedstring · date-timeRead-onlyRequired

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-onlyRequired

Whether the cart has been priced. A cart must be priced before it can be submitted for checkout. Pricing is triggered automatically when shipping methods are applied and tax/shipping totals are calculated.

Default: false

wallet_based_checkoutbooleanRequired

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

Default: false

currencystring · min: 3 · max: 3Required

ISO 4217 currency code for the Order.

Default: USDExample: 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_secretstring · nullableRead-onlyOptional

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

order_idinteger · int64Optional

order_statusstring · enumOptionalPossible values:

guestbooleanOptional

intent_based_checkoutbooleanOptional

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

400

bad request

application/json

404

not found

application/json

409

conflict

application/json

412

precondition failed

application/json

post

/checkout/cart/{cart_id}/submit

HTTPcURLJavaScriptPython

POST /v1/checkout/cart/{cart_id}/submit 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: 38

{
  "app_order_id": "asdf-ghjk-qwer-tyui"
}

{
  "id": 10000,
  "token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
  "user_id": 10000,
  "app_id": 10000,
  "developer_id": 10000,
  "customer": {
    "user_id": 10000,
    "first_name": "Super",
    "last_name": "Mario",
    "email": "[email protected]",
    "name": "Super Mario"
  },
  "bags": [
    {
      "id": 11111,
      "order_id": 10000,
      "merchant_id": 10000,
      "app_id": 10000,
      "status": "ACCEPTED",
      "fulfillment_status": "PROCESSING",
      "financial_status": "PAID",
      "skus": [
        {
          "id": 10000,
          "merchant_id": 10000,
          "app_id": 10000,
          "sku_id": 99999,
          "external_id": "1234567890",
          "name": "Nintendo Entertainment System",
          "brand": "Nintendo",
          "thumbnail": "https://res.cloudinary.com/violet/image/upload/c_thumb,w_200,g_face/v1729220594/product_media/2taesr1g7sciu8agrrtgaafi2dnzzmsv.jpg",
          "quantity": 2,
          "price": 9999,
          "weight": 1,
          "available": true,
          "status": "PROCESSING",
          "product_type": "PHYSICAL",
          "custom": false,
          "line_price": 19998
        }
      ],
      "shipping_method": {
        "carrier": "USPS",
        "shipping_method_id": "07d19139fc0f4558687c1900c696f071",
        "bag_id": 11111,
        "merchant_id": 10000,
        "label": "Priority Mail",
        "price": 644,
        "custom": false
      },
      "taxes": [
        {
          "order_id": 127021,
          "merchant_id": 10009,
          "state": "WA",
          "rate": 6.5,
          "amount": 1300,
          "description": "Washington State Tax"
        },
        {
          "order_id": 127021,
          "merchant_id": 10009,
          "state": "WA",
          "rate": 0,
          "amount": 0,
          "description": "King County Tax"
        },
        {
          "order_id": 127021,
          "merchant_id": 10009,
          "state": "WA",
          "rate": 3.85,
          "amount": 770,
          "description": "Seattle City Tax"
        }
      ],
      "sub_total": 19998,
      "shipping_total": 644,
      "tax_total": 2070,
      "discount_total": 0,
      "total": 22712,
      "taxes_included": false,
      "external_checkout": true,
      "commission_rate": 10,
      "date_created": "2017-06-15T01:01:01+0000",
      "date_last_modified": "2017-06-15T01:01:01+0000",
      "remorse_period_ends": "2017-06-15T01:01:01+0000",
      "currency": "USD",
      "external_currency": "USD",
      "channel": "APP",
      "platform": "SHOPIFY",
      "fulfillments": [],
      "discounts": [],
      "wallet_based_checkout": false,
      "bag_id": 22222,
      "bag_status": "IN_PROGRESS",
      "merchant_name": "Legacy Games"
    }
  ],
  "shipping_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "SHIPPING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "billing_address": {
    "name": "Super Mario",
    "city": "Seattle",
    "state": "WA",
    "country": "US",
    "postal_code": "98121",
    "phone": "1234567890",
    "type": "BILLING",
    "address_1": "2815 Elliott Ave, Unit 100",
    "first_name": "Super",
    "last_name": "Mario"
  },
  "payment_method": {
    "brand": "visa",
    "last_four": "4242",
    "exp_month": 12,
    "exp_year": 2025,
    "payment_method_id": 35236
  },
  "sub_total": 19998,
  "shipping_total": 644,
  "tax_total": 2070,
  "discount_total": 0,
  "total": 22712,
  "app_order_id": "00100100",
  "status": "COMPLETED",
  "is_guest": true,
  "date_created": "2017-06-15T01:01:01+0000",
  "date_last_modified": "2017-06-15T01:01:01+0000",
  "priced": true,
  "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": [
    {
      "id": 99999,
      "order_id": 10000,
      "payment_provider": "STRIPE",
      "payment_provider_transaction_id": "pi_vw8krrsvposl347c5l7x1nt5",
      "payment_method_id": 77777,
      "payment_provider_payment_method_id": "pm_1PtHCnK29KDiBVldrynYIy0k",
      "payment_intent_client_secret": "pi_vw8krrsvposl347c5l7x1nt5_secret_vbcw5t2bze37iptq430tmx7s",
      "amount": 22712,
      "metadata": {
        "payment_intent_client_secret": "pi_vw8krrsvposl347c5l7x1nt5_secret_vbcw5t2bze37iptq430tmx7s",
        "payment_intent_id": "pi_vw8krrsvposl347c5l7x1nt5"
      },
      "related_bags": [
        "11111"
      ],
      "currency": "USD",
      "capture_status": "CAPTURED",
      "errors": [],
      "date_created": "2024-08-29T22:52:42+0000",
      "date_last_modified": "2024-08-29T22:52:52+0000",
      "status": "CAPTURED"
    }
  ],
  "intent_based_checkout": true,
  "guest": true,
  "order_id": 10000
}