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.

1. Get your API key

   Your Kalixo account manager issues a sandbox and a production key. Keep them 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.

2. Find a product in your catalog

   List your catalog and pick a productId. You can filter by country, brand, category and more.

   cURL

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

   Send the productId, the price you expect to pay (for validation), the quantity, and a unique externalOrderCode. The order is accepted immediately with a processing status and an estimatedReadyAt timestamp.

   cURL

   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": 3299,
       "orderProducts": [
         { "productId": 2, "price": 3299, "quantity": 1 }
       ]
     }'
   

   Response

   {
     "orderId": 59400,
     "externalOrderCode": "O-12345",
     "status": "processing",
     "estimatedReadyAt": "2026-06-02T11:05:00Z"
   }
   
4. 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": 59400,
     "status": "completed",
     "externalOrderCode": "O-12345",
     "products": [
       { "productId": 2, "price": 3299, "quantity": 1, "pin": [{ "PIN": "ABCDE-FGHIJ-KLMNO-PQRST-UVWXY" }] }
     ]
   }
   

   While the order is still working you’ll get {"status": "processing", "message": "Order is still processing"}. Read more in Order lifecycle.

Next steps

Order lifecycle

Understand processing, completed, partially_completed, and failed.

Filtering

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

Postman collection

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