Axlet Python SDK

Server-side Python client for the Axlet subscription, entitlement, credits, and purchase APIs. Python 3.10 or later; no runtime dependencies.

pip install axlet

import os
from axlet import AxletClient, AxletApiError

client = AxletClient(
    api_key=os.environ["AXLET_API_KEY"],
    base_url=os.environ.get("AXLET_API_URL", "http://127.0.0.1:4310"),
)
print(client.get_plans())

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. The free public beta supports customer-owned Toss merchant projects, including live payments with the merchant's own contract and keys. Axlet platform fees are not charged during the beta; live customer payment flows have not yet been verified. Keys access a single project, are displayed once, and stop working when revoked. If you lose a key, revoke it and issue a replacement.

You can also connect your own Axlet API server. axlet.app is a website, not the API origin. This package does not include the API server. Keep project operator keys on your server. 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].

Usage

Methods use Python snake_case names. Input and response dictionaries preserve API camelCase fields:

customer = client.create_customer(
    {"name": "Example", "email": "user@example.com", "externalId": "user-123"},
    idempotency_key="create-user-123",
)
access = client.get_access(customer["id"], "report")
# For each paid operation, confirm successful consumption before doing the work.
usage = client.consume_usage(
    customer["id"],
    {"feature": "report", "operationId": "report-job-123"},
    idempotency_key="consume-job-123",
)

Every mutation requires an idempotency key. Keys and operation IDs must contain 8–100 ASCII letters, digits, underscores, or hyphens. Reuse them only for retries of the same operation; generate new IDs for new work. The customer must have the required subscription or credits before consuming paid usage.

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

customer = client.get_customer_by_external_id("user-123")
usage = client.get_usage(customer["id"], "report-job-123")
print(usage["status"])

Both methods use GET without a body, idempotency key, or automatic retries. Customer lookup matches the original external ID exactly, including spaces and case, and does not create or update a customer. Missing records, records belonging to another customer, and records outside the current project return HTTP 404 as AxletApiError. A 404 does not prove that an in-flight request has finally failed and is not a reason to generate a new operation ID.

Usage status is consumed or canceled. consumed confirms the Axlet usage record, not completion of your external AI or application work. Track that work in your own service and execute it at most once per operation ID. These reads do not consume or restore credits.

register_billing(customer_id, key) starts card registration. For a Toss project, pass the returned clientKey, customerKey, and state to the payment UI, then call complete_billing({"state": state, "customerKey": customer_key, "authKey": auth_key}, key) from your server when the customer returns. Authenticate that customer in your service before calling the completion API. Project Toss payments currently support cards only; method="TRANSFER" remains available on the local test server when the merchant supports it.

Supported methods: get_plans, set_plan, create_customer, get_customer_by_external_id, register_billing, complete_billing, subscribe, cancel, refund, retry, get_entitlement, get_credits, get_access, get_usage, consume_usage, cancel_usage, create_purchase, get_purchase, confirm_purchase, sync_purchase, refund_purchase, advance_demo, and run_jobs.

HTTP failures and invalid successful responses raise AxletApiError with status and body. Invalid keys raise ValueError. Network errors use the standard library's exceptions. Socket operations use a 75-second timeout, configurable with timeout=. Requests are synchronous, redirects are rejected, and no automatic retries are performed. Payment behavior depends on the API server configuration; installing this client does not enable production payments.

get_access(customer_id, feature) may include evidence: the evaluated plan and feature, subscription entitlement, and that subscription's latest payment recorded by Axlet. Use the existing allowed and reason fields for access decisions. For example, a paid subscription can still return insufficient_credits. observedAt is the ledger query time, not the time of a live PG status check. This read does not charge, refund, restore credits, or confirm that your own application granted access. Older servers may omit evidence.

License

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