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.

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.

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.

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.

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:

{
  "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
• List Orders API Reference
• Get Order API Reference