# 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](https://docs.violet.io/prism/checkout-guides/carts-and-bags/carts/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

{% hint style="info" %}
Bag management is automatic. You do not need to interact with Bags directly.
{% endhint %}

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:

```json
{
  "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](https://docs.violet.io/prism/checkout-guides/carts-and-bags/bags/states-of-a-bag) page.