Order Fulfillment Amounts in the Orders API

Overview

When querying order details via the Orders API endpoints, the returned asset_token_quantity and payment_token_quantity fields represent the placed order quantities, not the actual fulfilled amounts. This is a common point of confusion for integrators.

💡Reference: Get Order Fulfillments

---

The Issue

The asset_token_quantity and payment_token_quantity fields in the Orders API responses reflect the amount the user initially requested at order placement. They do not reflect:

• Partial fills
• Final settled amounts
• Adjustments due to market price changes or slippage

Relying on these fields for reconciliation, settlement tracking, or balance updates will lead to inaccuracies.

---

The Correct Approach

To obtain the actual fulfillment amounts for an order, we must query the Order Fulfillments API endpoints.

⚠️ Important Notes:

• Each order can have multiple fulfillments (e.g., partial fills over time).
• The sum of all fulfillments for a given order equals the total settled amount.
• Fulfillment records contain precise, finalized quantities for both the asset and the payment token.

---

Best Practices

1. Do not use asset_token_quantity or payment_token_quantity from the Orders API for:

• Updating user balances
• Calculating fees
• Confirming order completion

2. Always fetch fulfillment records for an order to:

• Determine the net settled quantity
• Handle partial fills correctly
• Reconcile transactions with external systems

3. Iterate over all fulfillments associated with an order ID, as a single order may have one or more entries.

---

Additional Context

---

Related Questions

• Q: Why would an order have multiple fulfillments?
  A: Due to liquidity fragmentation, market depth, or execution over time, a single limit or market order may be filled across several distinct trades.
• Q: Should I sum all fulfillments to get the total?
  A: Yes. The sum of all fulfillment amounts equals the final settled quantity for that order.