billing · developers
API reference
Base address https://encrypted.com/api/v1. Create a key in your workspace under Settings → API & webhooks and send it as Authorization: Bearer bk_…. Money is in cents (USD); times are ISO 8601 UTC.
Conventions
- Keys are read-only or read-and-write, may be limited to products (other products answer 404) and to IP addresses, and may make 600 requests per minute (
X-RateLimit-Limit,-Remaining,-Reset; 429 withRetry-Afterabove that). - Errors are
application/problem+json:{"title", "status", "detail", "code"}, plus"errors": {field: message}on 422. - Lists are newest first:
?limit=1–100(25) and?starting_after=<next_cursor>; the answer is{"object":"list","data":[…],"has_more","next_cursor"}. - Retries: send
Idempotency-Key: <your id>with a POST; repeating it within 24 h returns the first answer (Idempotent-Replayed: true) instead of acting twice. - PATCH and DELETE also exist as POST (
POST …/{id},POST …/{id}/delete) for clients that cannot send them.
Webhooks
Each event is POSTed as JSON to your endpoints with Billing-Event, Billing-Event-Id, Billing-Delivery and Billing-Signature: t=<unix>,v1=<hex>, where v1 = HMAC-SHA256(secret, t + "." + raw body). Reject a signature older than 5 minutes; answer 2xx within 10 s. Failed deliveries are retried after 1 m, 5 m, 30 m, 2 h and 12 h. The same event may arrive twice: use its id to ignore repeats.
| Event | When |
|---|---|
payment.paid | A payment succeeded: a purchase, a subscription's first or renewal charge, or an offline payment recorded. |
payment.failed | A payment attempt failed. |
payment.refunded | A full or partial refund was confirmed. |
subscription.started | A subscription began (trialing or active). |
subscription.renewed | A subscription renewal charge succeeded. |
subscription.past_due | A renewal charge failed; the subscription is past due. |
subscription.canceled | A subscription ended. |
subscription.plan_changed | A requested plan change took effect. |
subscription.paused | A subscription was paused. |
subscription.resumed | A paused subscription resumed. |
dispute.opened | A dispute, inquiry or fraud warning was opened. |
dispute.closed | A dispute was won, lost or closed. |
payout.sent | A payout left the workspace: sent to the provider, or recorded as paid by hand. |
payout.paid | The provider confirmed a payout reached the payee's account. |
payout.failed | A payout failed or was returned; its amount is back on the payee's balance. |
// PHP: check a delivery
$t = …; $v1 = …; // parsed from the Billing-Signature header
$ok = abs(time() - (int) $t) <= 300
&& hash_equals(hash_hmac('sha256', $t . '.' . file_get_contents('php://input'), $secret), $v1);
Try it
Analytics
GET /analytics/summary Summary figures for a period
Rollups plus today live. Rates are percentages. Scope: read. Returns AnalyticsSummary.
Query: range (7d | 30d | 90d | 12m | mtd | ytd | custom), from (YYYY-MM-DD (custom)), to (YYYY-MM-DD (custom)), product (product id or slug)
Try it
Checkouts
POST /checkouts Create a hosted checkout
Send the buyer to "url". provider defaults to the first one bound to the product; plan may be left out when the product has one paid plan. amount (cents) only for buyer-chosen-amount products. Scope: write. Accepts an Idempotency-Key header. Returns CheckoutCreated.
Try it
GET /checkouts/{id} Get a checkout
Scope: read. Returns Checkout.
Try it
Customers
GET /customers List customers
Scope: read. Returns list of Customer.
Query: email (exact email), created_from (date/time), created_to (date/time), limit, starting_after (next_cursor of the previous page)
Try it
GET /customers/{id} Get a customer
Includes current access per product. Scope: read. Returns Customer.
Try it
Payouts
GET /ledger List ledger entries
Append-only. Signed amounts: credit +, reversal −, payout −, payout_return +, adjustment ±; a payee's balance is their sum. Scope: read. Returns list of LedgerEntry.
Query: payee (payee id), kind (credit | reversal | payout | payout_return | adjustment), environment (live (default) | test), limit, starting_after (next_cursor of the previous page)
Try it
GET /payees List payees
With live and test balances. Needs an owner's key for every product. Scope: read. Returns list of Payee.
Query: status (onboarding | active | disabled), limit, starting_after (next_cursor of the previous page)
Try it
POST /payees Add a payee
route: stripe | paypal | manual. send_invitation true e-mails the payee a sign-in for their earnings. Scope: write. Accepts an Idempotency-Key header. Returns Payee.
Try it
GET /payees/{id} Get a payee
Scope: read. Returns Payee.
Try it
PATCH /payees/{id} Update a payee
Only the fields sent change. status: active | disabled. A changed e-mail unlinks the portal sign-in. Scope: write. Returns Payee.
Try it
POST /payees/{id} Update a payee (POST alias of PATCH)
Scope: write. Accepts an Idempotency-Key header. Returns Payee.
Try it
GET /payout-batches List payout batches
Batches are built and sent in the workspace, not over the API. Scope: read. Returns list of PayoutBatch.
Query: environment (live (default) | test), limit, starting_after (next_cursor of the previous page)
Try it
POST /payout-batches Build a payout batch
Takes every payee's available balance at or above the minimum payout into a ready batch; nothing is sent. 409 batch_conflict while another batch of the environment waits. Scope: write. Accepts an Idempotency-Key header. Returns PayoutBatch.
Try it
GET /payout-batches/{id} Get a payout batch
Scope: read. Returns PayoutBatch.
Try it
POST /payout-batches/{id}/send Send a ready payout batch
Moves money. Refused (403 api_send_disabled) unless an owner allowed sending over the API in Payouts → Settings. Scope: write. Accepts an Idempotency-Key header. Returns PayoutBatch.
Try it
POST /payout-batches/{id}/withdraw Withdraw a ready payout batch
Every payout is canceled and its amount goes back on the payee's balance. Scope: write. Accepts an Idempotency-Key header. Returns PayoutBatch.
Try it
GET /payouts List payouts
Scope: read. Returns list of Payout.
Query: payee (payee id), batch (batch id), status (queued | sent | paid | failed | returned | manual_paid | canceled), environment (live (default) | test), limit, starting_after (next_cursor of the previous page)
Try it
GET /payouts/{id} Get a payout
Scope: read. Returns Payout.
Try it
GET /splits List split rules
Applied per product in priority order (lowest first); shares never exceed the payment. Scope: read. Returns list of SplitRule.
Query: product (product id or slug), payee (payee id), limit, starting_after (next_cursor of the previous page)
Try it
POST /splits Give a payee a share of a product
type percent with "percent" (0.01–100) or fixed with "amount" (cents per payment). One rule per payee and product. Applies to payments from now on. Scope: write. Accepts an Idempotency-Key header. Returns SplitRule.
Try it
GET /splits/{id} Get a split rule
Scope: read. Returns SplitRule.
Try it
PATCH /splits/{id} Change a split rule
Scope: write. Returns SplitRule.
Try it
POST /splits/{id} Change a split rule (POST alias of PATCH)
Scope: write. Accepts an Idempotency-Key header. Returns SplitRule.
Try it
DELETE /splits/{id} Remove a split rule
Earlier payments keep their shares. Scope: write. Returns Deleted.
Try it
POST /splits/{id}/delete Remove a split rule (POST alias of DELETE)
Scope: write. Accepts an Idempotency-Key header. Returns Deleted.
Try it
GET /tax-summary Yearly tax summary
What each payee was paid in a calendar year (Live), by route, with the tax form on file (last four digits only) and the 1099 threshold flag. Informational: it files nothing. Scope: read. Returns TaxSummary.
Query: year (four-digit year (default: this year))
Try it
Licensing
GET /licenses List licenses
Scope: read. Returns LicenseList.
Query: status (active | suspended | revoked), q (search (key end, email)), customer_id (customer id), product_id (product id)
Try it
GET /licenses/{id} Get a license
With instances and recent events. Scope: read. Returns License.
Try it
DELETE /licenses/{id}/instances/{instance} Remove an instance (frees its seat)
Scope: write. Returns License.
Try it
POST /licenses/{id}/instances/{instance}/{action} Block, unblock or remove an instance
Scope: write. Accepts an Idempotency-Key header. Returns License.
Try it
POST /licenses/{id}/{action} Suspend, resume, revoke, set seats, regenerate or set the end date
seats: {"seats": n}; expires: {"expires_at": "YYYY-MM-DD" | ""}; suspend: {"reason": "…"}. Scope: write. Accepts an Idempotency-Key header. Returns License.
Try it
GET /products/{id}/signing-keys Signing keys of a product
Scope: read. Returns SigningKeys.
Try it
POST /products/{id}/signing-keys Create a pending signing key
Scope: write. Accepts an Idempotency-Key header. Returns SigningKeys.
Try it
POST /products/{id}/signing-keys/{kid}/{action} Activate or retire a signing key
Scope: write. Accepts an Idempotency-Key header. Returns SigningKeys.
Try it
Key
GET /me The key in use
Name, scope and product limits of the API key, and its workspace. Scope: read. Returns Me.
Try it
Access
GET /paid Has a customer paid?
Give email, customer_id or code; product is required with email and customer_id. Scope: read. Returns Paid.
Query: email (customer email), customer_id (customer id), code (confirmation code), product (product id or slug)
Try it
Payment links
GET /payment-links List payment links
Scope: read. Returns list of PaymentLink.
Query: status (active | used | expired | revoked), product (product id or slug), limit, starting_after (next_cursor of the previous page)
Try it
POST /payment-links Create a payment link
max_uses defaults to 1 (null = unlimited). send_email true e-mails it to customer_email. Scope: write. Accepts an Idempotency-Key header. Returns PaymentLink.
Try it
GET /payment-links/{id} Get a payment link
Scope: read. Returns PaymentLink.
Try it
POST /payment-links/{id}/revoke Revoke a payment link
Scope: write. Accepts an Idempotency-Key header. Returns PaymentLink.
Try it
Products
GET /products List products
Scope: read. Returns list of Product.
Query: status (draft | active | archived), limit, starting_after (next_cursor of the previous page)
Try it
POST /products Create a product
Amounts in cents. Optional "plans": [{name, interval (one_time, monthly, quarterly, annual, free), amount, trial_days}]. Needs a key for every product. Scope: write. Accepts an Idempotency-Key header. Returns Product.
Try it
GET /products/{id} Get a product
id is the product id or its slug. Scope: read. Returns Product.
Try it
PATCH /products/{id} Update a product
Only the fields sent change. Scope: write. Returns Product.
Try it
POST /products/{id} Update a product (POST alias of PATCH)
Scope: write. Accepts an Idempotency-Key header. Returns Product.
Try it
POST /products/{id}/plans Add a plan
Scope: write. Accepts an Idempotency-Key header. Returns Plan.
Try it
PATCH /products/{id}/plans/{plan} Archive or reactivate a plan
Body: {"status": "archived" | "active"}. Scope: write. Returns Plan.
Try it
POST /products/{id}/plans/{plan} Archive or reactivate a plan (POST alias)
Scope: write. Accepts an Idempotency-Key header. Returns Plan.
Try it
Subscriptions
GET /subscriptions List subscriptions
Scope: read. Returns list of Subscription.
Query: status (subscription status), product (product id or slug), customer (customer id), limit, starting_after (next_cursor of the previous page)
Try it
GET /subscriptions/{id} Get a subscription
Scope: read. Returns Subscription.
Try it
POST /subscriptions/{id}/{action} Cancel, pause or resume
cancel takes {"at_period_end": true|false} (default true). The change is confirmed by the provider's webhook. Scope: write. Accepts an Idempotency-Key header. Returns Subscription.
Try it
Transactions
GET /transactions List transactions
Newest first. Scope: read. Returns list of Transaction.
Query: status (transaction status), kind (initial | renewal | manual), provider (stripe | paypal | square | authnet | manual), product (product id or slug), customer (customer id), subscription (subscription id), email (customer email), created_from (date/time (inclusive)), created_to (date/time (exclusive)), paid_from (date/time), paid_to (date/time), limit, starting_after (next_cursor of the previous page)
Try it
GET /transactions/by-code/{code} Find a transaction by confirmation code
ENC-XXXX-XXXX-XX; case, spaces and dashes are forgiven. Scope: read. Returns Transaction.
Try it
POST /transactions/manual Record an offline payment
Grants paid access (and a license on licensed products) and e-mails a receipt. Scope: write. Accepts an Idempotency-Key header. Returns Transaction.
Try it
GET /transactions/{id} Get a transaction
Includes its refunds. Scope: read. Returns Transaction.
Try it
POST /transactions/{id}/refund Refund a transaction
Full refund when amount is left out. 202 while the provider confirms; 200 for offline payments. Scope: write. Accepts an Idempotency-Key header. Returns RefundResult.
Try it
Webhooks
GET /webhooks List webhook endpoints
Needs a key for every product. Scope: read. Returns list of WebhookEndpoint.
Query: limit, starting_after (next_cursor of the previous page)
Try it
POST /webhooks Add a webhook endpoint
The answer carries "secret" once; keep it to check Billing-Signature. Scope: write. Accepts an Idempotency-Key header. Returns WebhookEndpointWithSecret.
Try it
GET /webhooks/{id} Get a webhook endpoint
Scope: read. Returns WebhookEndpoint.
Try it
PATCH /webhooks/{id} Update a webhook endpoint
Scope: write. Returns WebhookEndpoint.
Try it
POST /webhooks/{id} Update a webhook endpoint (POST alias)
Scope: write. Accepts an Idempotency-Key header. Returns WebhookEndpoint.
Try it
DELETE /webhooks/{id} Delete a webhook endpoint
Scope: write. Returns Deleted.
Try it
POST /webhooks/{id}/delete Delete a webhook endpoint (POST alias)
Scope: write. Accepts an Idempotency-Key header. Returns Deleted.
Try it
GET /webhooks/{id}/deliveries List deliveries of an endpoint
Scope: read. Returns list of WebhookDelivery.
Query: limit, starting_after (next_cursor of the previous page)
Try it
POST /webhooks/{id}/deliveries/{delivery}/redeliver Send a delivery's event again
Scope: write. Accepts an Idempotency-Key header. Returns WebhookDelivery.
Try it
POST /webhooks/{id}/rotate-secret Issue a new signing secret
The old secret stops working at once. Scope: write. Accepts an Idempotency-Key header. Returns WebhookEndpointWithSecret.
Try it
POST /webhooks/{id}/test Send a test event now
Sends a "ping" event synchronously and returns the delivery. Scope: write. Accepts an Idempotency-Key header. Returns WebhookDelivery.