States of a Bag
Post-Submission states and sub-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:
- Top-level Bag Statuses
- Fulfillment Statues
- 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:
-
IN_PROGRESS
— Upon creation, a Bag is automatically in progress until submission. -
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 fromSUBMITTED
toACCEPTED
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.
-
ACCEPTED
— When the Bag is received by the e-commerce platform and returns a success response to Violet, it moves to theACCEPTED
state. If a Merchant were to look in their Dashboard they would see that this order exists. -
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. -
REFUNDED
— If all items in theBag
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. -
PARTIALLY_REFUNDED
— When multiple items were purchased in bag, and only some of those items are returned by the shopper, aBag
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. -
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 theCANCELED
status. -
REJECTED
— Although rare, it is possible for an e-commerce platform to reject a Bag. In such cases, the Bag is moved to aREJECTED
state. Violet will attempt to retry the bag a few times before accepting theREJECTED
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.
-
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:
UNPAID
— All Bags are in this state until submission. Payments are only triggered after bags are submitted and accepted.AUTHORIZED
— Once anOrder
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.PENDING
— When a bag’s financial status moves intoPENDING
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.PAID
— After the customer has been charged for the Order, funds are transferred to parties involved and the Bag is marked asPAID
.PARTIALLY_PAID
— In rare scenarios, a Bag may end up in aPARTIALLY_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.REFUNDED
— If all items in theBag
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.PARTIALLY_REFUNDED
— When multiple items were purchased in bag, and only some of those items are returned by the shopper, aBag
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.VOIDED
— When the financial status of a Bag isVOIDED
, it means that the customers payment failed to capture. In this instance Violet will remove the payment method and the Cart will move fromPROCESSING
backwards toIN_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:
PROCESSING
— ThePROCESSING
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.SHIPPED
— Once all items in a bag have been fulfilled, the bag moved into this state.PARTIALLY_SHIPPED
— For bags with multiple SKUs, after the first fulfillment is created in thefulfillments
list and at least one SKU is fulfilled, the bag moves from the processing state to thePARTIALLY_SHIPPED
state.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 aDELIVERED
state.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 aCOULD_NOT_DELIVER
state.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
}
]
}
],
Was this page helpful?