Quickstart

This guide walks you through authenticating, finding a product, placing an order, and retrieving your codes.

Pre-release: Base URLs in this guide are placeholders during the pre-release period. Your account manager will confirm the final endpoints when your keys are issued. Start in Sandbox with a kal_test_… key.

Get your API key

Your Kalixo account manager issues a sandbox and a production key, and whitelists your egress IP addresses. Keep keys secret and send them in the x-api-key header on every request. See Authentication.

Using Postman? Import the Kalixo API v2 collection and an environment (Sandbox or Production), then set your apiKey variable. For local dev against split services, use the Local environment.

Verify connectivity (optional)

Once your key is issued and your IP is whitelisted, confirm the API is reachable:

cURL

curl -X GET "https://api.kalixo.io/v2/ping" \
  -H "x-api-key: $KALIXO_API_KEY"

A 200 response with { "status": "ok", "timestamp": "..." } means the API is up.

Find a product in your catalog

List your catalog and pick a productCode - a stable 14-digit catalog identifier that is identical in sandbox and production. Each product also has per-locale sku values. Filter by country, brand, category, and more.

curl -X GET "https://api.kalixo.io/v2/catalog/products?country=GB&take=5" \
  -H "x-api-key: $KALIXO_API_KEY"

const res = await fetch(
  "https://api.kalixo.io/v2/catalog/products?country=GB&take=5",
  { headers: { "x-api-key": process.env.KALIXO_API_KEY } }
);
const { products } = await res.json();
console.log(products[0]);

import os, requests

res = requests.get(
    "https://api.kalixo.io/v2/catalog/products",
    params={"country": "GB", "take": 5},
    headers={"x-api-key": os.environ["KALIXO_API_KEY"]},
)
print(res.json()["products"][0])

Place an order

Send each line’s unit price, quantity, and productCode, plus a unique externalOrderCode. The optional top-level price is the order total - if you send it, it must equal the sum of (line price × quantity).The order is accepted immediately with processing, estimatedReadyAt, and a wallet snapshot.

curl -X POST "https://api.kalixo.io/v2/orders" \
  -H "x-api-key: $KALIXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderCode": "O-12345",
    "currency": "GBP",
    "price": 10000,
    "orderProducts": [
      { "productCode": "10020000213575", "price": 10000, "quantity": 1 }
    ]
  }'

curl -X POST "https://api.kalixo.io/v2/orders" \
  -H "x-api-key: $KALIXO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderCode": "O-67890",
    "currency": "GBP",
    "price": 15000,
    "orderProducts": [
      { "productCode": "10020000213575", "price": 10000, "quantity": 1 },
      { "productCode": "10001000000421", "price": 5000, "quantity": 1 }
    ]
  }'

const res = await fetch("https://api.kalixo.io/v2/orders", {
  method: "POST",
  headers: {
    "x-api-key": process.env.KALIXO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalOrderCode: "O-12345",
    currency: "GBP",
    price: 10000,
    orderProducts: [{ productCode: "10020000213575", price: 10000, quantity: 1 }],
  }),
});
console.log(await res.json());

Response

{
  "orderId": "b9f6f9a2-4d0a-4f5c-9a1e-7c2d8f3b6e10",
  "externalOrderCode": "O-12345",
  "status": "processing",
  "estimatedReadyAt": "2026-06-02T11:05:00Z",
  "wallet": { "balances": { "GBP": 196.01 }, "lowBalance": false }
}

Poll until completed

After estimatedReadyAt, fetch the order. Codes are returned once the status is completed.

cURL

curl -X GET "https://api.kalixo.io/v2/orders/O-12345" \
  -H "x-api-key: $KALIXO_API_KEY"

Response (completed)

{
  "orderId": "b9f6f9a2-4d0a-4f5c-9a1e-7c2d8f3b6e10",
  "status": "completed",
  "externalOrderCode": "O-12345",
  "products": [
    {
      "productCode": "10020000213575",
      "price": 10000,
      "quantity": 1,
      "codes": [{ "code": "ABCDE-FGHIJ-KLMNO-PQRST-UVWXY" }]
    }
  ],
  "wallet": { "balances": { "GBP": 96.01 }, "lowBalance": false }
}

While the order is still working you’ll get {"status": "processing", "message": "Order is still processing"}. Wait until estimatedReadyAt before polling - see the polling example. Or use the Node reference client.

Next steps

Order lifecycle

Understand processing, completed, partially_completed, and failed.

Filtering

Narrow your catalog by country, language, brand, category, and tag.

Node client

Reference SDK with estimatedReadyAt-aware polling.

Postman collection

Download the v2 collection and import the Sandbox or Production environment.

Get started

Core concepts

Migrate

Next steps

Order lifecycle

Filtering

Node client

Postman collection

Postman collection

​Next steps

Order lifecycle

Filtering

Node client

​Postman collection

Postman collection

Next steps

Postman collection