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.

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 placed and 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

• Order transitions from IN_PROGRESS to an accepted state

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: This event is typically followed by ORDER_UPDATED and ORDER_COMPLETED events as the order progresses through its lifecycle.

Additional Headers:

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

• X-Violet-Bag-Id - The bag ID (if order was placed via bag)

Note: When triggered via a bag placement, both ORDER_ACCEPTED and ORDER_UPDATED events fire together.

ORDER_UPDATED

Trigger: When any changes are made to an order, irrespective of which part of the lifecycle its from.

Common Scenarios:

• Order Status changes (e.g., from IN_PROGRESS to COMPLETED)

• Order metadata or custom field updates

• Order notes or tags modifications

• Customer contact information changes

• Shopper shipping or billing address corrections

Use Case: Subscribe to this event when you need to track all order 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 order placement and payment capture

• ORDER_SHIPPED - For order fulfillment

• ORDER_DELIVERED - For delivery confirmation

• ORDER_REFUNDED - For refunds without cancellation

• ORDER_RETURNED - For returns

• ORDER_CANCELLED - For cancellations

If you are subscribed to both ORDER_UPDATED and specific order events, be aware that multiple events may arrive in quick succession for the same order change. Always check the order state in the payload to determine the current status.

ORDER_COMPLETED

Trigger: When an order has been successfully submitted to all merchants and payment has been captured.

This means:

• At least one bag (merchant-specific order) has been accepted by a merchant's platform

• Payment has been successfully captured for the order

• The order has transitioned from PROCESSING to COMPLETED state

This event is the definitive signal that an order is successfully placed. The order has moved past the brief PROCESSING state (milliseconds) and payment has been captured. At this point, associated bags are in ACCEPTED state and visible in merchants' platforms, ready for fulfillment.

Use Case: This is the primary event for tracking new orders. Subscribe to this event to:

• Update inventory systems

• Trigger fulfillment workflows

• Send order confirmation notifications to customers

• Record sales analytics and metrics

• Begin order tracking and monitoring

• Initialize post-purchase workflows

Important: This event fires when the overall order is complete, but individual bags may still progress through additional states like COMPLETED (all items shipped) or REFUNDED. See Order and Bag States for the complete lifecycle.

ORDER_SHIPPED

Trigger: When an order is fulfilled by a merchant through their commerce platform.

Use Case: Subscribe to this event to:

• Track order fulfillment

• Update order status in your system

• Access tracking information

• Notify customers of shipment

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

ORDER_DELIVERED

Trigger: When a bag is marked as delivered by the merchant or carrier.

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 before order completion.

Additional Headers:

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

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

ORDER_REFUNDED

Trigger: When a refund has been processed for part or all of an order. 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 order's financial_status changes to REFUNDED or PARTIALLY_REFUNDED You can learn more about

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

• Refunds vs Returns: Check the fulfillment_status field to determine if items were physically returned. See Order and Bag States for details

Related Events:

• ORDER_RETURNED - For when items are physically returned (may occur with or without refund)

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

• See Transfer Webhooks for tracking fund reversals to merchants

ORDER_RETURNED

Trigger: When all or part of an order has been returned, with or without a refund.

Use Case: Track returns to:

• Update inventory

• Process return authorizations

• Adjust order status

• Handle restocking

Note: Returns may or may not include refunds. Check the order details to determine if a refund was processed.

ORDER_CANCELLED

Trigger: When all or part of an order has been cancelled, with or without a refund.

Use Case: Monitor cancellations to:

• Update order status

• Release reserved inventory

• Process refunds if applicable

• Track cancellation metrics

Note: Cancellations may occur with or without refunds depending on the order state and timing.

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 and Return Handling

ORDER_REFUNDED → Check refund amount → Update financials → Adjust commissions
ORDER_RETURNED → Update inventory → Process return → Determine refund eligibility

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

Return with Refund Flow

ORDER_RETURNED → Items physically returned
ORDER_REFUNDED → Refund processed after return
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.