Orders

Order webhooks notify your application about changes to the order lifecycle, from creation through fulfillment, returns, refunds, and cancellations.

Overview

Order webhooks track the complete lifecycle of orders and their associated bags (merchant-specific sub-orders). These events enable you to monitor order placement, fulfillment status, refunds, returns, and cancellations.

Important: All order webhook events are triggered by changes to Bag entities, not Order entities directly. Each event monitors specific bag status transitions and is published asynchronously when those conditions are met.

Learn more about the order lifecycle in the Order and Bag States documentation.

Understanding Order States

Orders progress through several states during their lifecycle:

• IN_PROGRESS - Order created but not yet submitted

• PROCESSING - Brief state during submission (milliseconds)

• COMPLETED - Order submitted, at least one bag accepted, payment captured

• CANCELED - Order cancelled by merchant or channel

• REFUNDED - Full refund processed

• PARTIALLY_REFUNDED - Partial refund processed

Each order contains one or more bags (merchant-specific orders) that can have independent states. See Order and Bag States for complete details.

Available Events

ORDER_ACCEPTED

Trigger: When an order is created and each bag is accepted by the merchant platform.

Common Scenarios:

• Order is successfully submitted to the merchant's platform

• Merchant's platform confirms the order can be fulfilled

Use Case: Subscribe to this event when you need to track the initial acceptance of orders. This event fires when the order is first acknowledged by the merchant system.

Important: Both ORDER_ACCEPTED and ORDER_UPDATED events are sent together for each bag.

Additional Headers:

• X-Violet-Order-Id - The order ID

• X-Violet-Bag-Id - The bag ID associated with this acceptance event

ORDER_UPDATED

Trigger: When any changes are made to a bag. This event is sent in two ways:

1. Automatically alongside specific events: ORDER_UPDATED is always sent together with ORDER_ACCEPTED, ORDER_SHIPPED, ORDER_DELIVERED, ORDER_COMPLETED, ORDER_CANCELED, and ORDER_REFUNDED events

2. Standalone for other changes: Sent by itself when bag changes occur that don't trigger specific events

Common Scenarios:

• Bag status changes (status, fulfillment status, financial status, dispute status)

• Tracking information updates

• New fulfillments added or modified

• Fulfillment property changes (tracking numbers, carrier information)

• SKU quantity changes within fulfillments

• Customer contact information changes

• Shopper shipping or billing address corrections

Use Case: Subscribe to this event when you need to track all bag changes, regardless of type. This is a catchall event for maintaining real-time synchronization of order data across your systems.

When to use specific events instead: For major order lifecycle changes, use these specific events rather than relying on ORDER_UPDATED:

• ORDER_ACCEPTED - For initial order acceptance

• ORDER_COMPLETED - For bag completion after fulfillment

• ORDER_SHIPPED - For order fulfillment

• ORDER_DELIVERED - For delivery confirmation

• ORDER_REFUNDED - For refunds

• ORDER_CANCELLED - For cancellations

Since ORDER_UPDATED is sent alongside most specific order events, you will receive multiple events in quick succession for the same bag change. Always check the bag state in the payload to determine the current status.

ORDER_COMPLETED

Trigger: When a bag's status changes to COMPLETED, indicating all items in that bag have been fulfilled.

This means:

• All items in the bag have been shipped

• The fulfillment process for this bag is complete

• The bag has transitioned to COMPLETED state

Use Case: Subscribe to this event to:

• Track when individual bags are fully fulfilled

• Monitor fulfillment completion across merchants

• Trigger post-fulfillment workflows

• Update fulfillment analytics and metrics

Important: This event fires at the bag level when fulfillment is complete. For tracking initial order placement and payment capture, use the ORDER_ACCEPTED event instead. Individual bags can reach COMPLETED status at different times as merchants fulfill their portions of the order.

Additional Headers:

• X-Violet-Order-Id - The order ID

• X-Violet-Bag-Id - The bag ID that completed

ORDER_SHIPPED

Trigger: When a bag's fulfillment status changes to SHIPPED or PARTIALLY_SHIPPED.

This means:

• The merchant has shipped all items in the bag (status: SHIPPED), OR

• The merchant has shipped some but not all items in the bag (status: PARTIALLY_SHIPPED)

• Tracking information is typically available at this point

Use Case: Subscribe to this event to:

• Track order fulfillment

• Update order status in your system

• Access tracking information

• Notify customers of shipment

• Monitor fulfillment timelines

Additional Data: This event typically includes tracking data such as carrier information and tracking numbers in the fulfillment details.

Additional Headers:

• X-Violet-Order-Id - The order ID

• X-Violet-Bag-Id - The bag ID that was shipped

ORDER_DELIVERED

Trigger: When a bag's fulfillment status changes to DELIVERED.

This means:

• The carrier or merchant has confirmed delivery to the customer

• The bag has reached its final destination

• All items in this bag have been successfully delivered

Use Case: Subscribe to this event to:

• Confirm successful delivery to customer

• Update order status to delivered

• Trigger post-delivery workflows (review requests, satisfaction surveys)

• Close out order tracking

• Update fulfillment analytics

Important: This event fires at the bag level when the carrier or merchant confirms delivery. It represents the final fulfillment milestone for that bag.

Additional Headers:

• X-Violet-Order-Id - The order ID

• X-Violet-Bag-Id - The bag ID that was delivered

ORDER_REFUNDED

Trigger: When a bag's status or financial status changes to REFUNDED. This occurs when:

• A merchant initiates a refund through their platform

• A refund is processed via Violet's API

• Funds are returned to the customer

• The bag's status changes to REFUNDED OR the bag's financial status changes to REFUNDED

Common Causes:

• Customer dissatisfaction or complaints

• Incorrect items shipped

• Goodwill gestures or compensation

• Merchant-initiated refunds for service issues

Use Case: Monitor refunds to:

• Update financial records and accounting systems

• Track customer satisfaction metrics and refund rates

• Reconcile payment transactions

• Trigger customer service workflows

• Update order status in dashboards

Important Distinctions:

• Refunds without returns: This event can fire when a refund is issued as a gesture of goodwill without requiring items to be physically returned

• Refunds vs Cancellations: A refund doesn't always mean the order is cancelled—items may have been shipped before the refund

• Partial vs Full Refunds: The event fires for both partial and full refunds. Check the bag's financial status to determine the refund amount

Related Events:

• ORDER_CANCELLED - For order cancellations (may occur with or without refund)

• See Transfer Webhooks for tracking fund reversals to merchants

Additional Headers:

• X-Violet-Order-Id - The order ID

• X-Violet-Bag-Id - The bag ID that was refunded

ORDER_CANCELLED

Trigger: When a bag's status changes to CANCELED.

Common Scenarios:

• Merchant cancels the order through their platform

• Order cannot be fulfilled and is cancelled

• Multi-bag order has individual bags fail during submission

Use Case: Monitor cancellations to:

• Update order status

• Release reserved inventory

• Process refunds if applicable

• Track cancellation metrics

• Trigger customer notifications

Note: Cancellations may occur with or without refunds depending on the order state and timing. Check the bag's financial status to determine if a refund was also processed.

Additional Headers:

• X-Violet-Order-Id - The order ID

• X-Violet-Bag-Id - The bag ID that was cancelled

ORDER_FAILED

Trigger: When an order or bag fails during creation or processing.

Common Scenarios:

• Order submission to merchant platform fails

• Validation errors during order creation

• Payment processing failures during order placement

• Merchant platform API errors or timeouts

• Product availability issues detected during submission

• Invalid or incompatible order data

Use Case: Subscribe to this event to:

• Handle order creation failures gracefully

• Implement retry logic for transient failures

• Alert customers of order submission issues

• Track order failure rates and patterns

• Build robust error handling workflows

• Capture detailed error information for debugging

What's Included: The webhook payload contains detailed error information including:

• Error messages describing what went wrong

• Error codes for programmatic handling

• Order and bag details that were attempted

• Context about which part of the order submission failed

Use Case Examples:

• Customer Notifications: Immediately notify customers when their order fails to process

• Retry Strategies: Implement intelligent retry logic for temporary failures (e.g., merchant platform timeout)

• Support Workflows: Create support tickets automatically for failed orders

• Analytics: Track failure patterns to identify systemic issues or merchant platform problems

Important: This event fires when order or bag creation fails completely, before the order is accepted by the merchant. This is different from ORDER_CANCELLED, which fires after an order has been accepted but is subsequently cancelled.

Additional Headers:

• X-Violet-Order-Id - The order ID (if order was created before failure)

• X-Violet-Bag-Id - The bag ID (if applicable to a specific bag)

Webhook Headers

In addition to the default webhook headers, order webhooks include these additional headers:

X-Violet-Order-Id

Contains the Violet Order ID for the order that triggered the event.

X-Violet-Bag-Id

Contains the Bag ID associated with the order.

Related Documentation

• Handling Webhooks - Learn how to properly process webhook events

• Order and Bag States - Understand order lifecycle states

• Simulating Webhook Events - Test order webhooks in your development environment

Common Integration Patterns

Order Placement and Fulfillment

ORDER_ACCEPTED → Order acknowledged → Validate inventory
ORDER_COMPLETED → Update inventory → Send confirmation email → Trigger fulfillment
ORDER_SHIPPED → Update tracking info → Notify customer → Update order status
ORDER_DELIVERED → Confirm delivery → Trigger post-delivery workflows → Request review

Refund Handling

ORDER_REFUNDED → Check refund amount → Update financials → Adjust commissions

Order Lifecycle Monitoring

ORDER_COMPLETED → Log order → Monitor for ORDER_SHIPPED
If no ORDER_SHIPPED after X days → Alert for delayed fulfillment

Coordinating with Other Events

Order events often occur in conjunction with other webhook events. Understanding the full flow helps ensure proper processing:

Successful Order Flow

ORDER_ACCEPTED → Order acknowledged
ORDER_COMPLETED → Order placed
PAYMENT_TRANSACTION_CAPTURE_STATUS_CAPTURED → Payment captured
TRANSFER_SENT → Funds sent to merchant
ORDER_SHIPPED → Merchant fulfills order
ORDER_DELIVERED → Order delivered to customer

Full Refund Flow

ORDER_REFUNDED → Refund initiated
PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED → Customer refunded
TRANSFER_REVERSED → Funds reversed from merchant

Partial Refund Flow

ORDER_REFUNDED (partial) → Partial refund initiated
PAYMENT_TRANSACTION_CAPTURE_STATUS_PARTIALLY_REFUNDED → Partial customer refund
TRANSFER_PARTIALLY_REFUNDED → Partial funds reversed from merchant

Refund Flow (with returned items)

ORDER_REFUNDED → Refund processed (check SKU status for returned items)
PAYMENT_TRANSACTION_CAPTURE_STATUS_REFUNDED → Customer receives refund

Monitor all related event types for complete visibility into the order lifecycle.

Best Practices

1. Use specific events when possible - Instead of relying solely on ORDER_UPDATED, subscribe to specific events like ORDER_SHIPPED or ORDER_REFUNDED for clearer business logic.

2. Handle idempotency - Use the X-Violet-Event-Id header to ensure you process each event only once, even if it's delivered multiple times.

3. Process asynchronously - Return a 2xx response quickly and process the order update in the background to avoid timeouts.

4. Validate order state - Always check the current order state in the webhook payload, as multiple events may arrive in quick succession.

5. Monitor all lifecycle events - Subscribe to all relevant order events to maintain an accurate view of order status in your system.

6. Coordinate with payment and transfer events - Order events are often part of a larger flow involving payment transactions and transfers. Monitor all related events for complete financial visibility.

7. Track bag-level status - Remember that individual bags can have different states within the same order. Check bag status when detailed fulfillment tracking is needed.