> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kalixo.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> From zero to your first delivered order in four steps.
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](/concepts/sandbox) with a `kal_test_…` 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](/authentication).
Using **Postman**? Import the
Kalixo API v2 collection and an environment
([Sandbox](/kalixo-api-v2.postman_environment.sandbox.json) or
[Production](/kalixo-api-v2.postman_environment.production.json)), then set your `apiKey`
variable. For local dev against split services, use the
[Local environment](/kalixo-api-v2.postman_environment.local.json).
Once your key is issued and your IP is whitelisted, confirm the API is reachable:
```bash cURL theme={"dark"}
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.
List your catalog and pick a `productId` (the `id` field). Each product also has a
`productCode` (a stable 14-digit catalog identifier) and per-locale `sku`. Filter by
country, brand, category, and more.
```bash cURL theme={"dark"}
curl -X GET "https://api.kalixo.io/v2/catalog/products?country=GB&take=5" \
-H "x-api-key: $KALIXO_API_KEY"
```
```javascript Node theme={"dark"}
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]);
```
```python Python theme={"dark"}
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])
```
Send each line's **unit** `price`, `quantity`, and `productId`, 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.
```bash cURL theme={"dark"}
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": [
{ "productId": 2, "price": 10000, "quantity": 1 }
]
}'
```
```bash cURL - two lines (total 15000) theme={"dark"}
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": [
{ "productId": 2, "price": 10000, "quantity": 1 },
{ "productId": 5, "price": 5000, "quantity": 1 }
]
}'
```
```javascript Node theme={"dark"}
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: [{ productId: 2, price: 10000, quantity: 1 }],
}),
});
console.log(await res.json());
```
```json Response theme={"dark"}
{
"orderId": 59400,
"externalOrderCode": "O-12345",
"status": "processing",
"estimatedReadyAt": "2026-06-02T11:05:00Z",
"wallet": { "balances": { "GBP": 196.01 }, "lowBalance": false }
}
```
After `estimatedReadyAt`, fetch the order. Codes are returned once the status is `completed`.
```bash cURL theme={"dark"}
curl -X GET "https://api.kalixo.io/v2/orders/O-12345" \
-H "x-api-key: $KALIXO_API_KEY"
```
```json Response (completed) theme={"dark"}
{
"orderId": 59400,
"status": "completed",
"externalOrderCode": "O-12345",
"products": [
{
"productId": 2,
"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](/concepts/order-lifecycle#polling-example).
Or use the [Node reference client](/examples/kalixo-node).
## Next steps
Understand `processing`, `completed`, `partially_completed`, and `failed`.
Narrow your catalog by country, language, brand, category, and tag.
Reference SDK with `estimatedReadyAt`-aware polling.
Postman collection
Download the v2 collection and import the Sandbox or Production environment.