GridlinePOS Solutions
Gridline

Orders API

Create, retrieve, and manage orders. Orders represent a completed or pending transaction including line items, payment status, and customer information.

List Orders

GET/v1/orders

Retrieve a paginated list of orders, sorted by creation date (newest first). Supports filtering by status, date range, and customer.

Response
{
  "data": [
    {
      "id": "ord_a1b2c3d4",
      "status": "paid",
      "total": 2499,
      "currency": "CAD",
      "items_count": 3,
      "customer_id": "cus_xyz789",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 142,
    "page": 1,
    "per_page": 20,
    "has_more": true
  }
}

Status Codes

  • 200Successfully retrieved orders
  • 401Invalid or missing API key
  • 403Insufficient permissions

Get Order

GET/v1/orders/:id

Retrieve a single order by its ID, including full line items, payment details, and customer information.

Response
{
  "id": "ord_a1b2c3d4",
  "status": "paid",
  "total": 2499,
  "subtotal": 2199,
  "tax": 300,
  "currency": "CAD",
  "items": [
    {
      "id": "li_001",
      "product_id": "prod_abc123",
      "name": "Flat White",
      "quantity": 2,
      "unit_price": 550,
      "total": 1100
    },
    {
      "id": "li_002",
      "product_id": "prod_def456",
      "name": "Avocado Toast",
      "quantity": 1,
      "unit_price": 1099,
      "total": 1099
    }
  ],
  "customer": {
    "id": "cus_xyz789",
    "name": "Jordan Smith",
    "email": "jordan@example.com"
  },
  "payment": {
    "method": "card",
    "card_last4": "4242",
    "paid_at": "2024-01-15T10:30:45Z"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:45Z"
}

Status Codes

  • 200Successfully retrieved order
  • 401Invalid or missing API key
  • 404Order not found

Create Order

POST/v1/orders

Create a new order with line items. The order will be created in 'pending' status until payment is captured.

Request Body
{
  "items": [
    { "product_id": "prod_abc123", "quantity": 2 },
    { "product_id": "prod_def456", "quantity": 1 }
  ],
  "customer_id": "cus_xyz789",
  "payment_method": "card",
  "notes": "Extra hot, no foam",
  "metadata": {
    "table_number": "12",
    "server": "staff_jane"
  }
}
Response
{
  "id": "ord_a1b2c3d4",
  "status": "pending",
  "total": 2499,
  "subtotal": 2199,
  "tax": 300,
  "currency": "CAD",
  "items": [...],
  "created_at": "2024-01-15T10:30:00Z"
}

Status Codes

  • 201Order successfully created
  • 400Invalid request body
  • 401Invalid or missing API key
  • 422Product not found or out of stock

Refund Order

POST/v1/orders/:id/refund

Issue a full or partial refund for a paid order. Partial refunds specify an amount in the smallest currency unit.

Request Body
{
  "amount": 1100,
  "reason": "customer_request",
  "items": [
    { "line_item_id": "li_001", "quantity": 2 }
  ]
}
Response
{
  "id": "ref_r1s2t3u4",
  "order_id": "ord_a1b2c3d4",
  "amount": 1100,
  "currency": "CAD",
  "status": "succeeded",
  "reason": "customer_request",
  "created_at": "2024-01-15T11:00:00Z"
}

Status Codes

  • 200Refund successfully processed
  • 400Invalid refund amount or already refunded
  • 401Invalid or missing API key
  • 404Order not found
  • 422Order is not in a refundable state

Full Example

create-order.tsTypeScript
import { Gridline } from '@gridline/sdk';

const client = new Gridline({ apiKey: process.env.GRIDLINE_API_KEY });

// Create an order
const order = await client.orders.create({
  items: [
    { product_id: 'prod_abc123', quantity: 2 },
    { product_id: 'prod_def456', quantity: 1 },
  ],
  customer_id: 'cus_xyz789',
  payment_method: 'card',
});

console.log('Order ' + order.id + ' created: $' + (order.total / 100));

// Refund the order later
const refund = await client.orders.refund(order.id, {
  amount: 1100,
  reason: 'customer_request',
});

console.log(`Refund ${refund.id}: ${refund.status}`);