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 with Retry-After above 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.

EventWhen
payment.paidA payment succeeded: a purchase, a subscription's first or renewal charge, or an offline payment recorded.
payment.failedA payment attempt failed.
payment.refundedA full or partial refund was confirmed.
subscription.startedA subscription began (trialing or active).
subscription.renewedA subscription renewal charge succeeded.
subscription.past_dueA renewal charge failed; the subscription is past due.
subscription.canceledA subscription ended.
subscription.plan_changedA requested plan change took effect.
subscription.pausedA subscription was paused.
subscription.resumedA paused subscription resumed.
dispute.openedA dispute, inquiry or fraud warning was opened.
dispute.closedA dispute was won, lost or closed.
payout.sentA payout left the workspace: sent to the provider, or recorded as paid by hand.
payout.paidThe provider confirmed a payout reached the payee's account.
payout.failedA 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

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.

Try it