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 Orders, there are two stages we need to dive into for Bags:

1. Pre-submission Bags
2. Post-submission Bags

During both 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. Bags reflect the following states:

1. IN_PROGRESS — Upon creation, a Bag is automatically in progress until submission.

2. SUBMITTED — A bag 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.

3. 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.

​

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.