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

# Get Order Status

> Retrieves real-time order status including tracking, fulfillments, returns, and refunds from the merchant platform

## Overview

The Get Order Status endpoint retrieves the current status of a placed order directly from the merchant platform. Use this endpoint for post-checkout order tracking to display:

* Current order status and fulfillment progress
* Shipment tracking information with carrier details
* Return and refund status
* Order timeline events

The response is assembled in real-time via the merchant's platform adapter, so the data reflects the latest state from the source system.

<Note>
  Response fields vary by merchant platform adapter — most merchants return only a subset of the fields documented below. Only **required** fields are guaranteed in every response:

  * **Top-level:** `status`, `order_number`
  * **Line items** (when present): `line_item_id`, `sku`, `status`
  * **Fulfillments** (when present): `id`, `status`
  * **Events** (when present): `type`, `timestamp`
  * **Returns** (when present): `id`, `status`; nested return line items: `sku`, `quantity`
  * **Refunds** (when present): `id`, `amount` (with `currency` and `value`)
</Note>

## Authentication

<ParamField header="x-firmly-authorization" type="string" required>
  Device authentication token or service binding authentication token
</ParamField>

## Path Parameters

<ParamField path="domain" type="string" required>
  Domain of the merchant website (e.g., `bestbuy.com`)
</ParamField>

<ParamField path="orderId" type="string" required>
  The order identifier returned from the Place Order or Complete Order endpoints
</ParamField>

## Response

<ResponseField name="status" type="string" required>
  Current order status. One of: `pending`, `confirmed`, `processing`, `on_its_way`, `shipped`, `partially_delivered`, `delivered`, `cancelled`, `returned`, `partially_returned`
</ResponseField>

<ResponseField name="order_number" type="string" required>
  The merchant platform order number
</ResponseField>

<ResponseField name="refund_total" type="object">
  Total refunded amount

  <Expandable title="Amount Properties">
    <ResponseField name="currency" type="string">
      Three-letter currency code (e.g., "USD")
    </ResponseField>

    <ResponseField name="value" type="number">
      Amount as a decimal (e.g., 29.99)
    </ResponseField>

    <ResponseField name="number" type="number">
      Amount in smallest currency unit (e.g., 2999)
    </ResponseField>

    <ResponseField name="symbol" type="string">
      Currency symbol (e.g., "\$")
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="order_status_page_url" type="string">
  URL to the merchant's order status page
</ResponseField>

<ResponseField name="line_items" type="array">
  Array of items in the order with individual status

  <Expandable title="Line Item Properties">
    <ResponseField name="line_item_id" type="string" required>
      Firmly line item identifier from the original cart, useful for correlating order items back to cart line items
    </ResponseField>

    <ResponseField name="sku" type="string" required>
      Product SKU identifier
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Item-level status. Same enum as the top-level `status` field
    </ResponseField>

    <ResponseField name="quantity" type="number">
      Quantity ordered
    </ResponseField>

    <ResponseField name="fulfilled_quantity" type="number">
      Quantity that has been fulfilled/shipped
    </ResponseField>

    <ResponseField name="returned_quantity" type="number">
      Quantity that has been returned
    </ResponseField>

    <ResponseField name="tracking" type="object">
      Tracking information for this line item

      <Expandable title="Tracking Properties">
        <ResponseField name="tracking_number" type="string">
          Shipment tracking number
        </ResponseField>

        <ResponseField name="tracking_url" type="string">
          URL to track the shipment
        </ResponseField>

        <ResponseField name="carrier" type="string">
          Shipping carrier name (e.g., "UPS", "FedEx")
        </ResponseField>

        <ResponseField name="shipped_at" type="string">
          ISO 8601 timestamp when the item was shipped
        </ResponseField>

        <ResponseField name="delivered_at" type="string">
          ISO 8601 timestamp when the item was delivered
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="return_eligible" type="boolean">
      Whether this item is eligible for return
    </ResponseField>

    <ResponseField name="return_by_date" type="string">
      ISO 8601 date by which the item must be returned
    </ResponseField>

    <ResponseField name="refund_amount" type="object">
      Per-item refund amount (when a return has been processed). Amount object with currency, value, number, and symbol fields
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="fulfillments" type="array">
  Array of fulfillment shipments

  <Expandable title="Fulfillment Properties">
    <ResponseField name="id" type="string" required>
      Fulfillment identifier
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Fulfillment status (e.g., "shipped", "delivered")
    </ResponseField>

    <ResponseField name="tracking_number" type="string">
      Shipment tracking number
    </ResponseField>

    <ResponseField name="tracking_url" type="string">
      URL to track the shipment
    </ResponseField>

    <ResponseField name="carrier" type="string">
      Shipping carrier name
    </ResponseField>

    <ResponseField name="shipped_at" type="string">
      ISO 8601 timestamp when the shipment was dispatched
    </ResponseField>

    <ResponseField name="estimated_delivery" type="string">
      ISO 8601 date of estimated delivery
    </ResponseField>

    <ResponseField name="delivered_at" type="string">
      ISO 8601 timestamp when the shipment was delivered
    </ResponseField>

    <ResponseField name="line_item_skus" type="array">
      Array of SKUs included in this fulfillment
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="events" type="array">
  Timeline of order events

  <Expandable title="Event Properties">
    <ResponseField name="type" type="string" required>
      Event type. One of: `order_placed`, `payment_captured`, `shipped`, `delivered`, `return_initiated`, `return_completed`, `refund_processed`, `cancelled`
    </ResponseField>

    <ResponseField name="timestamp" type="string" required>
      ISO 8601 timestamp of the event
    </ResponseField>

    <ResponseField name="description" type="string">
      Human-readable description of the event
    </ResponseField>

    <ResponseField name="line_item_sku" type="string">
      SKU of the related line item, if applicable
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Additional event-specific metadata
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="returns" type="array">
  Array of return requests

  <Expandable title="Return Properties">
    <ResponseField name="id" type="string" required>
      Return request identifier
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Return status (e.g., "initiated", "received", "completed")
    </ResponseField>

    <ResponseField name="line_items" type="array">
      Items included in this return

      <Expandable title="Return Line Item Properties">
        <ResponseField name="sku" type="string" required>
          Product SKU
        </ResponseField>

        <ResponseField name="quantity" type="number" required>
          Quantity being returned
        </ResponseField>

        <ResponseField name="refund_amount" type="object">
          Refund amount for this line item (Amount object with `currency`, `value`, `number`, `symbol`)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="refund_amount" type="object">
      Total refund amount for this return (Amount object with `currency`, `value`, `number`, `symbol`)
    </ResponseField>

    <ResponseField name="refund_product_price" type="object">
      Product price portion of the refund (Amount object with `currency`, `value`, `number`, `symbol`)
    </ResponseField>

    <ResponseField name="refund_sales_tax" type="object">
      Sales tax portion of the refund (Amount object with `currency`, `value`, `number`, `symbol`)
    </ResponseField>

    <ResponseField name="refund_shipping_total" type="object">
      Shipping cost portion of the refund (Amount object with `currency`, `value`, `number`, `symbol`)
    </ResponseField>

    <ResponseField name="restocking_fee" type="object">
      Restocking fee charged for this return (Amount object with `currency`, `value`, `number`, `symbol`)
    </ResponseField>

    <ResponseField name="other_fees" type="object">
      Any other fees associated with this return (Amount object with `currency`, `value`, `number`, `symbol`)
    </ResponseField>

    <ResponseField name="initiated_at" type="string">
      ISO 8601 timestamp when the return was initiated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="refunds" type="array">
  Array of refund transactions

  <Expandable title="Refund Properties">
    <ResponseField name="id" type="string" required>
      Refund transaction identifier
    </ResponseField>

    <ResponseField name="amount" type="object" required>
      Refund amount (Amount object with `currency`, `value`, `number`, `symbol`)
    </ResponseField>

    <ResponseField name="status" type="string">
      Refund status (e.g., "pending", "processed")
    </ResponseField>

    <ResponseField name="processed_at" type="string">
      ISO 8601 timestamp when the refund was processed
    </ResponseField>

    <ResponseField name="reason" type="string">
      Reason for the refund
    </ResponseField>
  </Expandable>
</ResponseField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.firmly.work/api/v1/orders/domains/bestbuy.com/order/ord_01H2XVBR8C8JS5MQSFPJ8HF9SA/status \
    --header 'x-firmly-authorization: YOUR_TOKEN'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.firmly.work/api/v1/orders/domains/bestbuy.com/order/ord_01H2XVBR8C8JS5MQSFPJ8HF9SA/status',
    {
      method: 'GET',
      headers: {
        'x-firmly-authorization': 'YOUR_TOKEN'
      }
    }
  );

  const orderStatus = await response.json();
  console.log(orderStatus);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.firmly.work/api/v1/orders/domains/bestbuy.com/order/ord_01H2XVBR8C8JS5MQSFPJ8HF9SA/status',
      headers={
          'x-firmly-authorization': 'YOUR_TOKEN'
      }
  )

  order_status = response.json()
  print(order_status)
  ```
</CodeGroup>

<ResponseExample>
  ```json theme={null}
  {
    "status": "partially_delivered",
    "order_number": "BBY01-807121052010",
    "refund_total": {
      "currency": "USD",
      "value": 27.53,
      "number": 2753,
      "symbol": "$"
    },
    "order_status_page_url": "https://www.bestbuy.com/profile/ss/orders/order-details/BBY01-807121052010/view",
    "line_items": [
      {
        "line_item_id": "a1b2c3d4-0005-0005-0005-000000000001",
        "sku": "6377581",
        "status": "returned",
        "quantity": 1,
        "tracking": {
          "tracking_number": "D10016972979292",
          "carrier": "OnTrac",
          "shipped_at": "2025-12-14T14:54:33Z",
          "delivered_at": "2025-12-14T00:00:00.000Z"
        },
        "refund_amount": {
          "currency": "USD",
          "value": 27.53,
          "number": 2753,
          "symbol": "$"
        }
      },
      {
        "line_item_id": "a1b2c3d4-0005-0005-0005-000000000002",
        "sku": "6617430",
        "status": "delivered",
        "quantity": 1
      }
    ],
    "fulfillments": [
      {
        "id": "c1568c71-d584-49c4-affc-3e756dfc3de0",
        "status": "DELIVERED",
        "tracking_number": "D10016972979292",
        "carrier": "OnTrac",
        "shipped_at": "2025-12-14T14:54:33Z",
        "delivered_at": "2025-12-14T00:00:00.000Z",
        "estimated_delivery": "2025-12-14T00:00:00.000Z",
        "line_item_skus": ["6377581"]
      }
    ],
    "events": [
      {
        "type": "order_placed",
        "timestamp": "2025-12-10T15:18:50-06:00",
        "description": "Order placed"
      },
      {
        "type": "delivered",
        "timestamp": "2025-12-14T14:54:33-06:00",
        "description": "Delivered",
        "line_item_sku": "6377581"
      },
      {
        "type": "refund_completed",
        "timestamp": "2026-01-05T10:00:00.000Z",
        "description": "Refund completed"
      }
    ],
    "returns": [
      {
        "id": "9725356645660",
        "status": "Receipt Closed",
        "line_items": [
          {
            "sku": "6377581",
            "quantity": 1,
            "refund_amount": {
              "currency": "USD",
              "value": 27.53,
              "number": 2753,
              "symbol": "$"
            }
          }
        ],
        "refund_amount": {
          "currency": "USD",
          "value": 27.53,
          "number": 2753,
          "symbol": "$"
        },
        "refund_product_price": {
          "currency": "USD",
          "value": 24.99,
          "number": 2499,
          "symbol": "$"
        },
        "refund_sales_tax": {
          "currency": "USD",
          "value": 2.54,
          "number": 254,
          "symbol": "$"
        },
        "refund_shipping_total": {
          "currency": "USD",
          "value": 0,
          "number": 0,
          "symbol": "$"
        },
        "restocking_fee": {
          "currency": "USD",
          "value": 0,
          "number": 0,
          "symbol": "$"
        },
        "initiated_at": "2025-12-22"
      }
    ]
  }
  ```
</ResponseExample>

## Error Responses

<Accordion title="401 Unauthorized">
  Device authentication failed — the token is missing, invalid, or expired.

  ```json theme={null}
  {
    "code": 401,
    "error": "InvalidJWTToken",
    "description": "The JWT token is invalid"
  }
  ```
</Accordion>

<Accordion title="403 Forbidden">
  The authenticated device does not own this order.

  ```json theme={null}
  {
    "code": 403,
    "error": "Forbidden",
    "description": "Device does not have access to this order"
  }
  ```
</Accordion>

<Accordion title="400 Bad Request">
  The order was not found in internal storage.

  ```json theme={null}
  {
    "code": 400,
    "error": "ErrorOrderNotFound",
    "description": "Order not found"
  }
  ```
</Accordion>

<Accordion title="422 Unprocessable Entity">
  The merchant platform adapter does not support order status retrieval.

  ```json theme={null}
  {
    "code": 422,
    "error": "ErrorOperationNotSupported",
    "description": "Order status is not supported for this merchant"
  }
  ```
</Accordion>

<Accordion title="404 Not Found">
  Store configuration not found for the given domain.

  ```json theme={null}
  {
    "code": 404,
    "error": "ErrorDomainNotFound",
    "description": "Store configuration not found for this domain"
  }
  ```
</Accordion>

## Related Endpoints

* [Place Order (v1)](/api-reference/payment/place-order-v1) - Place an order with the Simple Cart API
* [Place Order (v2)](/api-reference/payment/place-order-v2) - Place an order with the Full Cart API
* [Complete Order (v1)](/api-reference/payment/complete-order-v1) - Complete an order from an existing cart
* [Complete Order (v2)](/api-reference/payment/complete-order-v2) - Complete an order from an existing cart (v2)