> ## Documentation Index
> Fetch the complete documentation index at: https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Orders: Trade Types and Lifecycle in Coinbase Advanced Trade

> Learn about order types, statuses, and the full lifecycle of a trade from creation to settlement in the Coinbase Advanced Trade API.

Orders are the mechanism through which you buy and sell assets on Coinbase Advanced Trade. When you submit an order, you instruct the exchange to execute a trade on your behalf — either immediately at the best available market price, or conditionally when specific price conditions are met. Understanding order types, statuses, and the full lifecycle of an order is essential to building reliable trading applications.

## What Is an Order?

An order represents your intent to buy or sell a specific quantity of a base asset (e.g., BTC) using a quote asset (e.g., USD) on a given product (e.g., `BTC-USD`). Orders are matched against the exchange's order book. Depending on the order type and current market conditions, an order may fill immediately, partially, remain open, or fail entirely.

Every order has:

* A **side** — whether you are buying or selling
* A **type** — the execution strategy (market, limit, stop-limit)
* A **status** — the current state of the order
* A **product** — the trading pair the order applies to

## Order Types

Coinbase Advanced Trade supports three primary order types:

### MARKET

A market order executes immediately at the best available price in the order book. You specify only the quantity (or the total spend amount), and the exchange fills your order at whatever price the market offers at that moment.

> [!WARNING]
>
> Market orders do not guarantee a specific price. In fast-moving or low-liquidity markets, the actual fill price may differ significantly from the last quoted price — a phenomenon called **slippage**.

### LIMIT

A limit order lets you set a maximum price you are willing to pay (for a buy) or a minimum price you are willing to accept (for a sell). The order will only fill at your specified price or better. If the market does not reach your price, the order remains open until it fills, is cancelled, or expires.

Limit orders give you price certainty at the cost of execution certainty — your order may never fill if the market moves away from your price.

### STOP\_LIMIT

A stop-limit order combines a stop trigger with a limit order. You define two prices:

* **Stop price** — The price at which the order is activated and submitted to the order book
* **Limit price** — The price at or better than which the activated order will fill

Stop-limit orders are commonly used to cap losses (stop-loss) or to enter a position once a breakout is confirmed.

> [!NOTE]
>
> A stop-limit order is **not** active on the order book until the stop price is triggered. Before the stop is reached, the order will appear with a pending or open status but will not participate in matching.

## Order Sides

Every order must specify a **side**:

| Side | Description |
| - | - |
| `BUY` | You are purchasing the base asset using the quote asset (e.g., buying BTC with USD) |
| `SELL` | You are selling the base asset to receive the quote asset (e.g., selling BTC for USD) |

## Order Statuses

As an order moves through the exchange, it transitions through a series of statuses:

**OPEN** `status`

The order has been accepted and is active on the order book. It has not yet been fully filled and is awaiting matching.

**FILLED** `status`

The order has been completely executed. The full requested quantity has been matched and the trade has settled.

**CANCELLED** `status`

The order was cancelled before it could be fully filled. This may be the result of a manual cancellation, a time-in-force expiry, or an IOC/FOK condition that could not be met.

**EXPIRED** `status`

The order reached its expiration time (set via `end_time` for GTD orders) without being filled and was automatically removed from the order book.

**FAILED** `status`

The order could not be placed. This can occur due to insufficient funds, invalid parameters, or exchange-side rejections.

## Time in Force

Time-in-force (TIF) options control how long an order remains active if it is not immediately filled. The available options are:

| TIF | Name | Behavior |
| - | - | - |
| `GTC` | Good Till Cancelled | The order remains open until it is fully filled or manually cancelled. This is the most common setting for limit orders. |
| `GTD` | Good Till Date | The order remains open until it is fully filled or until a specified date and time (`end_time`), whichever comes first. |
| `IOC` | Immediate or Cancel | The order must fill immediately (in whole or in part). Any unfilled portion is cancelled instantly. |
| `FOK` | Fill or Kill | The order must fill completely and immediately. If the full quantity cannot be filled at once, the entire order is cancelled. |

> [!TIP]
>
> Use `GTC` for passive limit orders when you are willing to wait for the market to reach your price. Use `IOC` or `FOK` for aggressive orders where partial fills or waiting are unacceptable.

## Order Lifecycle

Understanding how an order moves from submission to settlement helps you design robust error handling and state management in your application.

1. **Submission** — You send a `POST` request to create an order. The API validates your parameters (sufficient balance, valid product, correct size precision) and returns an `order_id`.

2. **Acceptance** — If validation passes, the order enters the `OPEN` state and is placed on the order book (for limit orders) or routed for immediate matching (for market orders).

3. **Matching** — The exchange's matching engine continuously pairs buy and sell orders. A limit order fills when a counterparty order crosses your price. A market order fills against existing liquidity immediately.

4. **Partial Fill** — An order may fill in multiple smaller trades (called fills) over time. The `filled_size` and `filled_value` fields update as each partial fill occurs. The order remains `OPEN` until fully filled.

5. **Resolution** — The order reaches a terminal state: `FILLED` (fully executed), `CANCELLED` (manually or by TIF policy), or `EXPIRED` (GTD time elapsed).

6. **Settlement** — Once filled, your account balances update. The acquired asset appears in `available_balance`, and any held funds for the order are released.

> [!NOTE]
>
> The `order_id` returned by the API is Coinbase's internal identifier for the order. You may also supply your own `client_order_id` at creation time for idempotency and easier reconciliation on your end. These are two separate identifiers — use `order_id` when querying or cancelling orders via the API.

## Key Order Fields

**order\_id** `string` *required*

The unique identifier assigned by Coinbase when the order is created. Use this to query, cancel, or reference the order in subsequent API calls.

**client\_order\_id** `string`

An optional identifier you supply at creation time. Useful for idempotency checks and for correlating API orders with your internal records.

**product\_id** `string` *required*

The trading pair for the order (e.g., `"BTC-USD"`).

**side** `string` *required*

Whether the order is a `BUY` or `SELL`.

**order\_type** `string` *required*

The order strategy: `MARKET`, `LIMIT`, or `STOP_LIMIT`.

**status** `string`

The current state of the order: `OPEN`, `FILLED`, `CANCELLED`, `EXPIRED`, or `FAILED`.

**filled\_size** `string`

The quantity of the base asset that has been filled so far, as a string.

**filled\_value** `string`

The total quote asset value of all fills so far, as a string.

**average\_filled\_price** `string`

The average price per unit across all fills, as a string. Empty until at least one fill has occurred.

**created\_time** `string`

ISO 8601 timestamp of when the order was created.

## Example Order Object

The following is an example of a filled limit buy order for 0.01 BTC on the `BTC-USD` product:

```json theme={null}
{
  "order_id": "f7e8d9c0-b1a2-3456-cdef-789012345678",
  "client_order_id": "my-order-001",
  "product_id": "BTC-USD",
  "side": "BUY",
  "order_type": "LIMIT",
  "status": "FILLED",
  "time_in_force": "GTC",
  "created_time": "2024-01-20T09:15:00Z",
  "completion_percentage": "100",
  "filled_size": "0.01",
  "average_filled_price": "65400.00",
  "filled_value": "654.00",
  "number_of_fills": "1",
  "order_configuration": {
    "limit_limit_gtc": {
      "base_size": "0.01",
      "limit_price": "65500.00",
      "post_only": false
    }
  }
}
```

In this example, the order was placed with a limit price of `65500.00` but filled at the better price of `65400.00`, resulting in a total fill value of `654.00 USD`.

## Next Steps

Now that you understand how orders work, learn how to place your first order using the API:

* [Create an Order](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/guides/place-order.md)
* [List Orders API Reference](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/api/orders/list-orders.md)
* [Get Order API Reference](https://httpscashapplaunchbitcoinzann69yc4dfud2ascom.mintlify.site/api/orders/get-order.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.