Order and Bag States
Purpose
This document articulates the states and state changes within the Direct Order Submission checkout flow for both Orders and Bags, providing a comprehensive understanding of how entities transition through the checkout process.
Table of Contents
Overview
In Violet's Direct Order Submission flow, the checkout process involves two primary entities:
Order: The top-level entity representing the entire purchase
Bag: A merchant-specific subset of the order containing SKUs from a single merchant
Each entity progresses through specific states during the checkout process, with state transitions triggered by system events and external responses. Violet doesn't use a traditional "pending" concept - orders transition quickly through states.
Order States
1. IN_PROGRESS
IN_PROGRESS
Description: Order has not yet been submitted to ecom platform
Entry Condition: Order/Cart creation
Duration: Until submission is initiated
Next States:
PROCESSING
2. PROCESSING
PROCESSING
Description: Brief millisecond status while being submitted to the merchant's e-commerce platform
Entry Condition: Submit endpoint called
Duration: Milliseconds
Next States:
REQUIRES_ACTION
, or error
3. ACCEPTED
ACCEPTED
Description: Merchant's system successfully accepted the order
Entry Condition: All bags accepted by merchants
Duration: Brief transitional state
Next States:
COMPLETED
,CANCELED
4. REJECTED
REJECTED
Description: Merchant's system failed to process the order
Entry Condition: Critical failure during submission
Duration: Terminal state
Next States: None (terminal)
5. COMPLETED
COMPLETED
Description: Violet has submitted the order as a whole
Entry Condition: Order successfully processed and payment captured
Duration: Terminal state (with exceptions)
Next States:
CANCELED
6. CANCELED
CANCELED
Description: Merchant chose to cancel after initially accepting
Entry Condition: Cancellation request from merchant or channel
Duration: Terminal state
Next States: None (terminal)
7. REQUIRES_ACTION
REQUIRES_ACTION
Description: Order-level status requiring intervention (e.g., 3D Secure authentication)
Entry Condition: Payment requires additional authentication
Duration: Until shopper completes action
Next States:
PROCESSING
,CANCELED
Bag States
Individual bags within an order can have different statuses:
1. IN_PROGRESS
IN_PROGRESS
Description: Initial state upon creation until submission
Entry Condition: Bag entity created when items added to cart
Duration: Until order submission
Next States:
SUBMITTED
2. SUBMITTED
SUBMITTED
Description: Brief transitional state when submitted to merchant (usually moves quickly to ACCEPTED)
Entry Condition: Order submission initiated
Duration: Milliseconds to seconds
Next States:
ACCEPTED
,REJECTED
,IN_PROGRESS
(on retryable failure)Note: For platforms without external carts, bags remain in this state longer to prevent duplicate submissions
3. ACCEPTED
ACCEPTED
Description: Successfully received by the e-commerce platform and visible in merchant's dashboard
Entry Condition: Positive merchant response with external order ID
Duration: Until fulfillment or post-submission changes
Next States:
COMPLETED
,CANCELED
,REFUNDED
,PARTIALLY_REFUNDED
4. COMPLETED
COMPLETED
Description: All fulfillments have been shipped; bag is finished except for potential refunds/returns
Entry Condition: All items fulfilled by merchant
Duration: Terminal state (with exceptions)
Next States:
REFUNDED
,PARTIALLY_REFUNDED
5. REFUNDED
REFUNDED
Description: All items returned and fully refunded
Entry Condition: Full refund processed by merchant
Duration: Terminal state
Next States: None (terminal)
6. PARTIALLY_REFUNDED
PARTIALLY_REFUNDED
Description: Some items returned and partially refunded
Entry Condition: Partial refund processed by merchant
Duration: Can be terminal or transition to REFUNDED
Next States:
REFUNDED
(if remaining items refunded)
7. CANCELED
CANCELED
Description: Order canceled by merchant (doesn't trigger automatic refund)
Entry Condition: Merchant-initiated cancellation
Duration: Terminal state
Next States: None (terminal)
8. REJECTED
REJECTED
Description: E-commerce platform rejected the bag (Violet retries before accepting this state)
Entry Condition: Multiple failed submission attempts
Duration: Terminal state
Next States: None (terminal)
State Transition Flow
Direct Order Submission Flow Sequence
1. Order Created → Order: IN_PROGRESS
→ Bags: IN_PROGRESS (auto-created)
↓
2. Submit Order → Order: PROCESSING (milliseconds)
→ Bags: SUBMITTED (brief transition)
↓
3. Merchant Response:
- Success → Bags: ACCEPTED
→ Order: PROCESSING
- Failure → Bags: REJECTED (after retries)
→ Order: REJECTED
- Retry → Bags: IN_PROGRESS (retryable failures)
↓
4. Payment Processing:
- Requires 3DS → Order: REQUIRES_ACTION
- Direct capture → Continue
↓
5. All Bags Accepted + Payment Success → Order: COMPLETED
→ Bags remain ACCEPTED
↓
6. Post-Submission States:
- Fulfillment → Bags: COMPLETED
- Full Refund → Bags: REFUNDED
- Partial Refund → Bags: PARTIALLY_REFUNDED
- Cancellation → Order: CANCELED
→ Bags: CANCELED
Key State Relationships
During Submission:
Order moves through
PROCESSING
very quickly (milliseconds)Bags transition through
SUBMITTED
brieflyOrder cannot be
COMPLETED
unless at least one bag isACCEPTED
Post-Submission:
Bag states are managed by merchant platforms
Violet syncs state changes via webhooks and reconciliation.
Bags can have different states within the same order
State Change Triggers
Order State Triggers
IN_PROGRESS
Submit API called
PROCESSING
Valid cart data
PROCESSING
At least 1 bag is accepted
NONE
Stays in PROCESSING until payment is successful
PROCESSING
Any bag rejected
REJECTED
Critical failure after retries
PROCESSING
Payment needs auth
REQUIRES_ACTION
3DS or other authentication
REQUIRES_ACTION
Auth completed
PROCESSING
Re-submission initiated
PROCESSING
Payment captured
COMPLETED
At least 1 bag was capture AND successful payment
COMPLETED
Merchant cancels
CANCELED
Post-acceptance cancellation
COMPLETED
Full refund processed
REFUNDED
All bags refunded
COMPLETED
Partial refund processed
PARTIALLY_REFUNDED
Some bags/SKUs refunded
PARTIALLY_REFUNDED
Remaining items refunded
REFUNDED
All items now refunded
Bag State Triggers
IN_PROGRESS
Order submitted
SUBMITTED
Request sent to merchant
SUBMITTED
Merchant accepts
ACCEPTED
Positive API response
SUBMITTED
Merchant rejects
IN_PROGRESS
Retryable error
SUBMITTED
Multiple failures
REJECTED
Non-retryable or max retries
ACCEPTED
Items backordered
BACKORDERED
Platform supports backorders
ACCEPTED
All items shipped
COMPLETED
Fulfillment complete
ACCEPTED
/COMPLETED
Full refund
REFUNDED
All items refunded
ACCEPTED
/COMPLETED
Partial refund
PARTIALLY_REFUNDED
Some items refunded
PARTIALLY_REFUNDED
Remaining refunded
REFUNDED
All items now refunded
Any state
Merchant cancels
CANCELED
Cancellation request
Error States and Recovery
Error Handling in Order States
PROCESSING Failures:
Violet automatically retries retryable failures
Bags return to
IN_PROGRESS
for retry attemptsAfter max retries, bags move to
REJECTED
REQUIRES_ACTION Recovery:
Re-render payment sheet with same
payment_intent_client_secret
Resubmit order after action completed
Nested Error Object Structure when at least one Bag succeeds and a least one Bag fails.
{
"errors": [
{
"id": 10153,
"order_id": 10634,
"bag_id": 10645,
"entity_type": "BAG",
"entity_id": "10645",
"type": "EXTERNAL_SUBMISSION_FAILED",
"message": "Merchant API returned error: Invalid shipping method",
"external_platform": "SHOPIFY",
"date_created": "2025-06-16T14:21:24+0000"
}
]
}
Important: Always Check Errors Array
A cart response can come back with status code 200 and still have errors in the errors field. This happens when some bags succeed while others fail.
State Synchronization
Post-Submission Synchronization
Once bags are accepted by merchants, state management is handled by the merchant platform. Violet tracks these changes and updates the bag in our system.
Key Synchronization Mechanisms
Webhooks: Primary method for real-time updates
Order lifecycle events (fulfillment, refund, cancellation)
Merchant-initiated changes
State transitions
Order Reconciliation: For platforms with limited webhook support
Periodic status checks for bags in
ACCEPTED
,COMPLETED
,PARTIALLY_REFUNDED
stateEnsures no missed events
Platform-Specific Handling:
Cartless Platforms: Bags remain in
SUBMITTED
state longer to prevent duplicate submissionsPoll Get Cart by ID endpoint until status changes
Date Tracking
date_created
: When order/bag was createddate_submitted
: When validation passed and submission begandate_last_modified
: On an Order, this timestamp is updated only when a property of the Order itself is modified. Some, but not all, Bag status updates will also modify the parent Order. To ensure you have the latest status, check thedate_last_modified
of the associated Bag entities if the Order's timestamp has not changed.date_last_consolidated
: Last sync with merchant platform
State Consistency Rules
Order-Bag Consistency
Order reflects aggregate bag states
Mixed bag states possible (some
ACCEPTED
, someREJECTED
)
Refund vs Cancellation
CANCELED
state doesn't automatically trigger refundsRefunds must be initiated separately by merchant
REFUNDED
/PARTIALLY_REFUNDED
states indicate actual refund processing
Retry Logic
Violet handles automatic retries for transient failures
Bags remains in
SUBMITTED
during retry attemptsFinal
REJECTED
state only after all retries exhausted
Best Practices
State Management
Handle Brief Transitional States:
PROCESSING
andSUBMITTED
are millisecond statesDon't rely on catching these states in polling
Error Handling:
Always check
errors
array regardless of HTTP statusFor single bag order failures check the exception message.
Implement appropriate retry logic for your use case
Cancellation vs Refund:
Understand that
CANCELED
doesn't mean refundedTrack refund states separately (
REFUNDED
,PARTIALLY_REFUNDED
)
Monitoring Recommendations
Track State Durations:
Alert on bags stuck in
SUBMITTED
Monitor for orders in
REQUIRES_ACTION
Handle Mixed States:
Orders can have bags in different states
Implement UI to show per-merchant status
Webhook Best Practices:
Subscribe to all relevant webhooks
Implement webhook retry logic
Use reconciliation as backup for missed webhooks
Last updated
Was this helpful?