Axlet SDK

Server-side JavaScript and TypeScript client for Axlet's subscription, entitlement, and credit APIs. Requires Node.js 24 or later. Includes TypeScript declarations and has no runtime dependencies.

npm install axlet

import { AxletClient, AxletApiError } from 'axlet';

const axlet = new AxletClient({
  apiKey: process.env.AXLET_API_KEY,
  baseUrl: process.env.AXLET_API_URL || 'http://127.0.0.1:4310',
});

const plans = await axlet.getPlans();
console.log(plans.current);

Create a project in the Axlet console, copy its API origin, and issue a project key. Set AXLET_API_URL and AXLET_API_KEY on your server. Axlet usage is free during the public beta. Simulated and Toss test projects do not charge real money; live projects require the merchant's own approved Toss account, live keys, and live-payment consent. Each key accesses one project's customers, subscriptions, and credits; revoked keys stop working immediately. Keys are displayed once. If you lose a key, revoke it and issue a replacement.

You can also use an Axlet API server you operate. The website at axlet.app is not the API origin. This package does not include the API server. API keys have project operator privileges: keep them on your server and never ship them in browser code. See the getting started guide for the first simulated subscription.

API origins must use HTTPS and contain no credentials, query, or fragment. HTTP is allowed only for local development on localhost, 127.0.0.1, or [::1].

Subscriptions and usage

The client supports plan and customer management, subscriptions, entitlements, credit balances, usage consumption and cancellation, and purchase operations. Call getAccess(customerId, feature) to inspect access; confirm a successful consumeUsage before running a paid operation.

const usage = await axlet.consumeUsage(
  customerId,
  { feature: 'report', operationId: jobId },
  { idempotencyKey: requestId },
);

jobId and requestId must each contain 8–100 ASCII letters, digits, underscores, or hyphens. Keep the same operation ID and idempotency key when retrying the same operation. Generate new values for new operations. Mutation methods require an idempotency key, either as a string or { idempotencyKey }.

After canceling usage, use a new operation ID and a new idempotency key to execute the work again. Reusing a canceled operation returns HTTP 409, including retries with the original request key. Your service must also execute the actual work at most once for each operation ID.

Read an existing customer or usage operation

The following methods are available starting in SDK 0.1.2. The hosted Axlet API supports these lookup routes; self-hosted servers must also be updated.

const customer = await axlet.getCustomerByExternalId(user.id);
// { id, externalId }
const usageRecord = await axlet.getUsage(customer.id, jobId);
// { operationId, customerId, feature, credits, status, createdAt }

The Python SDK provides get_customer_by_external_id(user_id) and get_usage(customer_id, job_id). Both methods use GET without a body, idempotency key, or automatic retries. Customer lookup matches the original external ID exactly, including spaces and case; it never creates or updates a customer. The server accepts the same nonblank external IDs as customer creation, up to 120 UTF-16 code units.

Usage lookup returns consumed or canceled, including operations outside the recent usage list. It does not debit or restore credits, and it does not return a balance; use getCredits for the current balance. HTTP 404 throws AxletApiError and means no matching record was visible to this request. A concurrent operation may still be processing, so a 404 is not proof of final failure and must not trigger a new operation ID automatically. Likewise, consumed confirms an Axlet debit record, not completion of your application's AI job or other external work.

For hosted Toss projects, registerBilling(customerId, key) starts card registration and returns state, customerKey, and clientKey for the browser's requestBillingAuth() call. Bind the returned state to the authenticated customer in your server before opening the payment window. On return, validate that binding and call completeBilling({ state, customerKey, authKey }, key) from your server. Card registration does not charge the customer; call subscribe(customerId, key) only after the customer's subscription consent. Use separate idempotency keys for registration, completion, and subscription, and preserve each key when retrying its request.

Hosted projects currently support cards only. { method: 'TRANSFER' } is available only on the local test server when the merchant supports it. See the integration guide for the server/browser flow. Axlet usage fees and your customers' payments through your own merchant account are separate.

Requests time out after 75 seconds. API failures throw AxletApiError, with status and body properties. Invalid keys throw TypeError. Automatic retries are not performed. Payment behavior depends on your API server's configuration; installing this client does not enable production payments.

License

All rights reserved. This release does not grant an open-source license.