States of a Bag

To reflect accurate information and mirror the state of an order in merchant stores, the Violet Bag contains three different sets of statues:

1. Top-level Bag Statuses
2. Fulfillment Statues
3. Financial Statues

You can learn about each of these statues below.

​

Bag Statuses

The top level status of a bag is denoted by the status field on the Bag object and can be in 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.

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

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

6. PARTIALLY_REFUNDED — When multiple items were purchased in bag, and only some of those items are returned by the shopper, a Bag ends up in this state. Violet refunds to the customer’s card the amount of money refunded by the merchant to the the shopper and partially reverses any payouts to parties involved.

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

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

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

​

Financial Status

The financial status of a bag is denoted by the financial_status field on the Bag object and can be in the following states:

1. UNPAID — All Bags are in this state until submission. Payments are only triggered after bags are submitted and accepted.
2. AUTHORIZED — Once an Order has been submitted to Violet and if payments are being handled by Violet, Violet places a hold on the shopper’s card prior to the bag being submitted to the merchant.
3. PENDING — When a bag’s financial status moves into PENDING the payment has started processing, but needs time to complete. This state is rare, as Violet authorizes a payment before any actions are taken to submit a bag.
4. PAID — After the customer has been charged for the Order, funds are transferred to parties involved and the Bag is marked as PAID.
5. PARTIALLY_PAID — In rare scenarios, a Bag may end up in a PARTIALLY_PAID state if the shopper was only charged for a part of the amount or if there are currency conversion issues at time of sale. If a bag ends up in this state, please reach out to Violet.
6. 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.
7. PARTIALLY_REFUNDED — When multiple items were purchased in bag, and only some of those items are returned by the shopper, a Bag ends up in this state. Violet refunds to the customer’s card the amount of money refunded by the merchant to the the shopper and partially reverses any payouts to parties involved.
8. VOIDED — When the financial status of a Bag is VOIDED, it means that the customers payment failed to capture. In this instance Violet will remove the payment method and the Cart will move from PROCESSING backwards to IN_PROGRESS. In this instance an immediate resubmission of a Cart with failed payment would return an error “No payment method on Cart”. At which point you can apply a new payment method and resubmit.

​

Fulfillment Status

The fulfillment status of a bag is denoted by the fulfillment_status field on the Bag object and can be in the following states:

1. PROCESSING — The PROCESSING status will be the state of any Bag that has not been fulfilled by the merchant. Since it is possible to have multiple items in a bag, they can be fulfilled on a per-item basis.
2. SHIPPED — Once all items in a bag have been fulfilled, the bag moved into this state.
3. PARTIALLY_SHIPPED — For bags with multiple SKUs, after the first fulfillment is created in the fulfillments list and at least one SKU is fulfilled, the bag moves from the processing state to the PARTIALLY_SHIPPED state.
4. DELIVERED — Once all item in a Bag have been delivered to the shopper, and if supported by merchant and e-com platform, the Bag moves into a DELIVERED state.
5. COULD_NOT_DELIVER — If items are not able to be delivered to the shopper, and if this state is supported by merchant and e-com platform, the Bag moves into a COULD_NOT_DELIVER state.
6. RETURNED — If all items in a bag are returned to the merchant and the merchant is able to mark the order as returned, the bag ends up in this state.

Fulfillments on a Bag

The fulfillment list is a centralized location for fulfillment data with a list of SKUs and their corresponding quantities fulfilled. This is important because each bag can have multiple fulfillments. For each fulfillment, the bag has a list of information, including the tracking number and SKUs of the items shipped with that tracking information.

While Bags have a Fulfillment Status, an individual fulfillment can only have a singular status. The only status a fulfillment in the list can have is SUCCESS. Within the fulfillment, you can find the SKUs associated with the shipment. A fulfillment that does not yet exist will not appear in the fulfillments list.

Once all the SKUs in a Bag are fulfilled, the fulfillment_status of said bag will become SHIPPED. In fulfillments list, all relevant SKUs can be found within their corresponding fulfillments.

Example fulfillments list (showing a single fulfillment bag)

"fulfillments": [
{
	"id": ,
	"bag_id": ,
	"external_id": "",
	"carrier": "USPS",
	"raw_carrier": "USPS",
	"status": "SUCCESS",
	"carrier_status": "PENDING",
	"tracking_number": "",
	"tracking_url": "",
	"skus": [
			{
				"id": ,
				"fulfillment_id": ,
				"order_sku_id": ,
				"quantity_fulfilled": 1
			}
		]
	}
],