Orders

Manages the full lifecycle of single and multi-merchant orders — from estimation and creation through fulfillment, payment, and refunds.

Overview

An Order represents a single customer transaction that may span multiple merchants. Because Violet connects your application to many independent storefronts, a single checkout can produce items from several sellers. To handle this, every order is split into Bags — one per merchant.

Order
├── Customer
├── Shipping Address
├── Billing Address
├── Payment Method
├── Bag (Merchant A)
│   ├── SKUs
│   ├── Shipping Method
│   ├── Fulfillments
│   └── Refunds
├── Bag (Merchant B)
│   ├── SKUs
│   ├── Shipping Method
│   ├── Fulfillments
│   └── Refunds
└── Transactions

The Order holds customer-level data (addresses, payment, totals), while each Bag tracks merchant-specific state independently — its own status, financial status, fulfillment status, shipping method, and line items. This means one bag can be shipped and completed while another is still processing.

All monetary values are expressed in the smallest currency unit (e.g., cents for USD). An order total of $49.99 is represented as 4999.

Creating orders

There are two ways to create an order:

Multi-step checkout

Build an order incrementally through the Carts endpoints. This flow lets you:

1. Create a cart

2. Add SKUs from one or more merchants

3. Set customer information

4. Apply a shipping address and select shipping methods

5. Apply a payment method

6. Submit the cart, which creates the order

This approach is best when your UI guides the customer through discrete checkout steps.

Direct Order Submission (DOS)

Submit a complete order in a single POST /orders request. The payload includes everything — customer, bags with SKUs and prices, shipping and billing addresses, and an optional payment method. Violet validates inventory, pricing, and payment, then creates the order on each merchant's commerce platform.

This approach is best for server-to-server integrations, marketplace order ingestion, or any flow where you already have all order data assembled.

Estimating orders

Before creating an order, you can call POST /orders/estimate to preview totals without persisting anything. Provide one or more SKUs and a shipping address, and Violet returns estimated subtotals, taxes, shipping costs, and available shipping methods — grouped by merchant. This is useful for showing customers an order summary before they commit.

Order lifecycle

Order status

Tracks the overall state of the order across all bags.

Status	Description
IN_PROGRESS	The order is open and being assembled (cart phase).
PROCESSING	Checkout has been submitted; bags are being sent to merchants.
REQUIRES_ACTION	The order needs manual intervention before it can proceed.
COMPLETED	All bags have reached a terminal state.
CANCELED	The order has been canceled.

Bag status

Each bag progresses independently through its own lifecycle.

Status	Description
IN_PROGRESS	The bag is being assembled as part of a cart.
SUBMITTED	The bag has been sent to the merchant's platform.
ACCEPTED	The merchant has accepted the bag.
REJECTED	The merchant has rejected the bag.
COMPLETED	The bag has been fully fulfilled and delivered.
CANCELED	The bag has been canceled.
REFUNDED	A full refund has been processed for the bag.
PARTIALLY_REFUNDED	A partial refund has been processed.

Bag financial status

Tracks the payment state of each bag.

Status	Description
UNPAID	No payment has been captured.
AUTHORIZED	Payment has been authorized but not yet captured.
PAID	Payment has been captured.
VOIDED	The payment authorization has been voided.
REFUNDED	The full payment has been refunded.
PARTIALLY_REFUNDED	A partial refund has been issued.

Bag fulfillment status

Tracks the shipping and delivery state of each bag.

Status	Description
PROCESSING	The bag is being prepared for shipment.
SHIPPED	All items in the bag have shipped.
PARTIALLY_SHIPPED	Some items have shipped; others are still being prepared.
DELIVERED	All items have been delivered.

Order Webhook events

Violet publishes webhook events as orders progress through their lifecycle. Events are triggered at the bag level, since each bag moves independently.

Event	Trigger
ORDER_ACCEPTED	A bag is accepted by the merchant.
ORDER_SHIPPED	A bag has shipped.
ORDER_DELIVERED	A bag has been delivered.
ORDER_COMPLETED	A bag has reached its terminal completed state.
ORDER_REFUNDED	A refund has been processed for a bag.
ORDER_CANCELED	A bag has been canceled.
ORDER_FAILED	A bag submission or processing has failed.
ORDER_UPDATED	A general update has occurred on a bag.

See Events for details on subscribing to webhooks.

Available endpoints:

POST /v1/orders/estimate
POST /v1/orders
 GET /v1/orders
 GET /v1/orders/{order_id}
POST /v1/orders/search
POST /v1/orders/bags/search