Copy page

Examples

Place an Order

The Public Order API lets external integrations place orders at a Karma location in a single call — no tab pre-creation, no user lookup, no complex payload construction.

Endpoint

Code
POST /api/v1/public/orders/create

Authentication

All requests require an API key with the inventory.create permission:

Code
X-API-Key: karma_live_<your_key>

Contact Karma to obtain a key for your integration.

---

Quick Start

The simplest possible order

Code
curl -X POST https://api.karma.life/api/v1/public/orders/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: karma_live_<your_key>" \
  -d '{
    "location_id": 123,
    "items": [
      { "id": 456, "quantity_cents": 100 }
    ]
  }'

That's it. A new tab is opened, a kitchen dispatch is created, and an anonymous guest is generated automatically.

Response

Code
{
  "status": "success",
  "data": {
    "kitchenDispatchId": "e01dcd36-cdec-41e5-8708-1b57d943367d",
    "dailyOrderNumber": 7,
    "tabId": "59e4ce7d-b801-4323-af9d-ba0ca4bd757a",
    "tabMemberId": "1f910733-4456-4099-ab3b-7f6bece30657",
    "items": [
      {
        "kitchen_dispatch_item_id": "63ae3dc1-...",
        "item_id": 456,
        "quantity_cents": 100,
        "price_cents": 9900,
        "variants": []
      }
    ],
    "totalAmount": 9900,
    "linkedVouchers": [],
    "invalidVouchers": [],
    "orderFlow": "OPEN_TAB",
    "paymentRequired": false
  }
}

Use the tabId in the response to add more items to the same tab before payment is collected.

---

Common Scenarios

Identify the guest by email

If you know the guest's email, pass it in ordering_member. If the email matches an existing Karma account it is reused — no duplicate is created. New accounts are created automatically.

Code
curl -X POST https://api.karma.life/api/v1/public/orders/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: karma_live_<your_key>" \
  -d '{
    "location_id": 123,
    "ordering_member": {
      "email": "guest@example.com",
      "name": "Alex"
    },
    "items": [
      { "id": 456, "quantity_cents": 100 }
    ]
  }'

You can also identify by user_id (highest priority) or phone. If nothing is provided, a fresh anonymous guest is created for this order only.

Multiple items with variants and a voucher

A loyalty member ordering a customised burrito and a drink with a 10% welcome voucher, collected as takeaway:

Code
curl -X POST https://api.karma.life/api/v1/public/orders/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: karma_live_<your_key>" \
  -d '{
    "location_id": 123,
    "order_type": "TAKEAWAY",
    "ordering_member": {
      "email": "alex@example.com",
      "name": "Alex"
    },
    "items": [
      {
        "id": 456,
        "quantity_cents": 100,
        "variants": [
          { "id": 12 },
          { "id": 34 }
        ]
      },
      {
        "id": 789,
        "quantity_cents": 100
      }
    ],
    "vouchers": ["WELCOME10"]
  }'

Add items to an existing tab

Use the tabId from a previous response to keep adding orders to the same tab:

Code
curl -X POST https://api.karma.life/api/v1/public/orders/create \
  -H "Content-Type: application/json" \
  -H "X-API-Key: karma_live_<your_key>" \
  -d '{
    "location_id": 123,
    "order_destination": "TAB",
    "order_destination_id": "59e4ce7d-b801-4323-af9d-ba0ca4bd757a",
    "items": [
      { "id": 789, "quantity_cents": 100 }
    ]
  }'

Fractional quantities

quantity_cents scales by 100: 100 = 1 unit, 50 = half a unit, 200 = 2 units. Useful for weight-based or bulk items:

Code
{
  "items": [
    { "id": 456, "quantity_cents": 50 }
  ]
}

Price override

Override the catalogue price for this order only — useful for promotions or custom pricing:

Code
{
  "items": [
    { "id": 456, "quantity_cents": 100, "price_cents": 500 }
  ]
}

---

TypeScript / Node.js

Code
const response = await fetch('https://api.karma.life/api/v1/public/orders/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.KARMA_API_KEY!,
  },
  body: JSON.stringify({
    location_id: 123,
    ordering_member: { email: 'guest@example.com' },
    items: [
      { id: 456, quantity_cents: 100 },
      { id: 789, quantity_cents: 100, variants: [{ id: 12 }] },
    ],
  }),
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(`Order failed: ${error.code} — ${error.message}`)
}

const { data } = await response.json()
console.log('Order created:', data.kitchenDispatchId)
console.log('Tab:', data.tabId)
console.log('Total:', data.totalAmount, 'cents')

Python

Code
import httpx

response = httpx.post(
    'https://api.karma.life/api/v1/public/orders/create',
    headers={'X-API-Key': KARMA_API_KEY},
    json={
        'location_id': 123,
        'ordering_member': {'email': 'guest@example.com'},
        'items': [
            {'id': 456, 'quantity_cents': 100},
        ],
    },
)
response.raise_for_status()
data = response.json()['data']
print('Order created:', data['kitchenDispatchId'])
print('Tab:', data['tabId'])

---

Field Reference

Request body

Field	Type	Required	Description
location_id	number	✅	Location to place the order at
items	array	✅	Items to order (at least one)
ordering_member	object	—	Guest identity. Omit for an anonymous guest.
vouchers	string[]	—	Voucher codes to apply
order_destination	string	—	NONE (default, fresh tab), TAB, QR, KD
order_destination_id	string	—	UUID of the target when order_destination ≠ NONE
order_type	string	—	OTC (default), TAKEAWAY, TABLE

items[]

Field	Type	Required	Description
id	number	✅	Inventory item ID
quantity_cents	number	✅	Quantity × 100 (100 = 1, 50 = half)
variants	object[]	—	Variant selections (size, milk type, etc.)
price_cents	number	—	Price override. Defaults to catalogue price.
coursing_order	number	—	Course number. 0 = send immediately.

ordering_member

Field	Type	Description
user_id	number	Existing Karma user ID (highest priority)
email	string	Finds or creates a guest by email
phone	string	Finds or creates a guest by phone
name	string	Display name for new guests

---

Error codes

Status	Code	When
400	INVALID_INPUT	Missing required fields or bad types
401	MISSING_API_KEY	No X-API-Key header
403	INSUFFICIENT_PERMISSIONS	Key lacks inventory.create
403	SCOPE_VIOLATION	Key not scoped to this location
422	ITEM_NOT_FOUND	Item does not exist at this location
422	ITEM_UNAVAILABLE	Item is currently unavailable
429	RATE_LIMIT_EXCEEDED	Too many requests