List Orders

Returns a paginated list of orders, ordered by creation date (most recent first). Supports filtering by status, customer, payment status, and date range.

Authentication

Authorization: Bearer glm_test_YOUR_API_KEY

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results per page (default: 10, max: 100)
`starting_after`	string	Cursor for pagination (order ID)
`status`	enum	Filter by status: `pending`, `processing`, `completed`, `failed`, `cancelled`
`payment_status`	enum	Filter by payment status: `pending`, `authorized`, `captured`, `failed`, `refunded`, `disputed`
`customer_email`	string	Filter by customer email
`created_after`	timestamp	Filter orders created after this date
`created_before`	timestamp	Filter orders created before this date
`test_mode`	boolean	Filter by test mode (true/false)

Request

GET /v2/orders?limit=10&status=completed

Response

{
  "data": [
    {
      "id": "ord_abc123",
      "order_number": "ORD-2025-001234",
      "status": "completed",
      "payment_status": "captured",
      "customer": {
        "email": "[email protected]",
        "first_name": "Jane",
        "last_name": "Doe"
      },
      "amounts": {
        "total_cents": 4235,
        "hsa_fsa_amount_cents": 2995,
        "regular_amount_cents": 0
      },
      "payment": {
        "payment_method": "hsa_fsa_card",
        "last4": "1111"
      },
      "created_at": "2025-10-18T15:00:00Z",
      "completed_at": "2025-10-18T15:30:00Z"
    },
    {
      "id": "ord_def456",
      "order_number": "ORD-2025-001235",
      "status": "completed",
      "payment_status": "captured",
      "customer": {
        "email": "[email protected]",
        "first_name": "John",
        "last_name": "Smith"
      },
      "amounts": {
        "total_cents": 9900,
        "hsa_fsa_amount_cents": 9900,
        "regular_amount_cents": 0
      },
      "payment": {
        "payment_method": "hsa_fsa_card",
        "last4": "2222"
      },
      "created_at": "2025-10-17T10:00:00Z",
      "completed_at": "2025-10-17T10:15:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "ord_def456"
}

Response Fields

Field	Type	Description
`data`	array	Array of order objects
`has_more`	boolean	Whether more results are available
`next_cursor`	string	Cursor for next page (use as `starting_after`)

Examples

List All Orders

curl https://api.withgale.com/v2/orders \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY"

Filter by Status

curl "https://api.withgale.com/v2/orders?status=completed&limit=50" \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY"

Filter by Payment Status

curl "https://api.withgale.com/v2/orders?payment_status=captured" \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY"

Filter by Customer

curl "https://api.withgale.com/v2/[email protected]" \
  -H "Authorization: Bearer glm_test_YOUR_API_KEY"

Pagination

const getAllCompletedOrders = async () => {
  let allOrders = [];
  let hasMore = true;
  let cursor = null;

  while (hasMore) {
    const params = new URLSearchParams({
      status: 'completed',
      limit: '100',
      ...(cursor && { starting_after: cursor })
    });

    const response = await fetch(
      `https://api.withgale.com/v2/orders?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.GALE_API_KEY}`
        }
      }
    );

    const data = await response.json();
    allOrders = allOrders.concat(data.data);
    hasMore = data.has_more;
    cursor = data.next_cursor;
  }

  return allOrders;
};

Date Range Filter

// Get orders from last 30 days
const getRecentOrders = async () => {
  const thirtyDaysAgo = new Date();
  thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);

  const params = new URLSearchParams({
    created_after: thirtyDaysAgo.toISOString(),
    status: 'completed',
    limit: '100'
  });

  const response = await fetch(
    `https://api.withgale.com/v2/orders?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.GALE_API_KEY}`
      }
    }
  );

  return await response.json();
};

Test Mode Filter

# Only production orders
curl "https://api.withgale.com/v2/orders?test_mode=false" \
  -H "Authorization: Bearer glm_live_YOUR_API_KEY"

Use Cases

Revenue Dashboard

// Calculate total revenue from completed orders
const calculateRevenue = async (startDate, endDate) => {
  const params = new URLSearchParams({
    status: 'completed',
    payment_status: 'captured',
    created_after: startDate.toISOString(),
    created_before: endDate.toISOString(),
    test_mode: 'false',
    limit: '100'
  });

  let totalRevenue = 0;
  let hsaRevenue = 0;
  let orderCount = 0;
  let hasMore = true;
  let cursor = null;

  while (hasMore) {
    if (cursor) params.set('starting_after', cursor);

    const response = await fetch(
      `https://api.withgale.com/v2/orders?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.GALE_API_KEY}`
        }
      }
    );

    const { data, has_more, next_cursor } = await response.json();

    for (const order of data) {
      totalRevenue += order.amounts.total_cents;
      hsaRevenue += order.amounts.hsa_fsa_amount_cents;
      orderCount++;
    }

    hasMore = has_more;
    cursor = next_cursor;
  }

  return {
    totalRevenue: totalRevenue / 100,
    hsaRevenue: hsaRevenue / 100,
    regularRevenue: (totalRevenue - hsaRevenue) / 100,
    orderCount,
    averageOrderValue: totalRevenue / orderCount / 100
  };
};

Fulfillment Queue

// Get orders ready for fulfillment
const getFulfillmentQueue = async () => {
  const params = new URLSearchParams({
    status: 'completed',
    payment_status: 'captured',
    limit: '100'
  });

  const response = await fetch(
    `https://api.withgale.com/v2/orders?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.GALE_API_KEY}`
      }
    }
  );

  const { data } = await response.json();

  // Filter unfulfilled orders (using metadata)
  const unfulfilled = data.filter(order =>
    !order.metadata?.fulfillment_status ||
    order.metadata.fulfillment_status === 'pending'
  );

  return unfulfilled.map(order => ({
    orderId: order.id,
    orderNumber: order.order_number,
    customerName: `${order.customer.first_name} ${order.customer.last_name}`,
    items: order.line_items,
    shippingAddress: order.customer.shipping_address,
    createdAt: order.created_at
  }));
};

Customer Order History

// Show all orders for a customer
const getCustomerOrders = async (email) => {
  const params = new URLSearchParams({
    customer_email: email,
    limit: '50'
  });

  const response = await fetch(
    `https://api.withgale.com/v2/orders?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.GALE_API_KEY}`
      }
    }
  );

  const { data } = await response.json();

  return data.map(order => ({
    orderNumber: order.order_number,
    status: order.status,
    total: order.amounts.total_cents / 100,
    items: order.line_items.map(item => item.name),
    orderedAt: order.created_at,
    completedAt: order.completed_at
  }));
};

Failed Orders Report

// Monitor failed orders
const getFailedOrders = async () => {
  const yesterday = new Date();
  yesterday.setDate(yesterday.getDate() - 1);

  const params = new URLSearchParams({
    status: 'failed',
    created_after: yesterday.toISOString(),
    limit: '100'
  });

  const response = await fetch(
    `https://api.withgale.com/v2/orders?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.GALE_API_KEY}`
      }
    }
  );

  const { data } = await response.json();

  return data.map(order => ({
    orderNumber: order.order_number,
    customerEmail: order.customer.email,
    amount: order.amounts.total_cents / 100,
    failureReason: order.status_history
      .find(h => h.status === 'failed')?.reason,
    attemptedAt: order.created_at
  }));
};

HSA/FSA Analytics

// Analyze HSA/FSA usage patterns
const analyzeHSAUsage = async (startDate, endDate) => {
  const params = new URLSearchParams({
    status: 'completed',
    created_after: startDate.toISOString(),
    created_before: endDate.toISOString(),
    limit: '100'
  });

  let totalOrders = 0;
  let hsaOnlyOrders = 0;
  let splitPaymentOrders = 0;
  let totalHSAAmount = 0;
  let totalRegularAmount = 0;

  let hasMore = true;
  let cursor = null;

  while (hasMore) {
    if (cursor) params.set('starting_after', cursor);

    const response = await fetch(
      `https://api.withgale.com/v2/orders?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.GALE_API_KEY}`
        }
      }
    );

    const { data, has_more, next_cursor } = await response.json();

    for (const order of data) {
      totalOrders++;
      totalHSAAmount += order.amounts.hsa_fsa_amount_cents;
      totalRegularAmount += order.amounts.regular_amount_cents;

      if (order.amounts.regular_amount_cents === 0) {
        hsaOnlyOrders++;
      } else if (order.amounts.hsa_fsa_amount_cents > 0) {
        splitPaymentOrders++;
      }
    }

    hasMore = has_more;
    cursor = next_cursor;
  }

  return {
    totalOrders,
    hsaOnlyOrders,
    hsaOnlyPercentage: (hsaOnlyOrders / totalOrders) * 100,
    splitPaymentOrders,
    splitPaymentPercentage: (splitPaymentOrders / totalOrders) * 100,
    totalHSAAmount: totalHSAAmount / 100,
    totalRegularAmount: totalRegularAmount / 100,
    averageHSAPerOrder: totalHSAAmount / totalOrders / 100
  };
};

Export Orders

// Export orders to CSV
const exportOrdersToCSV = async (startDate, endDate) => {
  const params = new URLSearchParams({
    status: 'completed',
    created_after: startDate.toISOString(),
    created_before: endDate.toISOString(),
    limit: '100'
  });

  const orders = await getAllOrders(params);

  const csv = [
    'Order Number,Customer Email,Total,HSA Amount,Status,Date',
    ...orders.map(order =>
      [
        order.order_number,
        order.customer.email,
        order.amounts.total_cents / 100,
        order.amounts.hsa_fsa_amount_cents / 100,
        order.status,
        order.created_at
      ].join(',')
    )
  ].join('\n');

  return csv;
};

Errors

Status Code	Error Code	Description
400	`invalid_request`	Invalid query parameters
401	`unauthorized`	Invalid or missing API key
429	`rate_limit_exceeded`	Too many requests

Example error:

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid status value",
    "param": "status"
  }
}

Best Practices

Use Pagination

Always paginate large result sets using limit and cursors

Filter Efficiently

Use filters to reduce data transfer and improve performance

Cache Results

Cache historical order data to minimize API calls

Use Webhooks

Don’t poll for new orders. Use webhooks instead.

Get Order - GET /v2/orders/
Create Refund - POST /v2/refunds

Getting Started

Integration Guides

Core Objects

Checkout

Payment Links

Orders

Products

Subscriptions

Webhooks & Errors

List Orders

List Orders

Authentication

Query Parameters

Request

Response

Response Fields

Examples

List All Orders

Filter by Status

Filter by Payment Status

Filter by Customer

Date Range Filter

Test Mode Filter

Use Cases

Revenue Dashboard

Fulfillment Queue

Customer Order History

Failed Orders Report

HSA/FSA Analytics

Export Orders

Errors

Best Practices

Use Pagination

Filter Efficiently

Cache Results

Use Webhooks

Getting Started

Integration Guides

Core Objects

Checkout

Payment Links

Orders

Products

Subscriptions

Webhooks & Errors

​List Orders

​Authentication

​Query Parameters

​Request

​Response

​Response Fields

​Examples

​List All Orders

​Filter by Status

​Filter by Payment Status

​Filter by Customer

​Pagination

​Date Range Filter

​Test Mode Filter

​Use Cases

​Revenue Dashboard

​Fulfillment Queue

​Customer Order History

​Failed Orders Report

​HSA/FSA Analytics

​Export Orders

​Errors

​Best Practices

Use Pagination

Filter Efficiently

Cache Results

Use Webhooks

​Related Endpoints

​Related Resources

List Orders

Authentication

Query Parameters

Request

Response

Response Fields

Examples

List All Orders

Filter by Status

Filter by Payment Status

Filter by Customer

Pagination

Date Range Filter

Test Mode Filter

Use Cases

Revenue Dashboard

Fulfillment Queue

Customer Order History

Failed Orders Report

HSA/FSA Analytics

Export Orders

Errors

Best Practices

Related Endpoints

Related Resources