Skip to main content
The official billing.io SDK for Python 3.9+.

PyPI

billingio

GitHub

billingio/billingio-python

​
Installation

pip install billingio

​
Quick Start

from billingio import BillingIO

billing = BillingIO(api_key="sk_live_...")

checkout = billing.checkouts.create(
    amount_usd=49.99,
    chain="tron",
    token="USDT",
    metadata={"order_id": "ord_12345"},
)

print(checkout.checkout_id)
print(checkout.deposit_address)

​
Create a Checkout

checkout = billing.checkouts.create(
    amount_usd=100.00,
    chain="arbitrum",
    token="USDC",
    metadata={
        "customer_email": "alice@example.com",
        "plan": "pro",
    },
)

​
List with Pagination

Fetch a single page: 
page = billing.checkouts.list(limit=10)
for checkout in page.data:
    print(checkout.checkout_id, checkout.status)
Auto-paginate through all results: 
from billingio import auto_paginate

for checkout in auto_paginate(billing.checkouts.list):
    print(checkout.checkout_id, checkout.status)

​
Get Checkout Status

status = billing.checkouts.get_status("chk_abc123")

print(status.status)                  # "confirming"
print(status.confirmations)            # 8
print(status.required_confirmations)   # 19

​
Webhook Signature Verification

​
Flask

from flask import Flask, request
from billingio import verify_webhook_signature

app = Flask(__name__)


@app.route("/webhooks/billing", methods=["POST"])
def handle_webhook():
    is_valid = verify_webhook_signature(
        raw_body=request.get_data(as_text=True),
        signature_header=request.headers["X-Billing-Signature"],
        secret="whsec_...",
    )

    if not is_valid:
        return "Invalid signature", 401

    event = request.get_json()
    print(event["type"])  # "checkout.completed"
    return "OK", 200

​
Django

from django.http import HttpResponse, HttpResponseForbidden
from billingio import verify_webhook_signature


def billing_webhook(request):
    is_valid = verify_webhook_signature(
        raw_body=request.body.decode("utf-8"),
        signature_header=request.headers["X-Billing-Signature"],
        secret="whsec_...",
    )

    if not is_valid:
        return HttpResponseForbidden("Invalid signature")

    # process event...
    return HttpResponse("OK")

​
Error Handling

from billingio import BillingIO, BillingIOError

try:
    billing.checkouts.create(amount_usd=-1, chain="tron", token="USDT")
except BillingIOError as e:
    print(e.status)   # 422
    print(e.code)     # "validation_error"
    print(e.message)  # "amount_usd must be positive"
Error TypeStatusDescription
authentication_error401Invalid or missing API key
not_found404Resource doesn’t exist
validation_error422Invalid request parameters
rate_limit_error429Too many requests

​
Customers

customer = billing.customers.create(
    email="alice@example.com",
    name="Alice Johnson",
    metadata={"plan": "pro"},
)

customer = billing.customers.get("cus_abc123")

updated = billing.customers.update("cus_abc123", name="Alice Smith")

for customer in auto_paginate(billing.customers.list):
    print(customer.email)

​
Payment Methods

pm = billing.payment_methods.create(
    chain="tron",
    token="USDT",
    display_name="Primary USDT",
)

billing.payment_methods.set_default("pm_abc123")

page = billing.payment_methods.list(limit=10)
for pm in page.data:
    print(pm.display_name, pm.chain, pm.token)

link = billing.payment_links.create(
    amount_usd=99.99,
    chain="arbitrum",
    token="USDC",
    description="Annual subscription",
)
print(link.url)

​
Subscriptions

# Create a plan
plan = billing.subscription_plans.create(
    name="Pro Monthly",
    amount_usd=29.99,
    interval="monthly",
    token="USDT",
    chain="tron",
)

# Subscribe a customer
sub = billing.subscriptions.create(
    customer_id="cus_abc123",
    plan_id=plan.id,
    payment_method_id="pm_abc123",
)

# Cancel
billing.subscriptions.update("sub_abc123", status="canceled")

# List renewals
for renewal in auto_paginate(billing.subscription_renewals.list):
    print(renewal.status, renewal.amount_usd)

​
Entitlements

ent = billing.entitlements.create(
    plan_id="plan_abc123",
    feature_key="api_calls",
    value_type="numeric",
    value_numeric=10000,
)

check = billing.entitlements.check(
    customer_id="cus_abc123",
    feature_key="api_calls",
)
print(check.has_access, check.value)

​
Payouts

payout = billing.payout_intents.create(
    recipient_address="TXyz...",
    chain="tron",
    token="USDT",
    amount=500.00,
    currency="USD",
)

# Submit tx hash after executing externally
billing.payout_intents.execute("po_abc123", tx_hash="0xabc...")

# List settlements
for settlement in auto_paginate(billing.settlements.list):
    print(settlement.tx_hash, settlement.confirmed_at)

​
Revenue

for event in auto_paginate(billing.revenue_events.list):
    print(event.event_type, event.amount, event.currency)

adj = billing.adjustments.create(
    type="credit",
    amount_usd=10.00,
    description="Loyalty discount",
    customer_id="cus_abc123",
)