> For a complete page index, fetch https://docs.transak.com/llms.txt

# How to use Orders API

Once a user places an order, your app still needs to know what happened to it. Is there an order already in progress? What's in the user's order history? What's the status of one specific order? Can the user back out before paying? The Order APIs answer all four questions.

## What We'll Build

A "My Orders" experience: an active-order check before checkout, a full order history list, a single order details/status view, and a cancel action.

| API                                            | Purpose                                                                           |
| ---------------------------------------------- | --------------------------------------------------------------------------------- |
| `GET /api/whitelabel/orders/get-active-orders` | Check whether the user already has an order in progress before starting a new one |
| `GET /api/whitelabel/orders/get-orders`        | Fetch the user's complete order history                                           |
| `GET /api/whitelabel/orders/get-order-by-id`   | Fetch (or poll) the details and status of one specific order                      |
| `DELETE /api/whitelabel/orders/cancel-order`   | Cancel an order before its payment is completed                                   |

## Authentication Headers

These APIs support both onboarding paths from [Authentication APIs](/guides/how-to-use-authentication-apis). The headers you pass depend on which path your integration uses.

Pass these headers on every order API call when your platform owns the user's authentication:

| Header              | Description                            |
| ------------------- | -------------------------------------- |
| `x-user-identifier` | The authenticated user's email address |
| `x-access-token`    | Your Partner Access Token              |

Pass this header on every order API call when Transak owns the user's authentication:

| Header          | Description                                                |
| --------------- | ---------------------------------------------------------- |
| `Authorization` | The `accessToken` returned from `POST /api/v2/auth/verify` |

## Step 1 — Get Active Orders

Call this before letting a user start checkout. An active order is one that hasn't reached a final state (`COMPLETED`, `CANCELLED`, `FAILED`, `REFUNDED`, or `EXPIRED`) — see the full list on [How to Track Order Status](/guides/track-order-status). If one exists, resume it or offer to cancel it instead of creating a duplicate order.

```bash
curl "https://api-gateway-stg.transak.com/api/v2/active-orders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-ip: USER_IP_ADDRESS" \
  -H "Authorization: USER_ACCESS_TOKEN"
```

`data` is an array. An empty array means the user has no order in progress and can start a new one.

```ts
const { data: activeOrders } = json;
if (activeOrders.length > 0) {
  // Resume or offer to cancel activeOrders[0] instead of starting checkout
}
```

```ts title="getActiveOrders.ts"
const BASE = "https://api-gateway-stg.transak.com";

interface Order {
  orderId: string;
  status: string;
  isBuyOrSell: string;
  fiatCurrency: string;
  cryptoCurrency: string;
  paymentMethod: string;
  network: string;
  walletAddress: string;
  quoteId: string;
  fiatAmount: number;
  cryptoAmount: number;
  totalFeeInFiat: number;
  txHash: string;
}

async function getActiveOrders(params: {
  apiKey: string;
  userIp: string;
  accessToken: string;
}): Promise<Order[]> {
  const res = await fetch(`${BASE}/api/v2/active-orders`, {
    headers: {
      "x-api-key": params.apiKey,
      "x-user-ip": params.userIp,
      Authorization: params.accessToken,
    },
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json.error?.message ?? `HTTP ${res.status}`);
  return json.data as Order[];
}
```

## Step 2 — Get Orders

Fetch the user's complete order history — every order they've ever placed, regardless of status. Use this to render an order list or transaction history screen.

```bash
curl "https://api-gateway-stg.transak.com/api/v2/orders" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-ip: USER_IP_ADDRESS" \
  -H "Authorization: USER_ACCESS_TOKEN"
```

Each item includes `orderId`, `status`, amounts, and `paymentDetails`. Sort or filter client-side by `status` (e.g. show `COMPLETED` and `CANCELLED` separately).

```ts
const { data: orders } = json;
orders.map(o => `${o.orderId} — ${o.status} — ${o.fiatAmount} ${o.fiatCurrency}`);
```

```ts title="getOrders.ts"
const BASE = "https://api-gateway-stg.transak.com";

interface Order {
  orderId: string;
  status: string;
  isBuyOrSell: string;
  fiatCurrency: string;
  cryptoCurrency: string;
  paymentMethod: string;
  fiatAmount: number;
  cryptoAmount: number;
  totalFeeInFiat: number;
  txHash: string;
  transactionLink: string;
}

async function getOrders(params: {
  apiKey: string;
  userIp: string;
  accessToken: string;
}): Promise<Order[]> {
  const res = await fetch(`${BASE}/api/v2/orders`, {
    headers: {
      "x-api-key": params.apiKey,
      "x-user-ip": params.userIp,
      Authorization: params.accessToken,
    },
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json.error?.message ?? `HTTP ${res.status}`);
  return json.data as Order[];
}
```

## Step 3 — Get Order By ID

Fetch a single order using the `orderId` returned from checkout, from Get Orders, or from Get Active Orders. Use this for an order details screen, or poll it on an interval to track a specific order's status until it reaches a final state.

```bash
curl "https://api-gateway-stg.transak.com/api/v2/orders/ORDER_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-ip: USER_IP_ADDRESS" \
  -H "Authorization: USER_ACCESS_TOKEN"
```

See the full status list on [How to Track Order Status](/guides/track-order-status#order-status-reference).

```ts
const { status, txHash, transactionLink } = json.data;
// status: "AWAITING_PAYMENT_FROM_USER" | "PROCESSING" | "COMPLETED" | "CANCELLED" | "FAILED" | ...
```

```ts title="getOrderById.ts"
const BASE = "https://api-gateway-stg.transak.com";

interface Order {
  orderId: string;
  status: string;
  fiatAmount: number;
  cryptoAmount: number;
  txHash: string;
  transactionLink: string;
}

async function getOrderById(params: {
  orderId: string;
  apiKey: string;
  userIp: string;
  accessToken: string;
}): Promise<Order> {
  const res = await fetch(`${BASE}/api/v2/orders/${params.orderId}`, {
    headers: {
      "x-api-key": params.apiKey,
      "x-user-ip": params.userIp,
      Authorization: params.accessToken,
    },
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json.error?.message ?? `HTTP ${res.status}`);
  return json.data as Order;
}

const FINAL_STATUSES = ["COMPLETED", "CANCELLED", "FAILED", "REFUNDED", "EXPIRED"];

async function pollOrderStatus(
  params: Parameters<typeof getOrderById>[0] & { intervalMs?: number; timeoutMs?: number }
): Promise<Order> {
  const { intervalMs = 5000, timeoutMs = 300_000 } = params;
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const order = await getOrderById(params);
    if (FINAL_STATUSES.includes(order.status)) return order;
    await new Promise(resolve => setTimeout(resolve, intervalMs));
  }
  throw new Error("Timed out waiting for order to reach a final status");
}
```

## Step 4 — Cancel Order

Cancels an order that hasn't finished payment yet — useful when the user changes their mind, enters incorrect details, or hits a payment issue.

A cancelled order cannot be reversed. Once cancelled, the user must place a new order.

Pass `cancelReason` as a query parameter and the `orderId` in the path.

```bash
curl -X DELETE "https://api-gateway-stg.transak.com/api/v2/orders/ORDER_ID\
?cancelReason=User%20changed%20their%20mind" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-user-ip: USER_IP_ADDRESS" \
  -H "Authorization: USER_ACCESS_TOKEN"
```

```ts
const { orderId, status } = json.data;
// status: "CANCELLED"
```

```ts title="cancelOrder.ts"
const BASE = "https://api-gateway-stg.transak.com";

async function cancelOrder(params: {
  orderId: string;
  cancelReason: string;
  apiKey: string;
  userIp: string;
  accessToken: string;
}): Promise<{ orderId: string; status: string }> {
  const qs = new URLSearchParams({ cancelReason: params.cancelReason });
  const res = await fetch(`${BASE}/api/v2/orders/${params.orderId}?${qs}`, {
    method: "DELETE",
    headers: {
      "x-api-key": params.apiKey,
      "x-user-ip": params.userIp,
      Authorization: params.accessToken,
    },
  });
  const json = await res.json();
  if (!res.ok) throw new Error(json.error?.message ?? `HTTP ${res.status}`);
  return json.data;
}
```

## Full Flow (Putting It Together)

```ts title="hooks/useOrderManagement.ts"
import { useState } from "react";

const BASE = "https://api-gateway-stg.transak.com";
const FINAL_STATUSES = ["COMPLETED", "CANCELLED", "FAILED", "REFUNDED", "EXPIRED"];

interface Order {
  orderId: string;
  status: string;
  fiatAmount: number;
  cryptoAmount: number;
  fiatCurrency: string;
  cryptoCurrency: string;
  txHash: string;
  transactionLink: string;
}

export function useOrderManagement(apiKey: string, userIp: string, accessToken: string) {
  const [activeOrders, setActiveOrders] = useState<Order[]>([]);
  const [orders, setOrders] = useState<Order[]>([]);
  const [selectedOrder, setSelectedOrder] = useState<Order | null>(null);
  const [error, setError] = useState<string | null>(null);

  const headers = () => ({
    "x-api-key": apiKey,
    "x-user-ip": userIp,
    Authorization: accessToken,
  });

  async function fetchActiveOrders() {
    setError(null);
    const res = await fetch(`${BASE}/api/v2/active-orders`, { headers: headers() });
    const json = await res.json();
    if (!res.ok) throw new Error(json.error?.message ?? `HTTP ${res.status}`);
    setActiveOrders(json.data);
    return json.data as Order[];
  }

  async function fetchOrders() {
    setError(null);
    const res = await fetch(`${BASE}/api/v2/orders`, { headers: headers() });
    const json = await res.json();
    if (!res.ok) throw new Error(json.error?.message ?? `HTTP ${res.status}`);
    setOrders(json.data);
    return json.data as Order[];
  }

  async function fetchOrderById(orderId: string) {
    setError(null);
    const res = await fetch(`${BASE}/api/v2/orders/${orderId}`, { headers: headers() });
    const json = await res.json();
    if (!res.ok) throw new Error(json.error?.message ?? `HTTP ${res.status}`);
    setSelectedOrder(json.data);
    return json.data as Order;
  }

  async function pollOrderById(orderId: string, intervalMs = 5000, timeoutMs = 300_000) {
    const deadline = Date.now() + timeoutMs;
    while (Date.now() < deadline) {
      const order = await fetchOrderById(orderId);
      if (FINAL_STATUSES.includes(order.status)) return order;
      await new Promise(r => setTimeout(r, intervalMs));
    }
    throw new Error("Timed out waiting for order to reach a final status");
  }

  async function cancelOrder(orderId: string, cancelReason: string) {
    setError(null);
    const qs = new URLSearchParams({ cancelReason });
    const res = await fetch(`${BASE}/api/v2/orders/${orderId}?${qs}`, {
      method: "DELETE",
      headers: headers(),
    });
    const json = await res.json();
    if (!res.ok) throw new Error(json.error?.message ?? `HTTP ${res.status}`);
    setSelectedOrder(json.data);
    return json.data as { orderId: string; status: string };
  }

  return {
    activeOrders,
    orders,
    selectedOrder,
    error,
    fetchActiveOrders,
    fetchOrders,
    fetchOrderById,
    pollOrderById,
    cancelOrder,
  };
}
```

## Order APIs

Returns any order that hasn't reached a final state — must be completed or cancelled before a new one can be placed.

Returns the user's full order history, including completed, cancelled, and failed orders.

Returns the details and current status of a single order.

Cancels an order that hasn't finished payment yet. Cannot be reversed.