Billing, coupons, and growth

The public API can support a built-in commercial flow in addition to proxy delivery. Billing resources describe payment and promotions; orders and data ledgers describe service entitlement. Keep those states separate in your own system.

Commercial state

Invoice amount, payment provider, coupon, checkout URL, and payment status.

Service state

The resulting order, package access, credentials, and available data.

A created invoice is not active proxy access

Do not enable service because invoice creation or checkout redirection succeeded. Confirm the paid state and the resulting entitlement through the documented resources and event flow.

Purchase flow

1. Read GET /packages and let the customer choose a currently available product and data amount.
2. If the customer enters a coupon, call POST /coupons/calculate-price to validate it and preview the original and discounted price.
3. Create the pending invoice with POST /invoices using the exact package, data, currency, payment-provider, and coupon fields documented by the schema.
4. Use GET /invoices/{id}/pay when the selected provider requires a hosted checkout URL.
5. Observe invoice and entitlement state after payment. Treat redirects as user experience, not proof of settlement.
6. Reconcile the new order, credentials, and data before showing the product as ready.

List and retrieve operations are scoped to resources visible to the authenticated account. Resellers and administrators can have broader filtering or management capabilities, but customer code must not assume staff permissions.

Invoices

Use the invoice endpoints to:

• list invoices visible to the current account;
• inspect billing, package, payment, and status details;
• create a pending invoice from current package pricing;
• retrieve a hosted payment link while an invoice is payable;
• download the generated PDF;
• remove an invoice only when the authenticated account and its current state allow it.

Persist the returned invoice ID next to your own checkout record. After a timeout on invoice creation, inspect visible invoices before repeating the write; the public contract does not promise universal write idempotency.

Coupons

Coupon calculation validates a code against the selected package and data amount without creating an invoice. Display both original and discounted values returned by the server and recalculate immediately before checkout.

Coupon creation, modification, deletion, and redemption inspection are staff operations. A normal customer-facing client should use only the coupon views and calculation behavior allowed by its account.

Never calculate the authoritative discount in the browser

Browser-side arithmetic is useful for presentation only. Package pricing, coupon eligibility, redemption limits, and the final invoice total must come from the API response.

Rewards

GET /rewards lists referral and campaign rewards visible to the authenticated account. POST /rewards/claim applies an eligible reward according to its type and validates claim thresholds and current state.

Refresh the profile, orders, or other balance-bearing resource after a successful claim. Do not assume every reward becomes the same kind of value: a deployment can represent monetary and data outcomes differently in the response contract.

Affiliates

Eligible affiliate accounts can list attributed customers, individual reward entries, and earnings over a requested period. The time-series endpoint follows the analytics rules for start, end, and IANA timezone.

Use this data for an affiliate dashboard and reconciliation export. Keep your own campaign attribution and payout records if your commercial process requires them; the affiliate views should not replace your accounting books.

Operational controls

Control	Recommended behavior
Amounts and currencies	Send and store exactly the units documented by each schema; do not infer precision from formatted labels
Payment redirects	Return customers only to an allowlisted URL in your application and read server-side status afterward
Ambiguous writes	Read current state before retrying invoice creation or reward claims
Permissions	Hide administrative coupon controls from non-staff users and still enforce authorization server-side
Audit trail	Record your customer ID, ProxyRequest resource ID, actor, timestamp, request result, and business reason
Reconciliation	Compare invoices, orders, allocations, webhook deliveries, and closed analytics windows independently

See the API resource map for the rest of the public surface and the generated API Reference for exact schemas.