# 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](https://docs.violet.io/prism/checkout-guides/guides/order-and-bag-states). ## 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](https://docs.violet.io/prism/checkout-guides/guides/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 {% hint style="info" %} 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. {% endhint %} ### 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](https://docs.violet.io/prism/webhooks/events/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](https://docs.violet.io/prism/webhooks/managing-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](https://docs.violet.io/prism/webhooks/handling-webhooks) - Learn how to properly process webhook events * [Order and Bag States](https://docs.violet.io/prism/checkout-guides/guides/order-and-bag-states) - Understand order lifecycle states * [Simulating Webhook Events](https://docs.violet.io/prism/webhooks/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.