Developer Hub

Ship a loyalty programme
in an afternoon.

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.

Quickstart Guide → API Reference
quickstart.ts 
import { VariaOSClient } from '@loyaltyos/sdk';

const client = new VariaOSClient({
  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"
Quickstart

From zero to first transaction
in four steps.

1

Provision a Sandbox Tenant

Register at app.loyaltyos.io. Self-serve sandbox provisioning is rolling out now — join the waitlist for an invite. Before you build, read the honest beta status & known limitations. Sandbox tenants are isolated from production, with sample customer data and a pre-loaded rule set.

2

Generate an API Key

Navigate to Settings → API Keys in the admin portal. Keys are shown once at creation and stored as Argon2id hashes — keep yours somewhere sensible.

terminal 
export LOYALTYOS_API_KEY="los_sandbox_sk_..."
3

Install the SDK

terminal 
# TypeScript / JavaScript
npm install @loyaltyos/sdk

# Python
pip install loyaltyos

# Java (Maven)
# <dependency>io.loyaltyos/sdk</dependency>

# C# (.NET)
dotnet add package LoyaltyOS.SDK
4

Ingest Your First Order

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.

SDKs

Generated from the OpenAPI spec.
Always in sync.

All four SDKs are generated directly from the OpenAPI 3.1 specification, so they stay consistent with the API without manual maintenance. They are rolling out to private-beta participants first.

🟦

TypeScript / JavaScript

Full type safety, async/await, tree-shaking friendly. Works in Node.js and browser environments.

Coming soon — join the beta →
🐍

Python

Pydantic models for all request/response types. Supports sync and async usage via httpx.

Coming soon — join the beta →
☕

Java

Maven/Gradle artifact. Jackson-based serialisation. Compatible with Spring Boot and Micronaut.

Coming soon — join the beta →
🔷

C# / .NET

NuGet package. System.Text.Json serialisation. Native async/await. Targets .NET 8+.

Coming soon — join the beta →
API Reference

OpenAPI 3.1. REST + GraphQL.
Two ways to query, one truth.

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 API keys.

Order Ingestion

POST
/api/v1/orders

Ingest a single order. Returns points earned, new balance, tier, and ledger transaction reference.

POST
/api/v1/orders/batch

Ingest up to 500 orders in a single request. Idempotent by orderId. Returns per-order outcomes.

POST
/api/v1/orders/{orderId}/simulate

Dry-run rule evaluation against an order without writing to the ledger. Returns full evaluation trace.

DELETE
/api/v1/orders/{orderId}

Cancel an order. Proportionally voids all associated ledger entries. Idempotent.

Customers

POST
/api/v1/customers

Enrol a customer into the loyalty programme. Returns customer ID and initial tier assignment.

GET
/api/v1/customers/{customerId}/balance

Return current points balance, credit balance, tier, and next tier threshold. Snapshot-consistent.

GET
/api/v1/customers/{customerId}/ledger

Paginated ledger history for a customer. Cursor-based pagination. Supports entry type filter.

DELETE
/api/v1/customers/{customerId}

GDPR right-to-erasure. Destroys the customer's DEK; all PII becomes permanently irrecoverable.

Rules & DSL

GET
/api/v1/rule-sets

List all active and draft rule sets for the tenant. Includes version history and complexity score.

POST
/api/v1/rule-sets

Create or update a rule set. DSL source is validated, parsed, and compiled to IR at save time.

POST
/api/v1/rule-sets/validate

Validate DSL source without saving. Returns parse errors, complexity score, and a dry-run preview.

Webhooks

POST
/api/v1/webhooks

Register a webhook endpoint. Supports up to 10 endpoints (3 on Starter). Returns HMAC signing secret.

GET
/api/v1/webhooks/{id}/deliveries

Paginated delivery log for a webhook endpoint. PII-scrubbed payloads. 30-day retention.

PATCH
/api/v1/webhooks/{id}/rotate-secret

Rotate the HMAC signing secret with a configurable grace period. Old secret remains valid during grace.

API access in the private beta → GraphQL Playground (beta) →
Environments

Production and sandbox.
Completely isolated.

Production

Production Environment

Full SLA, immutable ledger writes, live webhook delivery, and the historical order-data import API. All changes to rule sets in production are versioned and attributed.

https://api.loyaltyos.io/v1 https://graphql.loyaltyos.io/v1
Sandbox

Sandbox Environment

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

Get early access.
Bring your curiosity.

Private beta is opening to design partners now. Early access includes full API access, a sandbox with pre-loaded data, and the DSL simulator — no credit card.

Join the Private Beta → Talk to an Engineer