Get Order Status

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>'

import requests

url = "https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status"

headers = {
    "x-firmly-authorization": "<x-firmly-authorization>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'x-firmly-authorization': '<x-firmly-authorization>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-firmly-authorization: <x-firmly-authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-firmly-authorization", "<x-firmly-authorization>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status")
  .header("x-firmly-authorization", "<x-firmly-authorization>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-firmly-authorization"] = '<x-firmly-authorization>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

string

required

Device authentication token or service binding authentication token

Path Parameters

string

required

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

string

required

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

Response

string

required

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

string

required

The merchant platform order number

object

Total refunded amount

Show Amount Properties

string

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

number

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

number

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

string

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

string

URL to the merchant’s order status page

array

Array of items in the order with individual status

Show Line Item Properties

string

required

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

string

required

Product SKU identifier

string

required

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

number

Quantity ordered

number

Quantity that has been fulfilled/shipped

number

Quantity that has been returned

object

Tracking information for this line item

Show Tracking Properties

string

Shipment tracking number

string

URL to track the shipment

string

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

string

ISO 8601 timestamp when the item was shipped

string

ISO 8601 timestamp when the item was delivered

boolean

Whether this item is eligible for return

string

ISO 8601 date by which the item must be returned

object

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

array

Array of fulfillment shipments

Show Fulfillment Properties

string

required

Fulfillment identifier

string

required

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

string

Shipment tracking number

string

URL to track the shipment

string

Shipping carrier name

string

ISO 8601 timestamp when the shipment was dispatched

string

ISO 8601 date of estimated delivery

string

ISO 8601 timestamp when the shipment was delivered

array

Array of SKUs included in this fulfillment

array

Timeline of order events

Show Event Properties

string

required

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

string

required

ISO 8601 timestamp of the event

string

Human-readable description of the event

string

SKU of the related line item, if applicable

object

Additional event-specific metadata

array

Array of return requests

Show Return Properties

string

required

Return request identifier

string

required

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

array

Items included in this return

Show Return Line Item Properties

string

required

Product SKU

number

required

Quantity being returned

object

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

object

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

object

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

object

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

object

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

object

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

object

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

string

ISO 8601 timestamp when the return was initiated

array

Array of refund transactions

Show Refund Properties

string

required

Refund transaction identifier

object

required

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

string

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

string

ISO 8601 timestamp when the refund was processed

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'

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);

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)

{
  "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)

⌘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>'

import requests

url = "https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status"

headers = {
    "x-firmly-authorization": "<x-firmly-authorization>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'x-firmly-authorization': '<x-firmly-authorization>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "x-firmly-authorization: <x-firmly-authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-firmly-authorization", "<x-firmly-authorization>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status")
  .header("x-firmly-authorization", "<x-firmly-authorization>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firmly.work/api/v1/orders/domains/{domain}/order/{orderId}/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-firmly-authorization"] = '<x-firmly-authorization>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Overview

Authentication

Path Parameters

Response

Code Examples

Error Responses

​Overview

​Authentication

​Path Parameters

​Response

​Code Examples

​Error Responses

​Related Endpoints

Overview

Authentication

Path Parameters

Response

Code Examples

Error Responses

Related Endpoints