@devx-commerce/loyaltyx-api-client

Typed HTTP client for the LoyaltyX loyalty engine API. Wraps every admin, storefront, and auth endpoint with strongly typed request/response shapes derived from @devx-commerce/loyaltyx-core zod schemas.

Use this when you're building a custom dashboard, mobile app, or backend integration against a running LoyaltyX deployment.

Install

pnpm add @devx-commerce/loyaltyx-api-client @devx-commerce/loyaltyx-core
# or
npm install @devx-commerce/loyaltyx-api-client @devx-commerce/loyaltyx-core

Quick start

import { LoyaltyClient } from '@devx-commerce/loyaltyx-api-client';

const client = new LoyaltyClient('https://loyalty.your-brand.com/api/v1');

// Bearer auth (admin or storefront key)
client.setAuthToken('lx_admin_...');

// List customers
const { data, total } = await client.listCustomers({ page: 1, limit: 20 });

// Adjust points
await client.adjustPoints('customer-id', { points: 100, reason: 'Goodwill credit' });

// Create a tier
await client.createTier({
  name: 'Gold',
  pointMultiplier: 1.5,
  description: 'Mid-tier with 1.5× earn',
});

For browser apps using cookie-based admin auth, omit setAuthToken and call client.login({ email, password }) first — the cookie is set automatically by the API.

API coverage

| Module | Methods | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Auth | login, logout, getMe, changePassword | | Tiers | listTiers, getTier, createTier, updateTier, deleteTier | | Earning Rules | listEarningRules, createEarningRule, updateEarningRule, deleteEarningRule | | Spending Rules | listSpendingRules, createSpendingRule, updateSpendingRule, deleteSpendingRule | | Customers | listCustomers, getCustomer, overrideTier, adjustPoints | | Ledger | listLedger | | Analytics | getAnalytics | | Config | getConfig, updateConfig | | Channel Mappings | getChannelMappings, bulkSaveChannelMappings, deleteChannelMapping | | Users | listUsers, createUser, updateUser, deleteUser | | Connectors | getShopifyConfig, updateShopifyConfig, getNectorConfig, updateNectorConfig, getKwikengageConfig, updateKwikengageConfig | | Import / Export | createImport, startImport, cancelImport, listImports, getImport, getImportErrors, getImportTemplate, getPresignedUploadUrl, createExport, listExports, getExport |

Error handling

All methods throw ApiError on non-2xx responses:

import { ApiError } from '@devx-commerce/loyaltyx-api-client';

try {
  await client.getTier('does-not-exist');
} catch (err) {
  if (err instanceof ApiError) {
    console.error(err.status, err.code, err.message);
    // err.details contains the raw `details` field from the API error envelope
  }
  throw err;
}

The API responds with the envelope { error: { code, message, statusCode, details } }. ApiError exposes each field directly.

Sibling packages

| Package | Purpose | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------- | | @devx-commerce/loyaltyx-core | Shared types + zod schemas (peer of this package) | | @devx-commerce/loyaltyx-hooks | React Query wrapper for this client | | @devx-commerce/loyaltyx-ui-kit | Pre-built React admin components |

License

Apache-2.0 — see LICENSE.