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
There are two primary stages of an
Both of these stages provide different statuses for
Orders to reflect what is shown in an e-commerce platform.
Pre-submission, the following steps are taken to go from a
Cart to an
- 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.
- 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.
- 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.
- 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.
- 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.
- Apply Shipping Method to the Cart: The appropriate shipping methods are then applied to the items in the cart.
- Finalize Pricing Details for the Cart: All pricing details (like taxes, shipping fees, etc) are finalized.
- 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.
- Submit Cart: Finally, the cart is submitted for processing. If successful, the cart becomes a order, with the same ID.
In summary, the basic steps are:
- Create Cart
- Add SKU to Cart
- Add Customer to Cart
- Add Address to Cart
- Price Cart
- Apply Payment Methods to Cart
- Submit Cart
During this phase, the
Order goes through the following states:
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.
PROCESSING— Denotes that an
Orderis 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.
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.
Carthas successfully been submitted and can now be called an
If there are any issues during these states, they are reflected in the
errors field on the
Order Response object.
An order 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.
Once an order is submitted to the e-commerce platform, Violet no longer has control over its status. However, we do 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
Orderwas voided either during its initial submission or later by a merchant.
PARTIALLY_REFUNDED: Only a subset of the
Orderhas 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
REFUNDED: Every item in the
Orderhas 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
To effectively process multi-merchant Checkout, an an
Order is an aggregation across all
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.