Orders Guide

Learn how to work with orders via the Pixlpay API.

List Orders

Retrieve all orders with optional filtering and pagination.

curl "https://yourstore.pixlpay.net/api/external/v1/orders" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters

Parameter	Type	Description
status	string	Filter by status: pending, processing, completed, cancelled
payment_status	string	Filter by payment: pending, paid, failed, refunded
customer_email	string	Filter by customer email
order_number	string	Filter by order number
start_date	date	Orders created after this date
end_date	date	Orders created before this date
sort_by	string	Sort field: created_at, total, order_number
sort_order	string	asc or desc
page	integer	Page number
per_page	integer	Items per page (max 100)

Example with Filters

curl "https://yourstore.pixlpay.net/api/external/v1/orders?payment_status=paid&start_date=2025-01-01&sort_by=created_at&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "data": [
    {
      "id": 123,
      "order_number": "ORD-2025-00123",
      "status": "completed",
      "payment_status": "paid",
      "total": "29.99",
      "currency": "USD",
      "customer_email": "player@example.com",
      "customer_name": "PlayerOne",
      "items": [
        {
          "id": 1,
          "product_id": 5,
          "product_name": "VIP Rank",
          "quantity": 1,
          "price": "29.99",
          "total": "29.99"
        }
      ],
      "created_at": "2025-01-20T14:30:00Z",
      "updated_at": "2025-01-20T14:35:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 15,
    "total": 142
  }
}

Get Single Order

Retrieve detailed information about a specific order.

curl "https://yourstore.pixlpay.net/api/external/v1/orders/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "data": {
    "id": 123,
    "order_number": "ORD-2025-00123",
    "status": "completed",
    "payment_status": "paid",
    "total": "29.99",
    "subtotal": "29.99",
    "tax": "0.00",
    "currency": "USD",
    "customer_email": "player@example.com",
    "customer_name": "PlayerOne",
    "customer_id": 45,
    "items": [
      {
        "id": 1,
        "product_id": 5,
        "product_name": "VIP Rank",
        "quantity": 1,
        "price": "29.99",
        "total": "29.99",
        "product": {
          "id": 5,
          "name": "VIP Rank",
          "type": "digital"
        }
      }
    ],
    "billing_address": {
      "name": "John Doe",
      "country": "US",
      "city": "New York"
    },
    "notes": null,
    "metadata": {
      "minecraft_username": "PlayerOne",
      "discord_id": "123456789"
    },
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-20T14:35:00Z",
    "completed_at": "2025-01-20T14:35:00Z"
  }
}

Fulfill an Order

Mark an order as fulfilled/completed.

curl -X POST "https://yourstore.pixlpay.net/api/external/v1/orders/123/fulfill" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "success": true,
  "data": {
    "id": 123,
    "order_number": "ORD-2025-00123",
    "status": "completed",
    "completed_at": "2025-01-20T15:00:00Z"
  },
  "message": "Order marked as fulfilled"
}

Error: Already Completed

{
  "success": false,
  "error": "ORDER_ALREADY_COMPLETED",
  "message": "Order is already completed"
}

Order Statuses

Status	Description
pending	Order created, awaiting payment
processing	Payment received, processing
completed	Order fulfilled
cancelled	Order cancelled

Payment Statuses

Status	Description
pending	Awaiting payment
paid	Payment received
failed	Payment failed
refunded	Payment refunded

Common Use Cases

Automated Order Fulfillment

Process orders when payment is received using webhooks:

// Webhook handler for order.paid
app.post('/webhooks/pixlpay', async (req, res) => {
  const event = req.body;

  if (event.event_type === 'order.paid') {
    const order = event.data;

    // Deliver items to player
    for (const item of order.items) {
      await deliverToPlayer(order.metadata.minecraft_username, item);
    }

    // Mark order as fulfilled
    await pixlpay.fulfillOrder(order.id);
  }

  res.status(200).json({ status: 'received' });
});

Export Orders to CSV

async function exportOrders(startDate, endDate) {
  const orders = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `${BASE_URL}/orders?start_date=${startDate}&end_date=${endDate}&page=${page}&per_page=100`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const data = await response.json();

    orders.push(...data.data);
    hasMore = page < data.meta.last_page;
    page++;
  }

  // Convert to CSV
  const csv = orders.map(o =>
    `${o.order_number},${o.customer_email},${o.total},${o.status}`
  ).join('\n');

  return csv;
}

Get Unfulfilled Orders

async function getUnfulfilledOrders() {
  const response = await fetch(
    `${BASE_URL}/orders?payment_status=paid&status=processing`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  return response.json();
}

Required Scopes

Endpoint	Required Scope
GET /orders	orders:read
GET /orders/:id	orders:read
POST /orders/:id/fulfill	orders:write