Overview
Login
- Access
Merchants
- Merchant
- Configuration
- Onboarding
- Explore
Catalog
- Offers
- SKUs
- Categories
- Collections
- Currencies
Orders & Checkout
- Carts
- Cart Items
- Cart Customer
- Cart Discounts
- Cart Shipping
- Cart Pricing
- Cart Payment
- Cart Completion
- Orders
- Order Refunds
- Order Cancellations
- Transfers
Payments
- Payout Accounts
- Distributions
- Transfers
Events
- Webhooks
- Webhook Events
- Wekbhook Headers
Apps
- Merchant/App Installs
- Commission Rates
Operations
- Connection
Relay
- Shipping
Ecom Syncs
- Offers
Submit Cart
curl --request POST \
--url https://sandbox-api.violet.io/v1/checkout/cart/{cart_id}/submit \
--header 'Content-Type: application/json' \
--data '{
"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": "super@mar.io",
"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
}
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.
{
"id": 10000,
"token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
"user_id": 10000,
"app_id": 10000,
"developer_id": 10000,
"customer": {
"user_id": 10000,
"first_name": "Super",
"last_name": "Mario",
"email": "super@mar.io",
"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
}
{
"id": 10000,
"token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
"user_id": 10000,
"app_id": 10000,
"developer_id": 10000,
"customer": {
"user_id": 10000,
"first_name": "Super",
"last_name": "Mario",
"email": "super@mar.io",
"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
}
{
"id": 10000,
"token": "fz8x7gksdjsy2p9fdlonw7k9svwjso4b",
"user_id": 10000,
"app_id": 10000,
"developer_id": 10000,
"customer": {
"user_id": 10000,
"first_name": "Super",
"last_name": "Mario",
"email": "super@mar.io",
"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.
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.
{
"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
}
]
}
}
When the submission of a Violet cart containing multiple bags results in one or more failed sumissions, any error(s) will be nested in the "errors": []
array on the Order
object.
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"
}]
...
}
Path Parameters
Body
Properties for cart submission.
Response
Violet Order Entity
Was this page helpful?
curl --request POST \
--url https://sandbox-api.violet.io/v1/checkout/cart/{cart_id}/submit \
--header 'Content-Type: application/json' \
--data '{
"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": "super@mar.io",
"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
}