Paylio Documentation

Integrate subscriptions in under a minute. Server-side SDKs for Python, Node.js, Go, and Rust, plus drop-in embed components for your frontend.

sk_*Server-Side

Secret key for backend API calls. Never expose in client code.

pk_*Client-Side

Publishable key for embed components. Safe for frontend code.

Authentication

Pass your secret key on every request using the x-paylio-key header (primary) or as a Bearer token.

Primary

x-paylio-key: sk_live_xxxx

Alternative

Authorization: Bearer sk_live_xxxx

Important: Never expose your secret key (sk_*) in client-side code. Use the publishable key (pk_*) for embed components.

Server-SidePython · Node.js · Go · Rust

Installation

Install the Paylio SDK for your language.

pip install paylio

Quick Start

Check a user's subscription status with one call.

import paylio

client = paylio.PaylioClient("sk_live_xxx")

# Retrieve current subscription
sub = client.subscription.retrieve("user_123")
print(sub.status)       # "active"
print(sub.plan.name)    # "Pro Plan"
print(sub.plan.amount)  # 999

List Billing History

history = client.subscription.list("user_123", page=1, page_size=10)
for item in history.items:
    print(item.plan_name, item.status)

if history.has_more:
    next_page = client.subscription.list("user_123", page=2)

Cancel a Subscription

# Cancel at end of billing period (safe default)
result = client.subscription.cancel("subscription_uuid")
print(result.success)  # True

# Cancel immediately
result = client.subscription.cancel("subscription_uuid", cancel_now=True)

Error Handling

import paylio

client = paylio.PaylioClient("sk_live_xxx")

try:
    sub = client.subscription.retrieve("user_123")
except paylio.AuthenticationError:
    print("Invalid API key")
except paylio.NotFoundError:
    print("Subscription not found")
except paylio.RateLimitError:
    print("Rate limited, try again later")
except paylio.InvalidRequestError as e:
    print(f"Bad request: {e.message}")
except paylio.APIError as e:
    print(f"API error: {e.message} (status {e.http_status})")
except paylio.APIConnectionError:
    print("Network error")

GET/flying/v1/subscription/:user_id

Get Subscription

Returns the current subscription for a user. Always returns an object — if the user has no subscription, status will be "none".

Request

Parameter		Description
`user_id` path · string	required	The user ID to look up.
`x-paylio-key` header · string	required	Your secret API key.

Request example

curl "https://api.paylio.pro/flying/v1/subscription/user_123" \
  -H "x-paylio-key: sk_live_xxxx"

Response

{
  "id": "4f5bc67d-...",
  "object": "subscription",
  "status": "active",
  "user_id": "user_123",
  "plan": {
    "slug": "pro-monthly",
    "name": "Pro",
    "interval": "month",
    "amount": 999,
    "currency": "usd"
  },
  "subscription_period": {
    "start": "2026-02-01T00:00:00Z",
    "end": "2026-03-01T00:00:00Z"
  },
  "cancel_at_period_end": false,
  "canceled_at": null,
  "provider": "stripe",
  "created_at": "2026-01-15T10:30:00Z"
}

Status	Meaning
`active`	User has an active paid subscription.
`trialing`	User is on a free trial.
`past_due`	Payment failed; subscription still accessible.
`canceled`	Subscription was canceled.
`none`	No subscription found for this user.

GET/api/billing-history

Billing History

Returns a paginated list of billing events for the authenticated project. Maximum page_size is 100.

Query parameters

Parameter		Description
`page` integer		Page number, starting at 1. Defaults to 1.
`page_size` integer		Items per page. Maximum 100. Defaults to 20.
`status` string		Filter by billing status (e.g. paid, failed).
`subscription_id` string		Filter to a specific subscription.

Request example

curl "https://api.paylio.pro/api/billing-history?page=1&page_size=20" \
  -H "x-paylio-key: sk_live_xxxx"

Response

{
  "items": [
    {
      "id": "bh_abc123",
      "subscription_id": "4f5bc67d-...",
      "plan_name": "Pro",
      "amount": 999,
      "currency": "usd",
      "payment_gateway": "stripe",
      "status": "paid",
      "is_trial": false,
      "created_at": "2026-02-01T00:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 20
}

Field	Type	Description
id	string	Unique billing event ID.
subscription_id	string	Parent subscription ID.
plan_name	string	Human-readable plan name.
amount	integer	Amount in smallest currency unit (e.g. cents).
currency	string	ISO 4217 currency code (e.g. usd).
payment_gateway	string	Gateway used: stripe or razorpay.
status	string	paid · failed · refunded.
is_trial	boolean	True if this was a trial period event.
created_at	string (ISO 8601)	Timestamp of the billing event.

POST/flying/v1/subscription/:subscription_id/cancel

Cancel Subscription

Cancels a subscription. By default, remains active until the end of the current billing period. Pass cancel_at_period_end: false to cancel immediately.

Body

Parameter		Description
`cancel_at_period_end` boolean		true → cancel at period end (default). false → cancel immediately.

Request example

curl -X POST \
  "https://api.paylio.pro/flying/v1/subscription/sub_123/cancel" \
  -H "x-paylio-key: sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{"cancel_at_period_end": true}'

Response

{
  "id": "4f5bc67d-1d9a-4b43-8f9c-a2f2f9659f4a",
  "object": "subscription_cancel",
  "success": true,
  "cancel_at_period_end": true
}

Client-SideDrop-in UI components for your frontend

Embed Plans Grid

Add a fully-styled pricing grid to your app. Choose from a zero-dependency script tag, an npm module, or a React component.

Drop a single <script> tag into your page — no build step, no npm install.

<div id="paylio-plans"></div>
<script
  src="https://api.paylio.pro/embed/v1/js"
  data-paylio-publishable-key="pk_live_xxxx"
  data-user-id="user_123">
</script>

Use your publishable key (pk_live_* or pk_test_*) — never your secret key.

Attributes

Configuration attributes for the embed script tag. Only 4 attributes — keep it simple.

Attribute	Required	Default	Description
data-paylio-publishable-key	required	—	Your publishable key (pk_live_* or pk_test_*).
data-user-id	required	—	Your user's ID. Required for showing plan state and checkout.
data-container		paylio-plans	ID of the div to render the plans grid into.
data-country		auto-detected	ISO country code (e.g. US, IN) for pricing display.

PostMessage Events

The embed fires window.postMessage events you can listen to for advanced integration.

Event	When it fires
paylio:ready	Script has initialised and is ready.
paylio:grid-loaded	Plans grid has rendered successfully.
paylio:resize	The embed container resized.
paylio:checkout	User clicked a plan and checkout opened.

window.addEventListener("message", (event) => {
  // paylio:ready | paylio:grid-loaded | paylio:resize | paylio:checkout
  if (event.data?.type?.startsWith("paylio:")) {
    console.log(event.data.type, event.data.detail);
  }
});

llms.txt

Machine-readable documentation for AI code assistants. Contains all SDK install commands, quick start examples, and API reference in plain text.

https://paylio.pro/llms.txt

Auto-generated · Updated with every SDK release

Home Pricing Dashboard