Official SDKs

npm install @gridline/sdk

# or with yarn
yarn add @gridline/sdk

# or with pnpm
pnpm add @gridline/sdk

import { Gridline } from '@gridline/sdk';

const client = new Gridline({
  apiKey: process.env.GRIDLINE_API_KEY,
  // Optional: override base URL for sandbox
  baseUrl: 'https://sandbox-api.gridlinepos.com/v1',
  // Optional: set request timeout (default: 30s)
  timeout: 10000,
  // Optional: set max retries (default: 2)
  maxRetries: 3,
});

// List orders with pagination
const orders = await client.orders.list({
  limit: 20,
  status: 'paid',
  created_after: '2024-01-01T00:00:00Z',
});

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

// Get customer loyalty balance
const balance = await client.loyalty.getBalance('cus_xyz789');
console.log(`Points: ${balance.points_balance}`);
console.log(`Tier: ${balance.tier.name}`);

// Earn points on an order
const earn = await client.loyalty.earn({
  customer_id: 'cus_xyz789',
  order_id: order.id,
  amount: order.total,
  currency: 'CAD',
});

// List products
const products = await client.products.list({ category: 'beverages' });

// Webhook signature verification
import { verifyWebhookSignature } from '@gridline/sdk/webhooks';

const isValid = verifyWebhookSignature(
  requestBody,
  headers['x-gridline-signature'],
  headers['x-gridline-timestamp'],
  process.env.WEBHOOK_SECRET
);

import { Gridline, GridlineError, RateLimitError } from '@gridline/sdk';

try {
  const order = await client.orders.get('ord_nonexistent');
} catch (error) {
  if (error instanceof RateLimitError) {
    // Retry after the specified delay
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof GridlineError) {
    console.error(`API Error [${error.status}]: ${error.message}`);
    console.error(`Error code: ${error.code}`);
  }
}

pip install gridline

# or with poetry
poetry add gridline

import gridline
import os

# Synchronous client
client = gridline.Client(
    api_key=os.environ["GRIDLINE_API_KEY"],
    # Optional: override base URL for sandbox
    base_url="https://sandbox-api.gridlinepos.com/v1",
    # Optional: set request timeout (default: 30s)
    timeout=10.0,
)

# Async client
async_client = gridline.AsyncClient(
    api_key=os.environ["GRIDLINE_API_KEY"],
)

# List orders
orders = client.orders.list(limit=20, status="paid")
for order in orders.data:
    print(f"Order {order.id}: ${order.total / 100:.2f}")

# Create an order
order = client.orders.create(
    items=[
        {"product_id": "prod_abc123", "quantity": 2},
    ],
    customer_id="cus_xyz789",
    payment_method="card",
)

# Get loyalty balance
balance = client.loyalty.get_balance("cus_xyz789")
print(f"Points: {balance.points_balance}")
print(f"Tier: {balance.tier.name}")

# Earn points
earn = client.loyalty.earn(
    customer_id="cus_xyz789",
    order_id=order.id,
    amount=order.total,
    currency="CAD",
)

# Async usage
import asyncio

async def main():
    orders = await async_client.orders.list(limit=10)
    print(f"Found {orders.pagination.total} orders")

asyncio.run(main())

from gridline.errors import GridlineError, RateLimitError, NotFoundError

try:
    order = client.orders.get("ord_nonexistent")
except NotFoundError:
    print("Order not found")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except GridlineError as e:
    print(f"API Error [{e.status}]: {e.message}")
    print(f"Error code: {e.code}")