Get Order Status - Firmly API

GET

api

orders

domains

{domain}

order

{orderId}

status

Get Order Status

curl --request GET \
  --url https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status \
  --header 'Authorization: Bearer <token>' \
  --header 'x-firmly-authorization: <x-firmly-authorization>'

{
  "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"
    }
  ]
}

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.

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)

Authentication

x-firmly-authorization

string

required

Device authentication token or service binding authentication token

Path Parameters

domain

string

required

Domain of the merchant website (e.g., bestbuy.com)

orderId

string

required

The order identifier returned from the Place Order or Complete Order endpoints

Response

status

string

required

Current order status. One of: pending, confirmed, processing, on_its_way, shipped, partially_delivered, delivered, cancelled, returned, partially_returned

order_number

string

required

The merchant platform order number

refund_total

object

Total refunded amount

Show Amount Properties

currency

string

Three-letter currency code (e.g., “USD”)

value

number

Amount as a decimal (e.g., 29.99)

number

Amount in smallest currency unit (e.g., 2999)

symbol

string

Currency symbol (e.g., ”$”)

order_status_page_url

string

URL to the merchant’s order status page

line_items

array

Array of items in the order with individual status

Show Line Item Properties

line_item_id

string

required

Firmly line item identifier from the original cart, useful for correlating order items back to cart line items

sku

string

required

Product SKU identifier

status

string

required

Item-level status. Same enum as the top-level status field

quantity

number

Quantity ordered

fulfilled_quantity

number

Quantity that has been fulfilled/shipped

returned_quantity

number

Quantity that has been returned

tracking

object

Tracking information for this line item

Show Tracking Properties

tracking_number

string

Shipment tracking number

tracking_url

string

URL to track the shipment

carrier

string

Shipping carrier name (e.g., “UPS”, “FedEx”)

shipped_at

string

ISO 8601 timestamp when the item was shipped

delivered_at

string

ISO 8601 timestamp when the item was delivered

return_eligible

boolean

Whether this item is eligible for return

return_by_date

string

ISO 8601 date by which the item must be returned

refund_amount

object

Per-item refund amount (when a return has been processed). Amount object with currency, value, number, and symbol fields

fulfillments

array

Array of fulfillment shipments

Show Fulfillment Properties

string

required

Fulfillment identifier

status

string

required

Fulfillment status (e.g., “shipped”, “delivered”)

tracking_number

string

Shipment tracking number

tracking_url

string

URL to track the shipment

carrier

string

Shipping carrier name

shipped_at

string

ISO 8601 timestamp when the shipment was dispatched

estimated_delivery

string

ISO 8601 date of estimated delivery

delivered_at

string

ISO 8601 timestamp when the shipment was delivered

line_item_skus

array

Array of SKUs included in this fulfillment

events

array

Timeline of order events

Show Event Properties

type

string

required

Event type. One of: order_placed, payment_captured, shipped, delivered, return_initiated, return_completed, refund_processed, cancelled

timestamp

string

required

ISO 8601 timestamp of the event

description

string

Human-readable description of the event

line_item_sku

string

SKU of the related line item, if applicable

metadata

object

Additional event-specific metadata

returns

array

Array of return requests

Show Return Properties

string

required

Return request identifier

status

string

required

Return status (e.g., “initiated”, “received”, “completed”)

line_items

array

Items included in this return

Show Return Line Item Properties

sku

string

required

Product SKU

quantity

number

required

Quantity being returned

refund_amount

object

Refund amount for this line item (Amount object with currency, value, number, symbol)

refund_amount

object

Total refund amount for this return (Amount object with currency, value, number, symbol)

refund_product_price

object

Product price portion of the refund (Amount object with currency, value, number, symbol)

refund_sales_tax

object

Sales tax portion of the refund (Amount object with currency, value, number, symbol)

refund_shipping_total

object

Shipping cost portion of the refund (Amount object with currency, value, number, symbol)

restocking_fee

object

Restocking fee charged for this return (Amount object with currency, value, number, symbol)

other_fees

object

Any other fees associated with this return (Amount object with currency, value, number, symbol)

initiated_at

string

ISO 8601 timestamp when the return was initiated

refunds

array

Array of refund transactions

Show Refund Properties

string

required

Refund transaction identifier

amount

object

required

Refund amount (Amount object with currency, value, number, symbol)

status

string

Refund status (e.g., “pending”, “processed”)

processed_at

string

ISO 8601 timestamp when the refund was processed

reason

string

Reason for the refund

Code Examples

curl --request GET \
  --url https://api.firmly.work/api/v1/orders/domains/bestbuy.com/order/ord_01H2XVBR8C8JS5MQSFPJ8HF9SA/status \
  --header 'x-firmly-authorization: YOUR_TOKEN'

{
  "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"
    }
  ]
}

Error Responses

401 Unauthorized

Device authentication failed — the token is missing, invalid, or expired.

{
  "code": 401,
  "error": "InvalidJWTToken",
  "description": "The JWT token is invalid"
}

403 Forbidden

The authenticated device does not own this order.

{
  "code": 403,
  "error": "Forbidden",
  "description": "Device does not have access to this order"
}

400 Bad Request

The order was not found in internal storage.

{
  "code": 400,
  "error": "ErrorOrderNotFound",
  "description": "Order not found"
}

422 Unprocessable Entity

The merchant platform adapter does not support order status retrieval.

{
  "code": 422,
  "error": "ErrorOperationNotSupported",
  "description": "Order status is not supported for this merchant"
}

404 Not Found

Store configuration not found for the given domain.

{
  "code": 404,
  "error": "ErrorDomainNotFound",
  "description": "Store configuration not found for this domain"
}

Place Order (v1) - Place an order with the Simple Cart API
Place Order (v2) - Place an order with the Full Cart API
Complete Order (v1) - Complete an order from an existing cart
Complete Order (v2) - Complete an order from an existing cart (v2)

OverviewSession management endpoints for multi-domain cart tracking and postal code preferences

⌘I

Get Order Status

curl --request GET \
  --url https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status \
  --header 'Authorization: Bearer <token>' \
  --header 'x-firmly-authorization: <x-firmly-authorization>'

{
  "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"
    }
  ]
}

​Overview

​Authentication

​Path Parameters

​Response

​Code Examples

​Error Responses

​Related Endpoints

Overview

Authentication

Path Parameters

Response

Code Examples

Error Responses

Related Endpoints