Lifecycle of a Bag

A Bag is an object that wraps all the data for an Order related to a single merchant in Violet. They live within Orders and mirror the information required by underlying e-commerce store. To a merchant, this bag is synonymous to an order in their merchant store.

Similar to the Lifecycle of a Cart, there are three stages we need to dive into for Bags:

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

During each of these stages, Violet provides different statuses to reflect the state of the parallel order in the merchant’s store.

​

Pre-Submission

Bags are automatically created and managed when items are added to a Cart. If an offer is from a different merchant to existing items in a Cart, a new bag is created and the offer is added to that bag. As you go through the Checkout process and add customer details, shipping methods, etc. Pre-Submission Bags will reflect the following states:

1. IN_PROGRESS — Upon creation, a Bag is automatically in progress and will remain in that state until submission.

​

Submission

Submission is the act of submitting the Bag to the external commerce platform for the purpose of creating an external order. During submission and immediately following submission Bags will reflect the following states:

1. SUBMITTED — A Bag is moved to this state when submitted by Violet to the Merchant store. This state is short-lived (in most cases you won’t notice it), as a Bag moves from SUBMITTED to ACCEPTED when a successful response is returned from the e-commerce platform.

   Once a cart that contains the Bag is submitted, the Bag gets associated with the order placed on the merchant’s eCommerce platform. It then also contains the applicable external order ID, status and tracking information.

2. ACCEPTED — When the Bag is received by the e-commerce platform and returns a success response to Violet, it moves to the ACCEPTED state. If a Merchant were to look in their Dashboard they would see that this order exists.

If there are any issues during processing, the errors are reflected at the Order level in the errors field. If the error is recoverable the Bag will return to an IN_PROGRESS state and submission can be tried again.

​

Duplicate Submissions

Some commerce platforms do not provide the concept of an external cart. For these platforms we emulate the cart experience using cart calculation endpoints to retrieve available shipping methods and to price orders. Since there is no external cart, there is no built-in mechanism within these commerce platforms to prevent duplicate order creation if the Violet order is submitted multiple times in quick succession. To accommodate these commerce platforms Violet will change the status property of any Bags linked to these platforms to SUBMITTED when the Violet cart is submitted. The Bag will remain in this state until the submission on the commerce platform completes with a success or failure response.

If you attempt to submit a Violet cart that is already in the process of submitting you will receive the following error response with a 409 Conflict HTTP status:

{
  "message": "Please wait for bag ID {{BAG-ID}} to finish submitting to the external commerce platform before retrying cart submission.",
  "error": "bag_submission_in_progress",
  "code": 4235
}

When this occurs you can poll the Get Cart by ID endpoint until the status property changes to ACCEPTED upon successful order submission. If the external commerce platform did not accept the order and the Bag status transitions back to IN_PROGRESS you can then attempt to submit the cart again.

​

Post-Submission

Once a Bag has been accepted by the e-commerce platform, state management is managed by the e-com platform as the merchant makes changes. Violet tracks these changes and updates the bag in our system as needed. A Bag can end up in one of the following states as a merchant makes updates:

1. COMPLETED — Once all fulfillments on a Bag are shipped, the Bag enters the state. This state signifies that the Bag is finished and, except for refunds or returns, no further actions will be taken on it.

2. REFUNDED — If all items in the Bag were returned to the merchant by the shopper and a refund was processed, the bag ends up in this state. Violet refunds payments made to the shopper and reverses any payouts to parties involved.

3. PARTIALLY_REFUNDED — When only some items in a bag are returned by the shopper (if multiple items were purchased), a Bag ends up in this state. Violet refunds the amount of money refunded by the merchant to the the shopper and partially reverses any payouts to parties involved.

4. CANCELED — Many e-commerce platforms allow for the cancellation of orders, but it is not often used since it does not trigger a refund to the shopper. When a merchant cancels an order in their e-commerce platform, the order will be updated to the CANCELED status.

5. REJECTED — Although rare, it is possible for an e-commerce platform to reject a Bag. In such cases, the Bag is moved to a REJECTED state. Violet will attempt to retry the bag a few times before accepting the REJECTED state.

   Multi-Merchant Order

   In the event of a multi-merchant Order, if one of the bags is truly rejected after retries Violet will decrease the Order total by the Bag amount to appropriately charge the Shopper and submit the rest of the Order.

   Single Merchant Order

   When an Order only has a single Bag and the Bag is rejected, the entire order will be in an error state and should be tried at a different time.

6. BACKORDERED — If a merchant and the platform they are on allow products to be backordered, a bag will end up in this state.

In addition to a top-level status, Bags also have two additional status fields to better reflect the state that they are in. You can learn more about them in the States of a Bag page.