# 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](https://docs.violet.io/api-reference/orders-and-checkout/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](https://docs.violet.io/api-reference/events/webhooks) 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
```