REST API

API Documentation

Integrate any SaaS application with the Arionys central billing engine. Verify licenses, check subscriptions, gate features, and initiate dynamic checkouts — all via a single authenticated API.

Authentication

Generate an API Key inside the Admin Dashboard at /admin. Send it with every request using either header scheme:

authentication

x-api-key: sb_live_your_saas_product_key_here

# Alternatively, Bearer scheme:
Authorization: Bearer sb_live_your_saas_product_key_here

Integration Flow

STEP 01

Initiate Checkout Session

Dynamic API Call: Your backend calls /api/public/create-checkout with price, email, and tracking IDs.
Redirect to Billing: You receive a unique checkoutUrl and redirect your customer.
Complete Purchase: The user pays securely via the Paddle checkout overlay.

STEP 02

Return & Verify

Return to E-Commerce: Paddle redirects the customer back to your successUrl after payment.
Verify Securely: Call /api/public/validate-subscription with your API Key to confirm payment.
Fulfill Order: If hasActiveSubscription: true, approve the order in your database.

STEP 03

Failures & Revocation

Checkout Failures: Paddle handles failure messaging inside the modal — overlay stays open until success.
Recurring Failures: Failed renewals fire a webhook, marking the subscription past_due and blocking API access.
Grace & Dunning: An automated email links the customer to /portal to update payment.

POST/api/public/validate-subscription

Validates if a customer has an active subscription to the calling SaaS product using their email address.

Request Parameters

Field	Type	Required	Description
email	string	Yes	The customer email to look up on the billing engine.

Example cURL

bash

curl -X POST http://localhost:3000/api/public/validate-subscription \
  -H "x-api-key: sb_live_analytics_saas_key_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{"email": "customer@example.com"}'

Response JSON

response.json

200 OK

{
  "hasActiveSubscription": true,
  "subscription": {
    "paddleSubscriptionId": "sub_mock_subscription_123",
    "status": "active",
    "currentPeriodStartsAt": "2026-04-26T20:00:00.000Z",
    "currentPeriodEndsAt": "2026-06-26T20:00:00.000Z",
    "cancelAtPeriodEnd": false,
    "plan": {
      "name": "Hobby Plan",
      "slug": "hobby",
      "billingInterval": "monthly",
      "features": {
        "export_pdf": false,
        "api_calls": 1000
      }
    }
  }
}

POST/api/public/verify-license

Validates a customer's alphanumeric license key — perfect for desktop apps, integrations, or plugins.

Request Parameters

Field	Type	Required	Description
licenseKey	string	Yes	The license key to verify (e.g. LIC-XXXX-XXXX).

Example cURL

bash

curl -X POST http://localhost:3000/api/public/verify-license \
  -H "x-api-key: sb_live_analytics_saas_key_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{"licenseKey": "LIC-ANALYTICS-MOCK-KEY-789"}'

Response JSON

response.json

200 OK

{
  "isValid": true,
  "status": "active",
  "expiresAt": "2026-06-26T20:00:00.000Z",
  "featuresAllowed": {},
  "user": {
    "email": "customer@example.com"
  },
  "subscription": {
    "paddleSubscriptionId": "sub_mock_subscription_123",
    "status": "active",
    "currentPeriodEndsAt": "2026-06-26T20:00:00.000Z"
  }
}

POST/api/public/get-feature-access

Checks feature access and can dynamically increment metered usage (e.g. API call counters) on the central engine.

Request Parameters

Field	Type	Required	Description
licenseKey	string	Yes	The customer license key.
featureKey	string	No	Specific limit key to inspect (e.g. api_calls).
incrementUsage	number	No	Amount to increment the metered usage this billing cycle.

Example cURL

bash

curl -X POST http://localhost:3000/api/public/get-feature-access \
  -H "x-api-key: sb_live_analytics_saas_key_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "licenseKey": "LIC-ANALYTICS-MOCK-KEY-789",
    "featureKey": "api_calls",
    "incrementUsage": 1
  }'

Response JSON

response.json

200 OK

{
  "isAllowed": true,
  "featureValue": 1000,
  "type": "metered",
  "limit": 1000,
  "currentUsage": 1,
  "remaining": 999,
  "resetAt": "2026-06-26T20:00:00.000Z"
}

POST/api/public/create-checkout

Initiates a dynamic checkout session — your app dictates price, currency, and interval. A hosted checkout link is returned.

Request Parameters

Field	Type	Required	Description
email	string	Yes	The customer email.
amount	number	Yes	Price amount (e.g. 49.99).
currency	string	No	Currency code (USD, EUR…). Defaults to USD.
title	string	Yes	Product title shown to the customer.
interval	string	No	Set to 'month' or 'year' for recurring. Omit for one-time.
source	string	No	Origin SaaS domain (e.g. my-saas.com).
reference	string	No	Your internal Order ID for tracking.
successUrl	string	Yes	URL to redirect the user after a successful purchase.

Example cURL

bash

curl -X POST http://localhost:3000/api/public/create-checkout \
  -H "x-api-key: sb_live_analytics_saas_key_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "amount": 49.99,
    "currency": "USD",
    "title": "Pro License (1-Time)",
    "description": "Unlimited access for life.",
    "source": "my-cool-saas.com",
    "reference": "order_001",
    "successUrl": "https://my-cool-saas.com/thank-you"
  }'

Response JSON

response.json

200 OK

{
  "success": true,
  "transactionId": "txn_01abc...",
  "checkoutUrl": "http://localhost:3000/checkout/txn_01abc..."
}