# Orders

The **Orders API** provides endpoints for managing customer purchase transactions, tracking order lifecycle statuses, vendor seller store routing, and logistics shipment updates.

---

## What is an Order?

An **Order** in Tradly represents a completed or in-progress purchase transaction made by a customer across one or multiple seller stores within the marketplace.

When a customer checks out:
- A parent **Order** record is created with payment details, customer info, delivery address, and pricing totals (`list_total`, `offer_total`, `shipping_total`, `tax_total`, `grand_total`).
- The order contains one or more **Order Details** (line items representing individual listings/variants purchased).
- For multi-vendor fulfillment, items are linked to seller store accounts (`account_id`), and associated **Shipments** track physical or local fulfillment status for each seller.

---

## Order Status Reference

An Order progresses through distinct lifecycle states represented by `order_status` (numeric ID):

| Status ID | Status Name | Description |
| :---: | :--- | :--- |
| `0` | `Draft` | Order draft initialized prior to cart checkout. |
| `1` | `Incomplete` | Order creation in progress in cart/checkout; unpaid. |
| `2` | `Order Placed` | Order placed & payment confirmed by customer; awaiting seller processing. |
| `3` | `In Process` | Order accepted and being prepared/processed by seller. |
| `4` | `Shipped` | Items dispatched with courier or carrier tracking. |
| `5` | `Delivered` | Order successfully delivered to destination. |
| `6` | `Cancelled by Customer` | Order cancelled by customer prior to fulfillment. |
| `7` | `Cancelled by Admin` | Order cancelled by tenant admin or seller. |
| `8` | `Completed` | Order transaction finalized and completed. |

---

## Shipment Status Reference

Each order fulfillment record (`shipment`) tracks physical delivery or pickup progress via `shipment_status` (numeric ID):

| Status ID | Status Name | Description |
| :---: | :--- | :--- |
| `1` | `Created` | Shipment record created for order line items. |
| `2` | `In Progress` | Seller is packing items and preparing shipment. |
| `3` | `Shipped` | Shipment handed over to logistics courier/carrier. |
| `4` | `Ready for Pickup` | Package ready at seller location for customer collection or courier pickup. |
| `5` | `Out for Delivery` | Courier actively delivering package to customer address. |
| `6` | `Undelivered / Returned` | Delivery attempt failed; package returned to sender. |
| `7` | `Delivered` | Courier marked package as delivered to customer. |
| `8` | `Delivered & Confirmed` | Customer/Admin verified and confirmed receipt of delivery. |
| `9` | `Customer Return Initiated` | Buyer requested return/exchange for shipment items. |
| `10` | `Customer Return Picked` | Return package collected by courier from buyer. |
| `11` | `Customer Return Confirmed` | Returned items received and verified by seller/store. |
| `12` | `Cancelled by Account` | Shipment cancelled by seller store account. |
| `13` | `Cancelled by Customer` | Shipment cancelled by customer. |
| `14` | `Arrived at Location` | Package arrived at intermediary transit hub or pickup locker. |
| `15` | `Cancelled by Admin` | Shipment cancelled by tenant admin. |

---

## Payment Status Reference

| Status ID | Status Name | Description |
| :---: | :--- | :--- |
| `1` | `Unpaid / Pending` | Payment has not been captured yet. |
| `2` | `Paid` | Payment successfully captured. |
| `3` | `Failed` | Payment attempt failed. |
| `4` | `Refunded` | Payment refunded to customer. |

---

## The Order Object Explained

An **Order** object represents a complete customer order transaction. It contains pricing totals, customer info, payment and shipping details, item listings, seller earnings, and shipment tracking:

### Core Order Attributes

- `id` (`number`): Primary key ID of the order.
- `reference_number` (`string`): Unique reference identifier (e.g. `ORD-1001-XYZ`).
- `tenant_id` (`number`): Tenant ID owning the marketplace.
- `user_id` (`number`): Customer user ID.
- `user` (`object`): Customer profile details (`id`, `unique_id`, `first_name`, `last_name`, `email`, `profile_pic`, `dial_code`, `mobile_number`).
- `account_ids` (`array`): Array of seller store account IDs associated with items in this order.
- `order_status` (`number`): Numerical status ID (see status table above).
- `order_status_description` (`string`): Human-readable order status label.
- `payment_status` (`number`): Numerical payment status ID (see payment table above).
- `payment_status_description` (`string`): Human-readable payment status label.
- `completed` (`boolean`): `true` if the order has reached a final state (delivered, completed, or cancelled).
- `currency` (`string`): 3-letter ISO currency code (e.g. `USD`, `EUR`, `MYR`).
- `created_at` (`number`): Unix epoch timestamp of order creation.
- `updated_at` (`number`): Unix epoch timestamp of last update.

### Monetary Amounts (`{ amount, formatted }`)

All price fields are formatted with raw numeric `amount` and localized string `formatted` (e.g. `{ "amount": 105.0, "formatted": "$105.00" }`):

- `list_total`: Total subtotal at original list prices.
- `offer_total`: Total subtotal after listing discounts.
- `tax_total`: Total tax amount charged.
- `shipping_total`: Total shipping fees.
- `grand_total`: Final grand total payable (`offer_total + shipping_total + tax_total`).

### Pricing & Earnings Breakdown

- `customer_pricing` (`object`): Itemized price breakdown shown to the buyer, including `grand_total` and `items` (`customer_sub_total`, `customer_shipping_charge`, `customer_tax`, `customer_coupon`).
- `account_pricing` (`object`): Seller-specific financial breakdown when filtered by `account_id`, including `total_earnings` and itemized subtotal, platform commission, shipping, and tax transactions.

### Delivery & Address Objects

- `payment_method` (`object`): Configured payment method details (`id`, `name`, `type`, `gateway_name`).
- `shipping_method` (`object`): Delivery method chosen (`id`, `name`, `type`, `shipping_charge`).
- `shipping_address` (`object`): Recipient delivery address (`id`, `name`, `phone_number`, `address_line_1`, `address_line_2`, `city`, `state`, `zip_code`, `country`, `landmark`).
- `shipment` (`object`): Active shipment tracking details (`id`, `shipment_status`, `tracking_number`, `courier_name`, `shipped_at`, `delivered_at`).

### Order Detail Items (`order_details`)

Array of purchased products/items in this order:

- `id` (`number`): Order detail line item ID.
- `listing_id` (`number`): Listing ID of the product.
- `quantity` (`number`): Quantity purchased.
- `list_price`, `offer_price`, `special_price`, `tax_charges`, `shipping_charges`: Monetary amount objects for this specific item line.
- `schedule_start_at` / `schedule_end_at`: Start and end dates for booking/rental items (`YYYY-MM-DD` and epoch timestamps).
- `listing` (`object`): Product details (`id`, `title`, `description`, `slug`, `images`, `account_id`, `review_status`).
- `variant` (`object`): Selected variant information if applicable (e.g. Size, Color).
- `order_detail_attributes` (`array`): Custom variant/option attributes selected during purchase.
- `order_detail_item_attributes` (`array`): Per-unit custom attribute inputs collected at checkout.