Skip to content
LuxorrLuxorrLuxorr API

Getting started

This guide uses the sandbox. Calls work the same way in production.

Before you start

Section titled “Before you start”

You need a sandbox key, which starts with lxr_sbx_. Your Luxorr contact or your tenant’s Administrator creates it. See environments and keys.

The key is shown once. Store it in a secret store, never in source code or a browser.

Terminal window
export LUXORR_API=https://api.sandbox.luxorr.io/api/public/v1
export LUXORR_KEY=lxr_sbx_...

1. Check the key

Section titled “1. Check the key”

GET /me returns the key, its tenant and the environment.

Terminal window
curl -s "$LUXORR_API/me" -H "Authorization: Bearer $LUXORR_KEY"
{
  "tenant": {
    "id": "6f1c2a0e-1d2b-4c3d-8e9f-0a1b2c3d4e5f",
    "name": "Example Operator",
    "locales": ["en-US", "de-DE"],
    "currency": "EUR",
    "approvalRequired": false,
    "customFields": [
      {
        "id": "3d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a",
        "label": "VIP tier",
        "type": "DROPDOWN",
        "required": true,
        "options": ["Gold", "Platinum"]
      }
    ]
  },
  "key": {
    "id": 42,
    "name": "VIP shop",
    "prefix": "lxr_sbx_7Hk2",
    "scopes": ["CATALOG", "ORDERS"],
    "brandIds": null,
    "webhookUrl": "https://hooks.operator.example/luxorr"
  },
  "environment": "sandbox"
}
Field Meaning
key.brandIds null: the key reaches every brand of the tenant, including brands added later.
tenant.locales Locales a personal link accepts: en-US and the locales enabled for the tenant.
tenant.currency Currency of catalog estimates and of a custom order’s budget.
tenant.approvalRequired true: new orders and personal links start REQUESTED and wait for approval.
tenant.customFields The tenant’s own order fields, in display order. Answer them by id on an order or a personal link. type is TEXT, CHECKBOX or DROPDOWN. options lists dropdown values.
key.webhookUrl Where the key’s events are sent, or null. The signing secret is never returned.

/me always returns the current settings. A missing, malformed, unknown or revoked key answers 401 invalid_api_key.

2. List brands

Section titled “2. List brands”

Every order belongs to a brand. The brand is shown to the player on the packaging and the gift site.

Terminal window
curl -s "$LUXORR_API/brands" -H "Authorization: Bearer $LUXORR_KEY"
[
  {
    "id": "0a6f2e1c-3b5d-4e7f-8a9b-0c1d2e3f4a5b",
    "name": "Example Brand",
    "slug": "example-brand",
    "primaryColour": "#0B1F3A",
    "logoUrl": "https://api.sandbox.luxorr.io/api/public/v1/catalog/images/…"
  }
]

3. List gifts for a country

Section titled “3. List gifts for a country”

country is required. Availability and estimates depend on the delivery country.

Terminal window
curl -s "$LUXORR_API/catalog/products?country=DE&limit=2" \
  -H "Authorization: Bearer $LUXORR_KEY"
{
  "items": [
    {
      "id": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "name": "Cashmere scarf",
      "listed": true,
      "available": true,
      "priced": true,
      "estimate": { "amount": "190.00", "currency": "USD" },
      "estimateEur": { "amount": "180.00", "currency": "EUR" },
      "variations": [{ "dimension": "Colour", "values": ["Black", "Tan"] }],
      "updatedAt": "2026-10-05T09:12:44Z"
    }
  ],
  "nextCursor": "eyJuYW1lIjoi…"
}

The response is shortened. See catalog for every field.

4. Place an order

Section titled “4. Place an order”

Send a new UUID as Idempotency-Key for each order. Reuse it when you retry the same order.

Terminal window
curl -s "$LUXORR_API/orders" \
  -H "Authorization: Bearer $LUXORR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b0e2c1a-6f7d-4e3b-9a8c-1d2e3f4a5b6c" \
  -d '{
    "externalOrderId": "ORD-1001",
    "brandId": "0a6f2e1c-3b5d-4e7f-8a9b-0c1d2e3f4a5b",
    "items": [{ "productId": "9b8a7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d", "variations": { "Colour": "Black" } }],
    "client": { "name": "Wendy Player" },
    "recipient": {
      "name": "Wendy Player",
      "phone": "+4930123456",
      "address": { "street": "Unter den Linden 1", "city": "Berlin", "postalCode": "10117", "country": "DE" }
    }
  }'

The response is 201 with the order. Status is REQUESTED when the tenant requires approval, otherwise PROCESSING. version starts at 0 and increases with every change.

{
  "id": "4c1f9a52-8d0e-4f4b-9a3e-1f2d3c4b5a69",
  "reference": "G-2026004711",
  "version": 0,
  "externalOrderId": "ORD-1001",
  "source": "API",
  "status": "PROCESSING",
  "deliveryCountry": "DE",
  "shipments": [],
  "createdAt": "2026-10-05T09:12:44.512731Z",
  "updatedAt": "2026-10-05T09:12:44.512731Z"
}

The response is shortened. See an order for every field.

5. Find the order by your ID

Section titled “5. Find the order by your ID”
Terminal window
curl -s "$LUXORR_API/orders?externalOrderId=ORD-1001" \
  -H "Authorization: Bearer $LUXORR_KEY"

6. Test webhooks

Section titled “6. Test webhooks”

Set a webhook URL on the key, then send a signed test event:

Terminal window
curl -s -X POST "$LUXORR_API/webhooks:test" \
  -H "Authorization: Bearer $LUXORR_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
{ "responseStatus": 200, "error": null }

responseStatus is your receiver’s HTTP status. error explains any other outcome. See test your receiver and signature verification.

Next steps

Section titled “Next steps”