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

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
post
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
}

Last updated

Was this helpful?