> ## Documentation Index > Fetch the complete documentation index at: https://docs.beinfi.com/llms.txt > Use this file to discover all available pages before exploring further. # HTTP API > Hosts, authentication, idempotency and the API route reference. The SDK is a client of Infi's HTTP API. Use these endpoints from your own language or when debugging a request. ## Environments | Environment | API | Hosted checkout | | ----------------------- | -------------------------------- | -------------------------------- | | Sandbox (`sk_test_`) | `https://api-sandbox.beinfi.com` | `https://app-sandbox.beinfi.com` | | Production (`sk_live_`) | `https://api.beinfi.com` | `https://app.beinfi.com` | Use the correct host for the key. Sandbox resources do not exist in production. ## Authentication ```bash theme={null} curl https://api-sandbox.beinfi.com/metering/products \ -H "Authorization: Bearer $INFI_SECRET_KEY" ``` Use `Authorization: Bearer`, not `X-Api-Key`. Keep secret keys server-side. Public checkout routes under `/pay/{slug}` do not take a merchant secret key. ## Agent provisioning `POST /public/v1/claimables` is public and accepts optional `ref`, `accountName` and `email`. It returns `apiKeySecret`, `publishableKey`, `tenantSlug`, `productId`, `claimUrl` and `expiresAt`. Email is an unverified contact, never an identity. With the claim-email update, providing an address queues a transactional message with the link and deadline, at most once per address every 24 hours. A `201` confirms provisioning, not email delivery. Always preserve the returned claim URL. Read [agent onboarding](https://beinfi.com/en/agent-onboarding) for questions, credentials and human handoff. Do not blindly repeat this POST after a lost response: the account may already exist. ## Idempotency Authenticated mutations require an `Idempotency-Key`. Use a stable, unique value for each operation and reuse it only when retrying that same operation. ```bash theme={null} curl -X POST "https://api-sandbox.beinfi.com/metering/products/$PRODUCT_ID/payment-links" \ -H "Authorization: Bearer $INFI_SECRET_KEY" \ -H "Idempotency-Key: create-link-for-order-123" ``` This requires a published product. Creating a link does not charge a customer. Missing keys return `400 idempotency_key_required`; reusing a key with a different body returns `409 idempotency_key_reused`. Public bootstrap routes have their own requirements. Do not assume every public route needs a merchant key or uses the same request shape. ## Responses and errors Collection reads return envelopes such as `{"products": [...]} `. Resource creation may return a composite response: product creation returns both `product` and a draft `version`. Check the endpoint contract instead of assuming every resource is at the root. Errors may use the handler envelope (`error_code`, `message`, `errors`, `tracer_id`) or the middleware envelope (`error.code`, `error.message`, `error.request_id`). Preserve diagnostic IDs when reporting a problem. ## Routes The tables below are generated from the backend OpenAPI contract. Provider capabilities and Early access availability still apply; an endpoint's presence is not a promise that every connected provider supports its operation. ### Catalog and customers | Method | Route | | | ------------------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------- | | `GET` · `POST` | `/metering/customers` | List tenant customers | | `GET` | `/metering/customers/{customerID}` | Get tenant customer detail or legacy enrollment by ID | | `GET` · `POST` | `/metering/customers/{customerID}/credit` | Get a customer's credit balance and ledger entries | | `POST` | `/metering/customers/{customerID}/credit/consume` | Consume (deduct) credit from a customer | | `GET` · `POST` | `/metering/customers/{customerID}/rate-cards` | List a customer's rate cards | | `DELETE` | `/metering/customers/{customerID}/rate-cards/{rateCardID}` | Delete a rate card | | `GET` | `/metering/customers/{customerID}/state` | Single-read customer state (enrollment, credit, subscriptions, usage) | | `GET` | `/metering/customers/{customerID}/wallet` | Get meter wallet balances for an enrollment | | `POST` | `/metering/customers/{customerID}/wallet/credit` | Credit a meter balance | | `POST` | `/metering/customers/{customerID}/wallet/debit` | Debit a meter balance | | `POST` | `/metering/events` | Ingest a single usage event | | `POST` | `/metering/events/batch` | Ingest a batch of usage events (all-or-nothing) | | `GET` | `/metering/overview` | Tenant KPI summary for the dashboard overview | | `GET` · `POST` | `/metering/products` | List products | | `GET` · `PATCH` | `/metering/products/{productID}` | Get a product | | `GET` · `POST` | `/metering/products/{productID}/customers` | List product enrollments | | `GET` | `/metering/products/{productID}/customers/{enrollmentID}` | Get a product enrollment by enrollment ID | | `GET` · `PUT` · `DELETE` | `/metering/products/{productID}/deliverable` | Get a product's deliverable metadata | | `POST` | `/metering/products/{productID}/deliverable/presign` | Presign an R2 upload URL for a file deliverable | | `GET` · `POST` | `/metering/products/{productID}/meters` | List meters of a product | | `PATCH` | `/metering/products/{productID}/meters/{meterID}` | Update a meter's display name / unit / aggregation | | `GET` · `POST` | `/metering/products/{productID}/payment-links` | List a product's payment links | | `DELETE` | `/metering/products/{productID}/payment-links/{linkID}` | Revoke a payment link | | `GET` · `POST` | `/metering/products/{productID}/versions` | List versions of a product | | `PUT` | `/metering/products/{productID}/versions/{versionID}/commitment` | Set a committed minimum on a version | | `PUT` | `/metering/products/{productID}/versions/{versionID}/entitlements` | Replace the complete entitlement snapshot of a draft version | | `GET` · `POST` | `/metering/products/{productID}/versions/{versionID}/prices` | List prices on a version | | `POST` | `/metering/products/{productID}/versions/{versionID}/publish` | Publish a draft version (makes pricing immutable) | | `GET` | `/metering/usage` | Get usage totals for a customer | ### Billing and payments | Method | Route | | | -------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------- | | `GET` · `POST` | `/billing/coupons` | List the tenant's coupons | | `GET` · `PATCH` · `DELETE` | `/billing/coupons/{couponID}` | Get a coupon | | `GET` | `/billing/customers/{customerID}/invoices` | List a customer's invoices | | `GET` | `/billing/customers/{customerID}/payment-methods` | List a payer's stored payment methods | | `DELETE` | `/billing/customers/{customerID}/payment-methods/{instrumentID}` | Remove a stored payment method | | `POST` | `/billing/customers/{customerID}/payment-methods/{instrumentID}/default` | Make a stored payment method the payer's default | | `GET` | `/billing/customers/{customerID}/subscriptions` | List a customer's subscriptions | | `GET` · `POST` | `/billing/invoices` | List all invoices for the tenant | | `GET` | `/billing/invoices/{invoiceID}` | Get an invoice | | `POST` | `/billing/invoices/{invoiceID}/charge` | Charge an open invoice via the PSP | | `GET` | `/billing/invoices/{invoiceID}/deliverable` | List the download grants an invoice's payments produced | | `GET` | `/billing/invoices/{invoiceID}/invoice.pdf` | Get an invoice PDF | | `GET` | `/billing/invoices/{invoiceID}/payments` | List payments against an invoice | | `GET` | `/billing/invoices/{invoiceID}/receipt.pdf` | Get an invoice receipt PDF | | `POST` | `/billing/invoices/{invoiceID}/send` | Finalize and send an invoice | | `POST` | `/billing/invoices/{invoiceID}/uncollectible` | Mark an invoice uncollectible | | `POST` | `/billing/invoices/{invoiceID}/void` | Void an invoice | | `POST` | `/billing/invoices/from-usage` | Generate an invoice from an enrollment's accrued usage (on demand) | | `GET` | `/billing/payments` | List all payments for the tenant | | `GET` | `/billing/payments/{paymentID}` | Get one payment | | `POST` | `/billing/payments/{paymentID}/refund` | Refund a payment (full or partial) | | `GET` | `/billing/payments/{paymentID}/refunds` | List the refunds recorded against a payment | | `POST` | `/billing/products/{productID}/invoices` | Purchase a product — enroll the customer and open a finalized invoice | | `POST` | `/billing/products/{productID}/subscriptions` | Create a subscription for a customer | | `GET` · `PUT` | `/billing/settings` | Get the tenant's collection settings | | `GET` | `/billing/subscriptions` | List all subscriptions for the tenant | | `GET` · `PATCH` | `/billing/subscriptions/{subscriptionID}` | Get a subscription | | `GET` · `POST` | `/billing/subscriptions/{subscriptionID}/alerts` | List usage alerts on a subscription | | `DELETE` | `/billing/subscriptions/{subscriptionID}/alerts/{alertID}` | Delete a usage alert | | `POST` | `/billing/subscriptions/{subscriptionID}/invoices` | Generate an invoice for the subscription's current ended period | | `GET` | `/billing/subscriptions/{subscriptionID}/periods` | List billing periods of a subscription | ### Account | Method | Route | | | -------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- | | `GET` · `POST` | `/account/api-keys` | List API keys | | `DELETE` | `/account/api-keys/{keyID}` | Revoke an API key | | `GET` · `POST` | `/account/notification-subscriptions` | List notification subscriptions | | `PATCH` · `DELETE` | `/account/notification-subscriptions/{subscriptionID}` | Activate or deactivate a notification subscription | | `GET` | `/account/notifications/deliveries` | List notification delivery audit records | | `GET` | `/account/plan` | Effective plan, approved payment volume, invoice projection and entitlements | | `POST` | `/account/plan/activate` | Accept the current Terms and activate a postpaid live plan | | `POST` | `/account/plan/downgrade` | Schedule a paid self-service tier to Free at the next cycle boundary | | `POST` | `/account/plan/upgrade` | Confirm Scale as the account's minimum economic tier | | `GET` · `PATCH` | `/account/tenant` | Get the authenticated tenant | | `GET` · `POST` | `/account/webhooks` | List webhook endpoints | | `GET` · `PATCH` · `DELETE` | `/account/webhooks/{endpointID}` | Get a webhook endpoint | | `POST` | `/account/webhooks/{endpointID}/rotate-secret` | Rotate a webhook endpoint's signing secret | | `GET` | `/account/webhooks/deliveries` | List webhook delivery audit records | ### Public — no merchant key | Method | Route | | | ------ | --------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `GET` | `/pay/{slug}/download/{token}` | Redeem a tokenized digital-product download (unauthenticated) | | `GET` | `/pay/{slug}/invoices/{invoiceID}` | Public hosted-checkout invoice read (unauthenticated) | | `POST` | `/pay/{slug}/invoices/{invoiceID}/charge` | Initiate payment on a public checkout invoice (unauthenticated) | | `POST` | `/pay/{slug}/invoices/{invoiceID}/coupon` | Apply a coupon to a public checkout invoice (unauthenticated) | | `GET` | `/pay/{slug}/invoices/{invoiceID}/invoice.pdf` | Public hosted-checkout invoice PDF (unauthenticated) | | `GET` | `/pay/{slug}/invoices/{invoiceID}/payments/{paymentID}` | Read authoritative public payment status (unauthenticated) | | `GET` | `/pay/{slug}/invoices/{invoiceID}/receipt.pdf` | Public hosted-checkout receipt PDF (unauthenticated) | | `GET` | `/pay/{slug}/links/{token}` | Resolve a payment link for display (unauthenticated) | | `POST` | `/pay/{slug}/links/{token}/checkout` | Materialize an invoice from a payment link (unauthenticated, legacy) | | `POST` | `/pay/{slug}/links/{token}/sessions` | Open (or reuse) a checkout session for a payment link (unauthenticated) | | `GET` | `/pay/{slug}/links/{token}/sessions/{sessionID}` | Read a checkout session (unauthenticated) | | `POST` | `/pay/{slug}/links/{token}/sessions/{sessionID}/charge` | Materialize the invoice and charge a checkout session (unauthenticated) | | `GET` | `/pay/{slug}/links/{token}/sessions/{sessionID}/payments/{paymentID}` | Read authoritative link-session payment status (unauthenticated) | | `GET` | `/public/platform-plans` | Published Infi platform plans for the landing and calculators | | `POST` | `/public/v1/claimables` | Provision a claimable tenant (instant creds, claim later; no auth) | | `GET` | `/public/v1/claimables/{claimableID}` | Public claimable-tenant status (no secrets) | ### Operations — sessions and inbound webhooks | Method | Route | | | ------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------- | | `POST` | `/auth/claimables/{claimableID}/claim` | Claim a provisional tenant to the signed-in user | | `POST` | `/auth/cli/token` | Exchange dashboard session for CLI API key | | `POST` | `/auth/session/bootstrap` | Provision tenant on first dashboard signup | | `POST` | `/auth/session/onboarding/complete` | Mark tenant onboarding complete | | `POST` | `/auth/session/sync` | Sync dashboard session with backend membership | | `POST` | `/webhook/provider/payments/webhook` | Inbound PSP webhook (authenticated by the gateway signature) | | `POST` | `/webhook/provider/webhooks/{provider}/{externalAccountID}/{token}` | Inbound webhook for a provider whose deliveries are not self-authenticating | | `POST` | `/webhook/provider/webhooks/adyen/{externalAccountID}` | Inbound Adyen Standard webhook | ## Integration guides * [Quickstart](https://beinfi.com/en/inicio-rapido) * [TypeScript SDK](https://beinfi.com/en/sdk) * [Webhooks](https://beinfi.com/en/webhooks)