In Violet, a Cart is contains all the data that a shopper completes during checkout, including items, addresses, and payment methods. Violet supports multi-merchant checkout, so a single Cart can include items from multiple merchants. Each merchant will have a separate Bag. Once a Cart is submitted, it becomes an Order.

There are three primary stages of an Order:

  1. Pre-Submission
  2. Submission
  3. Post-Submission

Each of these stages provide different statuses for Orders to reflect what is shown in an e-commerce platform.

​
Pre-Submission

Pre-submission includes all of the possible actions that may be performed when creating and populating a cart.

  1. Create a Cart: Cart creation begins the checkout process. An empty cart with no products can be created, or a cart prefilled with items and even customer information can be established for your shopper. It is also possible to initialize the cart with a base/presentment currency.
  2. Add Items to Cart: Add items to a cart using their SKU IDs (stock keeping units). These can be included during cart creation or added later.
  3. Apply Customer to Cart: Apply customer information to the cart, like First Name, Last Name, and Email Address. These values enable the the merchant to communicate with the customer once the order has been submitted. Some platforms require these values. If you have questions about different options for handling customer information, feel free to reach out and we’d be happy to help inform your strategy for customer data.
  4. Apply Shipping and Billing Address to Cart: To complete the checkout, a shipping and billing address needs to be applied to the cart. The Shipping Address is used to provide context-specific shipping options for Shopper. Phone numbers can be included to assist in delivery.
  5. Get Shipping Methods: With the Shipping Address applied, request shipping methods specific to the sku dimensions, weight, customer location, and shipping providers used by the Merchant.
  6. Apply Shipping Method to the Cart: The appropriate shipping methods are then applied to the items in the cart.
  7. Finalize Pricing Details for the Cart: All pricing details (like taxes, shipping fees, etc) are finalized.
  8. Apply Payment Method to Cart (Optional): You can use Violet’s built-in payment APIs, or power your own payment. If using Violet, follow the steps here.

​
Submission

Submission is the act of submitting the Violet cart and converting it into an order. During this step each external cart will be submitted in the external commerce platform, with each Bag capturing the external Order ID in the external_id property.

​
Post-Submission

Once an order is submitted to the external commerce platform the platform becomes the source of truth for the order status. We ensure that our Order model stays in sync with any changes made by the merchant, such as fulfillment notifications, delivery notifications, refund notifications, or order cancellations. If you want to learn more about these notifications and how you can receive updates, please refer to our Webhooks page.

Below are the statuses an Order can transition to post-submission:

  • CANCELED: Indicates the Order was voided either during its initial submission or later by a merchant.
  • PARTIALLY_REFUNDED: Only a subset of the Order has been refunded. This is common in multi-merchant scenarios, where some merchants may have processed a refund, while the remaining items were not returned. Or, a single SKU may have been returned within a single Merchant’s Bag. As a result, there was a refund for that specific bag or SKU, with appropriate payouts reversed, and the order would be marked PARTIALLY_REFUNDED.
  • REFUNDED: Every item in the Order has been refunded. Shoppers receive a full refund, and any merchant payouts or commissions are reversed.

Each state transition may entail financial or operational consequences, so it’s crucial to understand the workflow.

Feel free to consult our API docs for deeper insights into the mechanics of Order states.

To effectively process multi-merchant Checkout, an an Order is an aggregation across all Bags and SKUs. Bags have their own statuses for further details about the overall state of an Order. You can learn more about these in Lifecycle of a Bag.

​
Order States

During this phase, the Order goes through the following states:

  1. IN_PROGRESS — An IN_PROGRESS Order is a Cart. Orders in this state are going through the calls mentioned above and have not been submitted to the relevant external e-commerce platforms yet.
  2. PROCESSING — Denotes that an Order is in the process of being submitted. In this stage, inventory checks are being completed, the shopper is being charged, and the relevant orders are being placed in the merchant stores. You potentially may not see this status, as it often takes just a second or two.
  3. REQUIRES_ACTION — During processing, if there are further actions needed by the Shopper before the order can be submitted, an Order enters this state. An example of a Shopper action would be authorizing 3D secure payments, which is a pop-up controlled by the Credit Card provider of the shopper. When an Order enters REQUIRES_ACTION, you will need to re-render the Payment Sheet (with the same payment_intent_client_secret) to your shopper and then resubmit the order upon confirmation.
  4. COMPLETED — The Cart has successfully been submitted and can now be called an Order.

If there are any issues during these states, they are reflected in the errors field on the Order Response object.

A cart response can come back with status code 200 and still have errors in the errors field. This is because there might only be errors on some of the SKUs or Bags while the rest of the order is in a good state.

Make sure your system is coded to always check for the presence of the errors field on responses, no matter the status code.

Note that not all order errors are blocking. INTERNAL_ADD_ITEM for example just indicates that an item could not be added to the cart, this does not block checkout of other items.

Was this page helpful?

OverviewAdding items to a Cart