OpenAPI 3.1 spec, SDKs in four languages, a sandbox with pre-loaded data, and a GraphQL playground. The API is the product — you own the front end.
import { LoyaltyOSClient } from '@loyaltyos/sdk'; const client = new LoyaltyOSClient({ tenantSlug: 'acme-retail', apiKey: process.env.LOYALTYOS_API_KEY, }); // Ingest an order — ledger writes are atomic const result = await client.orders.ingest({ orderId: 'ord_8k2p', customerId: 'cust_a1b2', orderTotal: 149.99, currencyCode: 'GBP', lineItems: [ { sku: 'TRAINER-42', quantity: 1, unitPrice: 149.99 } ], }); console.log(result.pointsEarned); // 450 console.log(result.newBalance); // 3300 console.log(result.tier); // "Gold"
Register at app.loyaltyos.io. A sandbox tenant is provisioned in under 60 seconds — isolated from production, with sample customer data and a pre-loaded rule set.
Navigate to Settings → API Keys in the admin portal. Keys are shown once at creation and stored as Argon2id hashes — keep yours somewhere sensible.
export LOYALTYOS_API_KEY="los_sandbox_sk_..."
# TypeScript / JavaScript npm install @loyaltyos/sdk # Python pip install loyaltyos # Java (Maven) # <dependency>io.loyaltyos/sdk</dependency> # C# (.NET) dotnet add package LoyaltyOS.SDK
The SDK handles OAuth 2.0 token exchange, request signing, and retry logic. Your first order event will hit the rules engine, write to the ledger, and return the points outcome synchronously.
All four SDKs are generated directly from the OpenAPI 3.1 specification using a custom generator pipeline — so they are always consistent with the live API, without manual maintenance overhead. They come with that reassurance baked in.
Full type safety, async/await, tree-shaking friendly. Works in Node.js and browser environments.
npm install @loyaltyos/sdk →Pydantic models for all request/response types. Supports sync and async usage via httpx.
pip install loyaltyos →Maven/Gradle artifact. Jackson-based serialisation. Compatible with Spring Boot and Micronaut.
View on Maven Central →NuGet package. System.Text.Json serialisation. Native async/await. Targets .NET 8+.
dotnet add package LoyaltyOS.SDK →The REST API covers order ingestion and management operations. The GraphQL API is the reporting layer. Both are authenticated with OAuth 2.0 client credentials or mTLS (Growth+).
/api/v1/ordersIngest a single order. Returns points earned, new balance, tier, and ledger transaction reference.
/api/v1/orders/batchIngest up to 500 orders in a single request. Idempotent by orderId. Returns per-order outcomes.
/api/v1/orders/{orderId}/simulateDry-run rule evaluation against an order without writing to the ledger. Returns full evaluation trace.
/api/v1/orders/{orderId}Cancel an order. Proportionally voids all associated ledger entries. Idempotent.
/api/v1/customersEnrol a customer into the loyalty programme. Returns customer ID and initial tier assignment.
/api/v1/customers/{customerId}/balanceReturn current points balance, credit balance, tier, and next tier threshold. Snapshot-consistent.
/api/v1/customers/{customerId}/ledgerPaginated ledger history for a customer. Cursor-based pagination. Supports entry type filter.
/api/v1/customers/{customerId}GDPR right-to-erasure. Destroys the customer's DEK; all PII becomes permanently irrecoverable.
/api/v1/rule-setsList all active and draft rule sets for the tenant. Includes version history and complexity score.
/api/v1/rule-setsCreate or update a rule set. DSL source is validated, parsed, and compiled to IR at save time.
/api/v1/rule-sets/validateValidate DSL source without saving. Returns parse errors, complexity score, and a dry-run preview.
/api/v1/webhooksRegister a webhook endpoint. Supports up to 10 endpoints (3 on Starter). Returns HMAC signing secret.
/api/v1/webhooks/{id}/deliveriesPaginated delivery log for a webhook endpoint. PII-scrubbed payloads. 30-day retention.
/api/v1/webhooks/{id}/rotate-secretRotate the HMAC signing secret with a configurable grace period. Old secret remains valid during grace.
Full SLA, immutable ledger writes, live webhook delivery, and all warehouse CDC feeds active. All changes to rule sets in production are versioned and attributed.
https://api.loyaltyos.io/v1
https://graphql.loyaltyos.io/v1
Identical to production — same API, same DSL engine, same ledger model. GraphQL introspection is enabled. Simulate any scenario without touching live data.
https://sandbox-api.loyaltyos.io/v1
https://sandbox-graphql.loyaltyos.io/v1
No credit card. No time limit on the sandbox. Full API access, pre-loaded data, and the DSL simulator all available from the moment you register.