# API Keys Source: https://docs.paygentic.io/api-keys API keys authenticate requests to Paygentic. Each key belongs to a specific user and inherits that user's permissions. ## Key format Keys are environment-specific: | Environment | Prefix | Base URL | Usage | | - | - | - | - | | Sandbox | `sk_test_` | api.sandbox.paygentic.io | Development and testing | | Live | `sk_live_` | api.paygentic.io | Production | Sandbox keys only work with sandbox endpoints. Live keys only work with production endpoints. ## Creating keys 1. Log in to the Paygentic Dashboard 2. Navigate to More → Developer → API Keys 3. Select Create New Key 4. Name the key descriptively 5. Copy immediately - it won't be shown again Store keys securely. Use environment variables or secret managers, never commit to version control. ## Managing keys **Viewing keys** * See all active keys * Check creation dates * Identify by descriptive names * View partial values (last 4 characters) **Revoking keys** Navigate to More → Developer → API Keys, find the key, and select Revoke. Revocation is immediate — applications using that key will fail authentication. ## Usage Include keys in the Authorization header using Bearer authentication scheme. ## Security practices **Mandatory** * Never commit keys to git * Use environment variables * Rotate keys regularly * Revoke compromised keys immediately * Use sandbox keys for development only **Recommended** * Separate keys per application * Monitor usage to find inactive keys * Document which applications use which keys * Use descriptive key names ## Troubleshooting **Authentication failures** * Verify correct key format * Check key hasn't been revoked * Confirm environment match (test vs live) * Use correct base URL for environment **Permission errors** * Verify user permissions for the key * Check organization context * Contact admin for permission changes # Get an approval Source: https://docs.paygentic.io/api-reference/approvals/get-an-approval /openapi.json get /v0/approvals/{id} # List approvals Source: https://docs.paygentic.io/api-reference/approvals/list-approvals /openapi.json get /v0/approvals # Submit a resource for approval Source: https://docs.paygentic.io/api-reference/approvals/submit-a-resource-for-approval /openapi.json post /v0/approvals # Update an approval (approve, reject, or cancel) Source: https://docs.paygentic.io/api-reference/approvals/update-an-approval-approve-reject-or-cancel /openapi.json patch /v0/approvals/{id} # Create Source: https://docs.paygentic.io/api-reference/billable-metrics/create /openapi.json post /v0/billableMetrics Create a new billable metric for a merchant organization. A `Billable Metric` represents a metric that can be used to measure the usage of a `Product`. It contains information about the metric, such as its name, description, and units. # Get Source: https://docs.paygentic.io/api-reference/billable-metrics/get /openapi.json get /v0/billableMetrics/{id} # List Source: https://docs.paygentic.io/api-reference/billable-metrics/list /openapi.json get /v0/billableMetrics # List Meter Events Source: https://docs.paygentic.io/api-reference/billable-metrics/list-meter-events /openapi.json get /v0/billableMetrics/{id}/events List raw underlying events for a billable metric from the metering service. Returns events ordered by time descending. # Query Meter Usage Source: https://docs.paygentic.io/api-reference/billable-metrics/query-meter-usage /openapi.json get /v0/billableMetrics/{id}/meter Query aggregated usage data for a billable metric from the metering service. # Update Source: https://docs.paygentic.io/api-reference/billable-metrics/update /openapi.json patch /v0/billableMetrics/{id} # Create a billing schedule Source: https://docs.paygentic.io/api-reference/billing-schedules/create-a-billing-schedule /openapi.json post /v0/billingSchedules # Delete a billing schedule Source: https://docs.paygentic.io/api-reference/billing-schedules/delete-a-billing-schedule /openapi.json delete /v0/billingSchedules/{id} # Generate staged invoices Source: https://docs.paygentic.io/api-reference/billing-schedules/generate-staged-invoices /openapi.json post /v0/billingSchedules/{id}/invoices Generate (or regenerate) staged invoice projections for a schedule from its current intervals. Idempotent — replaces any existing staged rows. Schedule must have at least one interval. # Get a billing schedule Source: https://docs.paygentic.io/api-reference/billing-schedules/get-a-billing-schedule /openapi.json get /v0/billingSchedules/{id} # List billing schedules Source: https://docs.paygentic.io/api-reference/billing-schedules/list-billing-schedules /openapi.json get /v0/billingSchedules # List schedule intervals Source: https://docs.paygentic.io/api-reference/billing-schedules/list-schedule-intervals /openapi.json get /v0/billingSchedules/{id}/intervals # List staged invoices Source: https://docs.paygentic.io/api-reference/billing-schedules/list-staged-invoices /openapi.json get /v0/billingSchedules/{id}/invoices List the staged invoice projections for a schedule, newest period first. # Replace schedule intervals Source: https://docs.paygentic.io/api-reference/billing-schedules/replace-schedule-intervals /openapi.json put /v0/billingSchedules/{id}/intervals Replace (PUT semantics) the full interval set for a schedule. Wipes existing intervals and recreates from the supplied list. Reverts any in-flight order approval for order-owned schedules. # Update a billing schedule Source: https://docs.paygentic.io/api-reference/billing-schedules/update-a-billing-schedule /openapi.json patch /v0/billingSchedules/{id} # Create Source: https://docs.paygentic.io/api-reference/costs/create /openapi.json post /v0/costs Create a new metered cost for a product. # Delete Source: https://docs.paygentic.io/api-reference/costs/delete /openapi.json delete /v0/costs/{id} # Get Source: https://docs.paygentic.io/api-reference/costs/get /openapi.json get /v0/costs/{id} # List Source: https://docs.paygentic.io/api-reference/costs/list /openapi.json get /v0/costs # Query Summary Source: https://docs.paygentic.io/api-reference/costs/query-summary /openapi.json get /v0/costs/{id}/summary Query usage data and compute cost for a specific cost configuration. To retrieve summaries for all costs belonging to a merchant, first call listCosts to obtain cost IDs, then call this endpoint in parallel for each ID. # Report Source: https://docs.paygentic.io/api-reference/costs/report /openapi.json get /v0/costs/report Aggregate cost data across costs and customers with grouping, filtering, and time-series breakdown. # Update Source: https://docs.paygentic.io/api-reference/costs/update /openapi.json patch /v0/costs/{id} # Create Source: https://docs.paygentic.io/api-reference/customers/create /openapi.json post /v0/customers Create a new customer for a merchant organization. This endpoint is currently only used by the Paygentic platform as part of the subscription flow. # Delete Source: https://docs.paygentic.io/api-reference/customers/delete /openapi.json delete /v0/customers/{id} # Get Source: https://docs.paygentic.io/api-reference/customers/get /openapi.json get /v0/customers/{id} # List by Merchant Source: https://docs.paygentic.io/api-reference/customers/list-by-merchant /openapi.json get /v0/customers # List payment methods Source: https://docs.paygentic.io/api-reference/customers/list-payment-methods /openapi.json get /v0/customers/{id}/paymentMethods List off-session payment methods saved for this customer. # Set up a payment method Source: https://docs.paygentic.io/api-reference/customers/set-up-a-payment-method /openapi.json post /v0/customers/{id}/paymentMethods Create a payment session that captures a new off-session payment method for this customer without charging. The response contains a hosted-page URL — redirect the customer to it, or load it inside an iframe (when iframed, the page reports outcomes via `postMessage` to the parent window). # Update Source: https://docs.paygentic.io/api-reference/customers/update /openapi.json patch /v0/customers/{id} # Get Entitlement Source: https://docs.paygentic.io/api-reference/entitlements/get-entitlement /openapi.json get /v1/entitlements/{entitlementId} Retrieve a specific entitlement by ID. For metered entitlements, the response includes live balance, usage, and access status for the current billing period. # Issue Entitlement Source: https://docs.paygentic.io/api-reference/entitlements/issue-entitlement /openapi.json post /v1/entitlements Issue a new entitlement to a customer, granting them access to a specific feature. The feature must exist and belong to the same merchant as the customer. # List Entitlements Source: https://docs.paygentic.io/api-reference/entitlements/list-entitlements /openapi.json get /v1/entitlements Retrieve all entitlements for a customer, optionally filtered by feature or product. List items identify the entitlement with `entitlementId` (the original list contract). The get-by-id endpoint (`GET /v1/entitlements/{entitlementId}`) returns the same object but with a top-level `id` and `object: "entitlement"` instead — so use `item.entitlementId`, not `item.id`, when chaining a list result into a get-by-id call. For metered entitlements, each item carries live balance/usage fields, which the API resolves with one grant-engine balance lookup per metered item (bounded concurrency, up to `limit` items per page). # Ingest Event Source: https://docs.paygentic.io/api-reference/events/ingest-event /openapi.json post /v0/events Ingest a raw metering event. The event is published to the meter-events PubSub topic for processing by the meters service. # Create Source: https://docs.paygentic.io/api-reference/externalreferences/create /openapi.json post /v0/externalReferences # Delete Source: https://docs.paygentic.io/api-reference/externalreferences/delete /openapi.json delete /v0/externalReferences/{id} # Get Source: https://docs.paygentic.io/api-reference/externalreferences/get /openapi.json get /v0/externalReferences/{id} # List Source: https://docs.paygentic.io/api-reference/externalreferences/list /openapi.json get /v0/externalReferences # Update Source: https://docs.paygentic.io/api-reference/externalreferences/update /openapi.json patch /v0/externalReferences/{id} # Create Source: https://docs.paygentic.io/api-reference/features/create /openapi.json post /v0/features # Delete Source: https://docs.paygentic.io/api-reference/features/delete /openapi.json delete /v0/features/{id} # Get Source: https://docs.paygentic.io/api-reference/features/get /openapi.json get /v0/features/{id} # List Source: https://docs.paygentic.io/api-reference/features/list /openapi.json get /v0/features List features by productId, optionally filtered by key # Update Source: https://docs.paygentic.io/api-reference/features/update /openapi.json patch /v0/features/{id} # Create Source: https://docs.paygentic.io/api-reference/fees/create /openapi.json post /v0/fees Create a new fee for a merchant organization. A `Fee` represents a charge that can be applied to subscriptions. Cadence is defined when creating a Price for the fee. # Delete Source: https://docs.paygentic.io/api-reference/fees/delete /openapi.json delete /v0/fees/{id} # Get Source: https://docs.paygentic.io/api-reference/fees/get /openapi.json get /v0/fees/{id} # List Source: https://docs.paygentic.io/api-reference/fees/list /openapi.json get /v0/fees # Update Source: https://docs.paygentic.io/api-reference/fees/update /openapi.json patch /v0/fees/{id} # Create Grant Source: https://docs.paygentic.io/api-reference/grants/create-grant /openapi.json post /v1/entitlements/{entitlementId}/grants Create a grant directly for a metered entitlement, crediting the customer's balance immediately. The entitlement must belong to an active v1 subscription. # Get Grant Source: https://docs.paygentic.io/api-reference/grants/get-grant /openapi.json get /v1/entitlements/{entitlementId}/grants/{grantId} Retrieve a specific grant by ID. # List Grants Source: https://docs.paygentic.io/api-reference/grants/list-grants /openapi.json get /v1/entitlements/{entitlementId}/grants List grants for a metered entitlement. Active grants are returned by default; pass `includeVoided=true` to include voided grants. # Purchase Grant Source: https://docs.paygentic.io/api-reference/grants/purchase-grant /openapi.json post /v1/entitlements/{entitlementId}/grants/purchase Create an ad-hoc invoice with a payment session for a grant purchase. The customer pays via the returned payment URL; the grant is created automatically on payment completion. If payment expires, the invoice is cancelled and no grant is created. To confirm payment completion, subscribe to the `invoice.paid.v0` webhook. The payload includes the original `invoiceId` and the created `grantId`, so you can correlate the purchase response with downstream fulfilment without an extra fetch. As a fallback if you cannot consume webhooks, poll `GET /v2/invoices/{invoiceId}` (interval 2s, timeout 60s) and check for `status === "PAID"`. # Void Grant Source: https://docs.paygentic.io/api-reference/grants/void-grant /openapi.json delete /v1/entitlements/{entitlementId}/grants/{grantId} Void a grant, removing it from the customer's balance. This operation is idempotent — voiding an already-voided grant returns the voided grant without error. # Create Manual Line Item Source: https://docs.paygentic.io/api-reference/invoices-v2/create-manual-line-item /openapi.json post /v2/invoices/lineItems Create a manual line item for a billing v1 subscription. Manual line items are ad-hoc charges or credits that flow through the same collection pipeline as auto-generated items. Exactly one of subscriptionId or invoiceId must be provided. # Download Invoice PDF Source: https://docs.paygentic.io/api-reference/invoices-v2/download-invoice-pdf /openapi.json get /v2/invoices/{id}/pdf Downloads the Paygentic-rendered invoice document. The caller must be authenticated and entitled to the invoice; the stored document is streamed back, so no storage URL is ever handed out. Returns 404 when the invoice's document is the tax provider's rather than ours — in that case the invoice resource reports pdfSource `tax_provider` and its pdfUrl points at the provider's link instead. # Get Source: https://docs.paygentic.io/api-reference/invoices-v2/get /openapi.json get /v2/invoices/{id} Retrieve a single invoice with real-time aggregates (for ACTIVE/CLOSING/CLOSED) or cached aggregates (for finalized invoices). Optionally include line items with expand=lineItems. # Get Line Items Source: https://docs.paygentic.io/api-reference/invoices-v2/get-line-items /openapi.json get /v2/invoices/{id}/lineItems Get paginated line items for an invoice # List Source: https://docs.paygentic.io/api-reference/invoices-v2/list /openapi.json get /v2/invoices List invoices with optional filters. Platform users can use nextActionAt=ready to get invoices ready for processing. # List Invoice Refunds Source: https://docs.paygentic.io/api-reference/invoices-v2/list-invoice-refunds /openapi.json get /v2/invoices/{id}/refunds List the credit notes (refunds) recorded against an invoice. Accessible to the owning merchant or platform operators. # List Line Items Source: https://docs.paygentic.io/api-reference/invoices-v2/list-line-items /openapi.json get /v2/invoices/lineItems List pending and invoiced line items for a subscription from the billing database. Returns exact fee amounts and estimated metered charges. # List projected Source: https://docs.paygentic.io/api-reference/invoices-v2/list-projected /openapi.json get /v2/invoices/projected List the invoices a subscription will issue in a range of invoice moments, one projected invoice for each distinct invoice moment. Projected invoices are derived on each read and never stored. Each has status PROJECTED, and its id is stable between reads, but GET /v2/invoices/{id} returns 404 for it. Totals EXCLUDE usage: metered charges are not projected, and an invoice moment that has only metered charges is omitted. Tax and sequenceNumber are estimates. The range filters on the invoice moment (invoiceAt) in [from, to). A from before now is treated as now. to must be after from and at most one year after now; now is the subscription's test-clock time when it has a test clock. A terminated subscription returns an empty list. Each invoice carries its lines in lineItems. Authorization is the same as listing invoices. # Refund Invoice Source: https://docs.paygentic.io/api-reference/invoices-v2/refund-invoice /openapi.json post /v2/invoices/{id}/refunds Issue a full refund against a paid invoice by creating a credit note. The invoice stays PAID; the refund is recorded as a child credit note. Accessible to the owning merchant or platform operators. Only works for invoices in PAID status that have not already been refunded. Full refund only — the entire invoice (subtotal + tax) is credited. # Retry Payment Source: https://docs.paygentic.io/api-reference/invoices-v2/retry-payment /openapi.json post /v2/invoices/{id}/retryPayment Charge the customer's saved payment method again for an unpaid invoice. The invoice must be in status `ISSUED` or `PAYMENT_FAILED`, auto-charge must be on for its subscription, and the invoice must have a payment session. If not, the response is 400. The response status tells you the result. Only 200 means that the charge succeeded. Every other response from this operation that has a `retry_payment_result` body has `success: false`, and `error.code` gives the reason: | Status | `error.code` | Meaning | | --- | --- | --- | | 200 | — | The charge succeeded, the provider had already collected it, or no amount is unpaid. | | 202 | `processing` | The provider accepted the charge. It settles later (for example, a bank debit). | | 402 | a decline code, for example `card_declined`, `insufficient_funds`, `do_not_honor`, `authentication_required` | The provider declined the payment method. | | 409 | `concurrent_attempt` | Another payment attempt for this invoice is in progress. | | 409 | `PAYMENT_SESSION_EXPIRED` | The payment link expired (after 30 days). Create a new link with `POST /v2/invoices/{id}/payment` and `method: hosted_link`, then retry. If the customer also has no usable saved payment method, the response is 422 instead. | | 409 | another value, or no `code` | The payment session cannot be charged in its current state (for example `session_unusable`, `non_confirmable`, `PAYMENT_PROCESSING`, `PAYMENT_ALREADY_COMPLETED`). Read `error.message` for the cause. | | 422 | `no_payment_method` | The customer has no usable saved payment method. Send a payment link instead. | | 502 | `provider_unavailable` or none | The payment provider did not answer, or the provider failed the charge for a reason that is not known. Retry later. | A 500 response has the standard error body, not `retry_payment_result`. It is an internal error, and a retry does not fix it. An invoice that does not exist returns 404, the same as an invoice of another merchant. This operation is rate limited to one call each minute for each invoice. # Settle Invoice Payment Source: https://docs.paygentic.io/api-reference/invoices-v2/settle-invoice-payment /openapi.json post /v2/invoices/{id}/payment Settle an unpaid invoice in status `ISSUED` or `PAYMENT_FAILED`. The `method` field selects how. - `hosted_link`: create a new hosted payment link and email it to the customer. The invoice stays unpaid until the customer pays on the link. Each call replaces the previous link. A payment link expires after 30 days; to collect an invoice whose link has expired, call this method again. - `out_of_band`: record a payment that you collected outside Paygentic. The invoice changes to `PAID` immediately. A second call returns 409. For `hosted_link`, an invoice that does not exist returns 404, the same as an invoice of another merchant. Paygentic selects the payment provider from your connected payment account. The response reports the provider. **Warning:** each `hosted_link` call creates a new link and sends the customer a new email. Do not retry a `hosted_link` call after a timeout: first read the invoice to see if a new link exists. # Void Invoice Refund Source: https://docs.paygentic.io/api-reference/invoices-v2/void-invoice-refund /openapi.json post /v2/invoices/{id}/refunds/{refundId}/void Void a previously-issued refund (credit note). Reverses the credit note in the tax provider and excludes it from revenue. Accessible to the owning merchant or platform operators. # Create Source: https://docs.paygentic.io/api-reference/items/create /openapi.json post /v0/items # Get Source: https://docs.paygentic.io/api-reference/items/get /openapi.json get /v0/items/{id} # List Source: https://docs.paygentic.io/api-reference/items/list /openapi.json get /v0/items # Update Source: https://docs.paygentic.io/api-reference/items/update /openapi.json patch /v0/items/{id} # Get the caller Source: https://docs.paygentic.io/api-reference/me/get-the-caller /openapi.json get /v0/me Returns the caller's identity in its active organization, its roles, and the permissions that its credential holds there. The permissions are the effective set for the credential of the call: for a session or an API key, those of the principal; for an OAuth token, those of the principal narrowed to the scopes of the token. # Reset a merchant's data Source: https://docs.paygentic.io/api-reference/merchant-data/reset-a-merchants-data /openapi.json post /v0/merchants/{merchantId}/reset With `scope: merchant`, deletes the merchant's customers and everything attached to them: subscriptions, invoices, line items, payments, entitlements, grants, orders, test clocks, usage events, invoice documents and, when tax is enabled, the documents in the merchant's Quaderno sandbox account. `keepCatalog: true` keeps the catalog (products, plans, prices, fees, features, billable metrics), and `keepCatalog: false` deletes it too; the merchant's configuration is always kept. With `scope: customer`, deletes one customer and what is attached to it; test clocks and the Quaderno account's documents are kept, since they belong to no single customer. A `204` means every delete is done or scheduled: usage events and Quaderno documents finish in the background, and usage events still being ingested while it runs can survive it. A `502` means a store outside Postgres failed; the customers are already out of the API, and calling again with the same body finishes the reset. Calling again is always safe. While a customer waits for that, its external id is free for a new customer to take; a retry then deletes usage events by customer id only. Not available in production. # Disconnect Source: https://docs.paygentic.io/api-reference/merchantintegrations/disconnect /openapi.json patch /v0/merchantIntegrations/{id}/disconnect Soft-disconnect a connection (status `disconnected`, stamp `disconnectedAt`). Never hard-deletes — preserves the install id and `connectedAt` for audit. # Get Source: https://docs.paygentic.io/api-reference/merchantintegrations/get /openapi.json get /v0/merchantIntegrations/{id} # List Source: https://docs.paygentic.io/api-reference/merchantintegrations/list /openapi.json get /v0/merchantIntegrations # Upsert Source: https://docs.paygentic.io/api-reference/merchantintegrations/upsert /openapi.json put /v0/merchantIntegrations Create or re-activate a merchant's connection to a provider. Idempotent on `(merchantId, provider)` — connecting an already-connected provider re-activates the existing row, never creating a duplicate. # Add a line item Source: https://docs.paygentic.io/api-reference/orders/add-a-line-item /openapi.json post /v0/orders/{orderId}/lineItems # Create an approval for the order Source: https://docs.paygentic.io/api-reference/orders/create-an-approval-for-the-order /openapi.json post /v0/orders/{orderId}/approvals Submit the order for maker-checker approval. Returns 409 if a pending approval already exists. # Create an order Source: https://docs.paygentic.io/api-reference/orders/create-an-order /openapi.json post /v0/orders # Delete a line item Source: https://docs.paygentic.io/api-reference/orders/delete-a-line-item /openapi.json delete /v0/orders/{orderId}/lineItems/{id} # Delete an order Source: https://docs.paygentic.io/api-reference/orders/delete-an-order /openapi.json delete /v0/orders/{id} # Get an order Source: https://docs.paygentic.io/api-reference/orders/get-an-order /openapi.json get /v0/orders/{id} # List orders Source: https://docs.paygentic.io/api-reference/orders/list-orders /openapi.json get /v0/orders # Update a line item Source: https://docs.paygentic.io/api-reference/orders/update-a-line-item /openapi.json patch /v0/orders/{orderId}/lineItems/{id} # Update an order Source: https://docs.paygentic.io/api-reference/orders/update-an-order /openapi.json patch /v0/orders/{id} # List Source: https://docs.paygentic.io/api-reference/payment-sessions/list /openapi.json get /v0/paymentSessions List payment sessions for the authenticated merchant with optional filters. Supports filtering by subscriptionId, customerId, status, and entityType. When subscriptionId is provided the result includes both the subscription's own activation session (entityType='subscription') and any session attached to invoices for that subscription (entityType='invoice'). When customerId is provided the result covers the customer's full payment history: payment-link sessions (entityType='payment'), the activation sessions of the customer's subscriptions, and the sessions of those subscriptions' invoices. # Create Payment Source: https://docs.paygentic.io/api-reference/payments/create-payment /openapi.json post /v0/payments Create a new payment for collecting a one-off charge. Returns a payment URL that can be shared with the customer. # Get Payment Source: https://docs.paygentic.io/api-reference/payments/get-payment /openapi.json get /v0/payments/{id} Retrieve a single payment by ID. # List Payments Source: https://docs.paygentic.io/api-reference/payments/list-payments /openapi.json get /v0/payments List payments for the authenticated merchant with optional filters. # Create Source: https://docs.paygentic.io/api-reference/plans/create /openapi.json post /v0/plans # Get Source: https://docs.paygentic.io/api-reference/plans/get /openapi.json get /v0/plans/{id} # Get a version Source: https://docs.paygentic.io/api-reference/plans/get-a-version /openapi.json get /v0/plans/{id}/versions/{versionNumber} Get a single plan version, including its price slots. Only accounts that can manage this plan may read its versions; versions can expose in-progress pricing, so read-only access is not sufficient. # List Source: https://docs.paygentic.io/api-reference/plans/list /openapi.json get /v0/plans # List Available Plans Source: https://docs.paygentic.io/api-reference/plans/list-available-plans /openapi.json get /v0/plans/available Retrieves all plans for a merchant that the customer does not have an active or pending subscription for. When a customer has a subscription for any plan within a product, all plans from that product are excluded. # List versions Source: https://docs.paygentic.io/api-reference/plans/list-versions /openapi.json get /v0/plans/{id}/versions List the versions of a plan, newest first. Only accounts that can manage this plan may list its versions; versions can expose in-progress pricing, so read-only access is not sufficient. # Mint a plan version Source: https://docs.paygentic.io/api-reference/plans/mint-a-plan-version /openapi.json post /v0/plans/{id}/versions Mint a new plan version from the price set it is to hold, and make it the version the plan bills from, in one step. The request names the complete set, not a change to it: create prices beforehand with POST /prices, then list every price the new version holds. The change against the current version follows from the keys — a key on both sides with a different price ID replaces that line, a key only in the request adds a line, and a key the current version holds and the request omits removes that line. To return to an earlier price set, make that version the default with a PATCH on the version. # Set the default version Source: https://docs.paygentic.io/api-reference/plans/set-the-default-version /openapi.json patch /v0/plans/{id}/versions/{versionNumber} Point the plan's default at this version, so its floating subscriptions bill from it. Any version may become default, in either direction — this is how you roll a plan back to (or forward to) an earlier price set. Idempotent when the version is already the default. # Update Source: https://docs.paygentic.io/api-reference/plans/update /openapi.json patch /v0/plans/{id} # Create Source: https://docs.paygentic.io/api-reference/prices/create /openapi.json post /v0/prices # Delete Source: https://docs.paygentic.io/api-reference/prices/delete /openapi.json delete /v0/prices/{id} # Get Source: https://docs.paygentic.io/api-reference/prices/get /openapi.json get /v0/prices/{id} # List Source: https://docs.paygentic.io/api-reference/prices/list /openapi.json get /v0/prices # Update Source: https://docs.paygentic.io/api-reference/prices/update /openapi.json patch /v0/prices/{id} Updates a price. `paymentTerm` and `billingCadence` are fixed when the price is created: a request that sends either one is refused with a 400. To change them, create a new price. # Create Source: https://docs.paygentic.io/api-reference/products/create /openapi.json post /v0/products # Get Source: https://docs.paygentic.io/api-reference/products/get /openapi.json get /v0/products/{id} # List Source: https://docs.paygentic.io/api-reference/products/list /openapi.json get /v0/products # Update Source: https://docs.paygentic.io/api-reference/products/update /openapi.json patch /v0/products/{id} # Get profitability summary Source: https://docs.paygentic.io/api-reference/profitability/get-profitability-summary /openapi.json get /v0/profitability Returns a per-customer profitability summary for a merchant over a date range. Each row aggregates revenue (invoices issued in the period, whatever their status since, less refunds, both excluding tax; the same figure /v0/revenue reports), cost (from metered cost discovery), profit, and margin. Customers are ranked by profit descending and capped at topN; the remainder is rolled into a single self-consistent 'Other' row whose revenue, cost, and profit reflect the same set of customers. Rows are joined against the merchant's customer list, so meter subjects that match no customer are dropped. Soft-deleted customers with revenue or cost in the period are folded into a single 'deleted' row, which always comes last, after 'Other', and takes no top-N slot. # Get revenue summary Source: https://docs.paygentic.io/api-reference/revenue/get-revenue-summary /openapi.json get /v0/revenue Returns revenue summary with invoice and payment breakdowns (outstanding/paid/writtenOff), plus a time-series trend. Revenue is what was billed in the period (by default, invoices issued in it; see periodBasis), whatever their status since, less refunds, both excluding tax; completed payments are reported under payments, never in revenue. # List customer accounts Source: https://docs.paygentic.io/api-reference/revenue/list-customer-accounts /openapi.json get /v0/revenue/accounts Returns each customer's account as at today, one row per customer and currency, with a total per currency. Every figure covers all dates: there is no date window. `outstanding` is what customers owe: every invoice with status `ISSUED` or `PAYMENT_FAILED`, at the amount due printed on the invoice (subtotal and tax, each rounded to the currency's minor unit), so it is gross of tax. Revenue (`GET /v0/revenue`) is net of tax. `outstanding` splits into `awaitingPayment` (status `ISSUED`) and `paymentFailed` (status `PAYMENT_FAILED`, collection has ended); the two always add up to it, in count and amount. A credit invoice (a negative amount due) nets against what is owed and is counted in no `count`; nor is an invoice whose amount due rounds to zero. A customer with nothing counted and nothing owed has no row. Amounts are grouped by currency and never combined or converted. `totals` covers every row in the filter, not only the returned page, so the rows on one page add up to `totals` only when the page holds every row. Pages fetched in separate requests are separate reads. # List Salesforce accounts Source: https://docs.paygentic.io/api-reference/salesforce/list-salesforce-accounts /openapi.json get /v0/integrations/salesforce/accounts Returns Accounts from the merchant's connected Salesforce org via live proxy SOQL. # Approve Source: https://docs.paygentic.io/api-reference/sources/approve /openapi.json post /v0/sources/{id}/events/{eventId}/approve Approve a pending source event to create a usage event # Bulk Approve Source: https://docs.paygentic.io/api-reference/sources/bulk-approve /openapi.json post /v0/sources/{id}/events/bulk-approve Approve multiple pending source events at once # Bulk Reject Source: https://docs.paygentic.io/api-reference/sources/bulk-reject /openapi.json post /v0/sources/{id}/events/bulk-reject Reject multiple pending source events at once # Create Source: https://docs.paygentic.io/api-reference/sources/create /openapi.json post /v0/sources Create a new source for automated usage event generation from external data sources. # Create Rule Source: https://docs.paygentic.io/api-reference/sources/create-rule /openapi.json post /v0/sourceRules Create a rule for automatically approving source events. When a pending source event matches ALL conditions in a rule, it will be automatically approved and converted to a usage event. Rules are evaluated in order (lowest order number first), and the first matching rule triggers auto-approval. Maximum 10 rules per source. # Delete Rule Source: https://docs.paygentic.io/api-reference/sources/delete-rule /openapi.json delete /v0/sourceRules/{ruleId} # Get Source: https://docs.paygentic.io/api-reference/sources/get /openapi.json get /v0/sources/{id} # Get Rule Source: https://docs.paygentic.io/api-reference/sources/get-rule /openapi.json get /v0/sourceRules/{ruleId} # List Source: https://docs.paygentic.io/api-reference/sources/list /openapi.json get /v0/sources # List Events Source: https://docs.paygentic.io/api-reference/sources/list-events /openapi.json get /v0/sources/{id}/events List events for a specific source with optional status filtering # List Rules Source: https://docs.paygentic.io/api-reference/sources/list-rules /openapi.json get /v0/sourceRules List all auto-acceptance rules for a source. These rules automatically approve pending source events when all conditions are met. # Reject Source: https://docs.paygentic.io/api-reference/sources/reject /openapi.json post /v0/sources/{id}/events/{eventId}/reject Reject a pending source event # Update Source: https://docs.paygentic.io/api-reference/sources/update /openapi.json patch /v0/sources/{id} # Update Rule Source: https://docs.paygentic.io/api-reference/sources/update-rule /openapi.json patch /v0/sourceRules/{ruleId} # Create Source: https://docs.paygentic.io/api-reference/subscriptions/create /openapi.json post /v0/subscriptions Creates a subscription for an existing customer or creates a new customer as part of the action. # Create Adjustment Source: https://docs.paygentic.io/api-reference/subscriptions/create-adjustment /openapi.json post /v0/subscriptions/{id}/adjustments Attaches an adjustment to the subscription for a dated window. A percentageDiscount reduces every discountable charge by a rate and carries one discount line per charge on the invoice. A usageDiscount takes a number of usage units off one metered price's billable quantity before that line is priced, so the line re-slots on a volume ladder and shows the corrected quantity; it emits no line of its own. Tax is assessed on the reduced amount either way. An invoice that already exists is not changed, including one still in draft — the adjustment reaches the periods that close after it is created. There is no update operation, and a window cannot be changed after it is created. To change an adjustment before any invoice has issued under it, delete it and create a replacement. Once an invoice has issued the adjustment is permanent, so set effectiveTo at creation time whenever the deal has a known end date. # Delete Adjustment Source: https://docs.paygentic.io/api-reference/subscriptions/delete-adjustment /openapi.json delete /v0/subscriptions/{id}/adjustments/{adjustmentId} Stops an adjustment from applying to any period it has not already been billed on. An adjustment that has never reached an issued invoice is removed, and the response is 204. An adjustment that has already been billed on an issued invoice is RETRACTED instead: its effectiveTo moves to the end of the last period it was billed on, the adjustment still exists, and the response is 200 carrying it. Read a 200 as "shortened", not as "removed". No invoice changes either way: an issued invoice keeps its numbers, and a draft loses the adjustment only when its period is calculated again. Deleting the same adjustment again returns the same 200 and the same window. # Edit Price Intervals Source: https://docs.paygentic.io/api-reference/subscriptions/edit-price-intervals /openapi.json post /v0/subscriptions/{id}/intervals Adds, edits, or removes price intervals on the subscription. Use an add to override a plan price for a period. Use an edit to change unitPrice, baseQuantity, quantityTransitions, or endDate. Use a remove to delete an interval. To close a price, set endDate. To re-open it, set endDate to null. To send an interval from a GET response as an edit, remove kind from it. An edit with no changed field changes nothing. If you send an add again after a timeout, it fails with 409 because it overlaps the first add. Use GET to check the result. The request is rejected if it changes a billing period that already exists, leaves a gap or an overlap, or bills a one-off price more than once. # Generate Portal Link Source: https://docs.paygentic.io/api-reference/subscriptions/generate-portal-link /openapi.json post /v0/subscriptions/{id}/portal Generates a secure, time-limited URL that allows customers to access their subscription data without authentication. # Get Source: https://docs.paygentic.io/api-reference/subscriptions/get /openapi.json get /v0/subscriptions/{id} # Get Price Intervals Source: https://docs.paygentic.io/api-reference/subscriptions/get-price-intervals /openapi.json get /v0/subscriptions/{id}/intervals Returns all the price intervals of the subscription, ordered by start date. This includes intervals that ended and intervals that start in the future. If there are none, returns an empty array. # List Source: https://docs.paygentic.io/api-reference/subscriptions/list /openapi.json get /v0/subscriptions # List Adjustments Source: https://docs.paygentic.io/api-reference/subscriptions/list-adjustments /openapi.json get /v0/subscriptions/{id}/adjustments Reads the adjustments on the subscription, oldest window first. A subscription with no adjustment returns an empty array. Paginated, because a long-running subscription accumulates one adjustment per rate change of every deal it has carried. # List Interval Changes Source: https://docs.paygentic.io/api-reference/subscriptions/list-interval-changes /openapi.json get /v0/subscriptions/{id}/intervalChanges Lists the subscription's interval changes, oldest first. Each shows why it was made and each interval before and after. # List Merchant Interval Changes Source: https://docs.paygentic.io/api-reference/subscriptions/list-merchant-interval-changes /openapi.json get /v0/intervalChanges Lists the interval changes of all your subscriptions, oldest first. `from` is included and `to` is excluded. # Migrate To A Plan Version Source: https://docs.paygentic.io/api-reference/subscriptions/migrate-to-a-plan-version /openapi.json post /v0/subscriptions/{id}/versionMigration Moves the subscription to a named version of its plan. By default the move follows the plan's versionTransition. With timing next_period, the move takes effect at the end of the current billing period: the current period bills as before, and each period that starts at or after that boundary bills from the target version. With timing immediate, entitlements change at once, in-arrears prices bill the whole current period at the target version, and in-advance prices change at the end of the current period, with no proration. The target can be an older or a newer published version. A migration always sets versionPolicy to pinned, so a later change of the plan's default version does not move the subscription. To follow the plan default again, call PATCH /v0/subscriptions/{id} with versionPolicy: 'floating'. A second migration before the boundary replaces the first. Migrating to the version the subscription is already on changes nothing except that it pins a floating subscription, so it is safe to repeat. A version number that does not exist on the plan and an archived version both return 404. The request is refused with 409 and a code when: the subscription is not live; the subscription ends at or before the boundary; a kept override has a rate that would mean something else on the new price; a feature's reset period, metric or pricing unit changes; or the new version sells a price that a continuing interval already covers. # Reconcile Features Source: https://docs.paygentic.io/api-reference/subscriptions/reconcile-features /openapi.json post /v0/subscriptions/{id}/reconciliations Creates a reconciliation that converges a subscription's feature entitlements to its current plan. Provisions a missing entitlement (and, for metered features, its initial grant) for every plan feature the subscription does not already have; cancels the entitlement and voids the grants of any feature no longer on the plan; then synchronizes the corresponding prices' billing. An already-present feature is left unchanged. Restricted to active subscriptions billed on their plan's line-item schedule. # Terminate Source: https://docs.paygentic.io/api-reference/subscriptions/terminate /openapi.json post /v0/subscriptions/{id}/termination Terminates a subscription with a required reason. This endpoint is for merchant-initiated termination only. # Update Source: https://docs.paygentic.io/api-reference/subscriptions/update /openapi.json patch /v0/subscriptions/{id} # Advance Source: https://docs.paygentic.io/api-reference/test-clocks/advance /openapi.json patch /v0/testClocks/{id} Advances the test clock's current time. You can either specify a new absolute time or advance by a duration. A clock moves forward only, and at most 1 year per call: a time earlier than the clock's current time, or more than 1 year after it, returns 400. To move further, advance more than once. # Create Source: https://docs.paygentic.io/api-reference/test-clocks/create /openapi.json post /v0/testClocks Creates a new test clock with an optional initial time. If no time is provided, uses the current time. # Delete Source: https://docs.paygentic.io/api-reference/test-clocks/delete /openapi.json delete /v0/testClocks/{id} Soft deletes a test clock. The clock will be marked as deleted but not removed from the database. # Get Source: https://docs.paygentic.io/api-reference/test-clocks/get /openapi.json get /v0/testClocks/{id} Retrieves details of a specific test clock # List Source: https://docs.paygentic.io/api-reference/test-clocks/list /openapi.json get /v0/testClocks Retrieves a paginated list of test clocks # Get Source: https://docs.paygentic.io/api-reference/users/get /openapi.json get /v0/users/{id} # Update Source: https://docs.paygentic.io/api-reference/users/update /openapi.json patch /v0/users/{id} # Disable Source: https://docs.paygentic.io/api-reference/webhooks/disable /openapi.json delete /v0/webhooks Pauses webhook delivery. This has the same effect as the update operation with `enabled: false`: it does not delete the configuration, the endpoints or their event subscriptions. Use the update operation with `enabled: true` to resume delivery. Returns 404 if webhooks have never been enabled. # Enable Source: https://docs.paygentic.io/api-reference/webhooks/enable /openapi.json post /v0/webhooks Turns on webhook delivery for your account. Call it once: when a configuration already exists, enabled or disabled, the response is 400 with code `DUPLICATE_RESOURCE`. Use the update operation to turn delivery on or off after that. Endpoint URLs, event subscriptions and the signing secret are managed in the webhook portal. # Get Source: https://docs.paygentic.io/api-reference/webhooks/get /openapi.json get /v0/webhooks Returns the webhook configuration for your account. Returns 404 if webhooks have never been enabled. # Get Portal Access Source: https://docs.paygentic.io/api-reference/webhooks/get-portal-access /openapi.json get /v0/webhooks/portal Returns a link to the webhook portal, where you add endpoints, choose event types, read the signing secret and inspect deliveries. The link opens without a login and expires one hour after it is issued, at `expiresAt`. Treat it as a secret. The link is read-only unless the caller holds `webhooks:write`: a read-only portal shows endpoints and deliveries but does not let you add or change endpoints, read the signing secret or replay messages. Returns 404 unless webhooks are enabled. # Update Source: https://docs.paygentic.io/api-reference/webhooks/update /openapi.json patch /v0/webhooks Turns webhook delivery on or off. Set `enabled` to `false` to pause delivery and to `true` to resume it. Endpoints and their event subscriptions are kept. Returns 404 if webhooks have never been enabled. # Authentication Source: https://docs.paygentic.io/authentication Paygentic uses API keys as bearer tokens for authentication. Every request must include a valid key. ## Key structure Keys are tied to users and environments: * Each key belongs to one user * Inherits that user's permissions * Environment-specific: `sk_test_` (sandbox) or `sk_live_` (production) * Work only with their matching API endpoint See [Environments](/getting-started/environments) for details on sandbox vs production. ## Getting keys After logging into the Paygentic dashboard: 1. Navigate to More → Developer → API Keys 2. Copy your key Store securely in environment variables or secret managers. Never expose in client-side code or commit to version control. ## Making requests Include keys in the Authorization header using Bearer authentication scheme. All requests must use HTTPS. HTTP requests will fail. Unauthenticated requests will fail. For user permission management, see [Organizations](/platform/organizations). # Changelog Source: https://docs.paygentic.io/changelog Product updates and announcements **October 22, 2026** ## Filter the subscriptions list by several statuses `GET /v0/subscriptions` now takes `status` as a list. Repeat the parameter to pass several, for example `?status=active&status=pending_payment`. The page and `pagination.total` both count subscriptions in any of the listed statuses. **Breaking**: from TypeScript SDK 0.12.0, `subscriptions.list()` takes `status` as an array. Code that passes a string no longer compiles, and from plain JavaScript it throws `SDKValidationError` before any request is sent. ### What changed * `status` takes one or more values. A single `?status=active` still filters on that one status * A query parameter in bracket syntax, such as `status[]=active` or `status[0]=active`, now gets a `400` on every endpoint that takes query parameters. Before, the API ignored it and returned results without that filter * The SDK leaves an empty `status` list out of the request, so an empty list returns every status. Check for an empty list before you call if it should match nothing ### What's unaffected * SDK versions before 0.12.0 keep working. They send a single `status=` value, which the API still accepts * A request without `status` still returns every status ### If you upgrade the SDK Wrap a single status in an array: `status: "active"` becomes `status: ["active"]`. **October 9, 2026** ## See how each invoice line was calculated Each invoice line now saves a trace of how its amount before tax was reached, at the moment the invoice is calculated. Add `lineProvenance` to `expand` on `GET /v2/invoices/{id}`, `GET /v2/invoices/{id}/lineItems` or `GET /v2/invoices/lineItems` to get it as a `provenance` field on each line. ### What changed * The trace shows the inputs, each step in order with its value before and after, and the result * Every value names its source: the subscription interval, the price, the meter or entitlement, the grant, the adjustment, or the line it reduces * Each source keeps a copy of the values the calculation used, so the trace still explains the line after a price, plan or grant changes * The trace ends exactly at the line's amount before tax, and it does not change after the invoice is issued * Grant credit and percentage discount lines have their own trace and name the line they reduce ### What's unaffected * Invoice amounts. The trace explains an amount, it never changes it * Responses that do not ask for `lineProvenance` * Lines calculated before this release report `status: "notRecorded"`. Their traces are not rebuilt See [Invoices](/platform/billing/invoices#see-how-a-line-was-calculated). **September 30, 2026** ## Entitlements whose end date has passed now report `expired` An entitlement whose `activeTo` has passed now has `status: "expired"`. Before, it kept `status: "active"` even though the access check already denied it. ### What changed * The status changes to `expired` within a minute of `activeTo` passing, for every entitlement, including ones you issued yourself * A plan version change ends a dropped feature at the start of the new version, so the `activeTo` of that entitlement is that instant ### What's unaffected * Access decisions. The access check already denied an entitlement from `activeTo` * Invoices for a period that the entitlement covered, even partly, still bill against the entitlement and its grant **September 15, 2026** ## Volume pricing: one rate for the whole period, chosen by total usage A price can now carry a ladder of bands instead of a single rate. Set `model` to `volume` and put the bands in `properties.tiers`. The period's total usage selects one band, and that band's rate applies to every billed unit, so a customer who crosses a boundary re-rates their whole period rather than only the units above it. ### What changed * Metered prices accept `model: "volume"` on create and update, alongside `standard` * Each band carries `upTo` (its inclusive upper bound) and `unitPrice`. The last band carries `upTo: null` and takes everything above the highest bound * The published `PriceProperties` schema now carries the ladder rules: bounds must be positive and strictly ascending, band rates cannot be negative, and both fields are capped at 6 decimal places. The API rejects an unrecognized field in a band rather than ignoring it * The dashboard shows a volume price as a band table and offers a ladder editor on the price create and edit forms ### What's unaffected * Existing `standard` prices are unchanged, and `standard` remains the model to reach for by default * Legacy `dynamic` and `percentage` prices keep billing exactly as before ### Where it surprises people Because one rate applies to every unit, a volume total can fall as usage rises. On a ladder charging \$5.00 up to 100 units and \$3.00 above it, 100 units bill \$500.00 and 101 units bill \$303.00. Check your boundaries against the rates on either side before you publish a ladder. A volume price also cannot be combined with grant discounts, a credit denomination, or a fee. See [Prices](/platform/pricing/prices) for the full model. **August 12, 2026** ## Invoice documents: `pdfUrl` can now point at an authenticated endpoint Invoices are now issued with a Paygentic-rendered PDF, so merchants who do not use a tax provider get an invoice document for the first time. Customers receive it as an email attachment; over the API it is served by `GET /v2/invoices/{id}/pdf`. **Breaking**: `pdfUrl` on the invoice resource may now be a Paygentic URL that requires your API key. Previously every non-null `pdfUrl` was a tax provider's link that any HTTP client could open unauthenticated, so code that puts `pdfUrl` straight into a browser link or fetches it without an `Authorization` header will get a `401`. ### What changed * Invoices that previously had `pdfUrl: null` because no tax provider was configured now carry a link to `GET /v2/invoices/{id}/pdf` * That endpoint requires your API key, like every other API call. The link is stable and does not expire, and no credential is ever embedded in it * A new `pdfSource` field says which kind of link you have: `paygentic` (fetch it with your API key) or `tax_provider` (openable directly). It is `null` when there is no document * For Paygentic-rendered invoices, the customer email carries the document as an attachment rather than a link ### What's unaffected * Invoices whose document comes from a tax provider are unchanged — same link, still directly openable, now labelled `pdfSource: "tax_provider"` * `permalink` is unchanged * Nothing about existing invoices changes retroactively; only invoices issued from this release onward gain a document ### If you relied on the old behaviour Branch on `pdfSource` rather than on the shape of the URL, and send your API key when it is `paygentic`. A hard-coded `` needs to become a server-side fetch that streams the bytes to the customer. If you display documents only for tax-provider invoices today, gate on `pdfSource === "tax_provider"` and nothing changes for you. We plan to serve tax-provider documents through the same authenticated endpoint in a later release, at which point those links change shape too — branching on `pdfSource` now means you will not need to change again. **July 17, 2026** ## Platform * Large amounts on the Prices tab are now displayed with thousands separators for easier reading **July 16, 2026** ## Profitability Dashboard * Removed the redundant status badge from the profitability table and the customer Gross Margin card — the margin percentage already told the same story * "Customers At Risk" on the summary card now reflects margin at or below breakeven, replacing the looser previous threshold ## Bug fixes * Softened merchant logo upload restrictions — square logos up to 4096px, any aspect ratio, and SVGs now upload without being rejected **July 15, 2026** ## Metering * Meter events can now be reported with `externalSubject` — your own customer identifier — instead of, or ahead of, our internal `subject`. Events reported before the matching customer exists are linked automatically once that customer is created, and are still billed normally as long as they fall within the invoicing period * The meter detail page can now group usage by customer, with a breakdown table showing usage share, event counts, and links to each customer's profile and events ## Platform * The Sources tab on a plan's detail page is now only shown to merchants who already use event sources ## Bug fixes * Improved validation on customer address updates **July 13, 2026** ## Outcome-Based Pricing * The plan quick-start wizard now supports outcome-based pricing — charge per delivered outcome (e.g. per resolved support ticket) alongside the existing fixed, usage-based, and hybrid models ## Subscriptions API * New `POST /v0/subscriptions/{id}/reconciliations` endpoint re-syncs a subscription's feature entitlements and metered grants to its plan's current features, with a `dryRun` preview mode ## Bug fixes * Fixed a server error when creating a plan without a linked product — this now returns a clear validation error instead * Fixed a rendering issue on the login page introduced by a recent update **July 8, 2026** ## Platform * Account lockout after 3 failed login attempts within an hour, for added account security **July 6, 2026** ## Grants API * New optional `priority` field on `POST /v1/entitlements/{entitlementId}/grants` to control the order in which grants are consumed — lower priority burns down first * `priority` is now returned on every grant response (create, retrieve, list, and void), so you can confirm the applied value without a follow-up lookup * Handy for correction grants: assign a negative priority so an ad-hoc grant is consumed before the recurring allowance ## Platform * Automatic logout after 5 minutes of inactivity for payments merchants, for added account security * Meter event subject IDs now link directly to the matching customer page ## Bug fixes * Removed a non-functional logo upload from the merchant onboarding flow **July 2, 2026** ## Plan creation: `billingVersion: 0` no longer accepted **Breaking**: `POST /v0/plans` now rejects requests that explicitly pass `billingVersion: 0` with a validation error. New plans can only be created on Standard Billing (`billingVersion: 1`). ### What changed * Passing `billingVersion: 0` returns a validation error — Legacy Billing plans can no longer be created * Omitting `billingVersion` still defaults to `1` (Standard Billing) — no change here * Passing `billingVersion: 1` explicitly is unaffected ### What's unaffected * Existing plans created with `billingVersion: 0` continue to work exactly as before — `billingVersion` cannot be changed after creation, so this is a creation-time restriction only * `PATCH` (update plan) never accepted `billingVersion` and is unaffected ### If you relied on the old default If your integration omitted `billingVersion` expecting Legacy Billing, or explicitly passed `0`, switch to Standard Billing (`billingVersion: 1`, or omit the field). See [Plans](/platform/pricing/plans). **June 28, 2026** ## Invoice refunds * Refund invoices via credit notes, with revenue reporting that accounts for refunded amounts ## Payments * Merchants can now retry an invoice payment directly, with a per-invoice cooldown to prevent duplicate attempts ## Payment methods * New Payment methods section on the customer page to view and manage a customer's saved methods * Customers can no longer remove their last payment method while they have an active subscription ## Entitlements * Filter `GET /v1/entitlements` by external customer ID ## Customer portal * Meter usage now appears as clear usage cards on the customer portal and subscription pages, replacing the raw event list **June 21, 2026** ## Customer portal * Added a payment-required banner so customers can see at a glance when an invoice needs paying * Payment sessions that are completing or still processing no longer show a misleading "Payment Error" **June 14, 2026** ## Metering * Meter event ingestion now accepts an `externalId` on each event, so you can tie events back to your own records (API + SDK) ## Billing * Regenerate the payment link for an invoice at any time * Fee prices can now be created with a quantity of 0 ## Platform * Manage customer notification settings directly in the dashboard **June 7, 2026** ## API * `GET /v1/entitlements` (list) and the single-entitlement endpoint now return consistent response shapes ## Platform * Plan creation no longer shows the legacy billing-version selector — new plans use Standard Billing * Invited team members are now activated automatically on first access * Invoice PDFs are available from the customer portal even before payment **May 31, 2026** ## Webhooks * New `invoice.paid.v0` webhook event fires when an invoice is paid **May 24, 2026** ## Entitlements * Entitlement template changes now propagate to active subscribers, with broader coverage of template fields ## Billing * New `defaultQuantity` on Price sets the default quantity for fee invoice lines (API + SDK) **May 17, 2026** ## Plans * New Advanced Settings and Danger Zone sections on the plan detail page ## Entitlements * Direct-grant-only entitlements can now be configured with `issueAfterReset` set to 0 ## Accounting * Sync issued invoices to Rillet ## Platform * Create costs directly in the dashboard * Revenue, New Plan, and Cost Explorer now consistently use your primary currency * Billable metric creation defaults the aggregation type to SUM * Billable metric JSONPath is validated when you save a metric **May 10, 2026** ## API keys **Breaking**: Creating an API key (`POST /v0/users/{userId}/apikeys`) now requires a `name` in the request body. Update SDK clients to pass a name before upgrading. ## Billing * US merchants can opt in to non-sequential invoice numbers * Invoice list now paginates for large invoice volumes ## Platform * Set auto-charge when creating a subscription, directly in the subscription form * Capture and store a customer's payment method during subscription setup **May 3, 2026** ## Onboarding * New quick-start checklist guides you through the initial setup steps **April 26, 2026** ## Metering * Meter events are now searchable by `externalId` ## Performance * Reduced the number of API calls the dashboard makes, for faster page loads **April 17, 2026** ## Cost Explorer * New Cost Explorer page for analyzing revenue and costs across your customer base * Break down costs by type, customer, or custom dimension * Chart and table views with sorting, pagination, and drill-down navigation * Filter by date range and subject — searchable by customer name ## Raw meter events * New raw events view inside each billable metric — inspect the individual events feeding your usage aggregations * Filter by subject to focus on a specific customer's event stream * Idempotency keys visible directly in the event list ## Entitlements: query at a point in time * New optional `at` parameter on `GET /v1/entitlements` and `GET /v1/entitlements/{id}` * Pass an ISO 8601 timestamp to check balance, access, and period bounds at any point in time * TypeScript and Python SDKs updated ## Entitlements: automatic grant reinitialization * When a plan's entitlement template is updated (rollover policy, expiry, reset behaviour), active subscribers' grants are automatically reinitialized at the next billing period boundary * Rolled-over balance is preserved — a one-time seed grant carries existing balance forward ## Grant discounts on invoices * When `grantDiscountEnabled` is set on a price, unused grant balance now appears as a dedicated discount line item on the invoice * Previously, grant discounts were applied implicitly; they are now visible and auditable ## Platform * Invoice review step added when creating in-advance subscriptions — see line items and totals before confirming * Revamped onboarding wizard with improved layout, radio card selection, and clearer step flow * Filter customers directly from the customers list by name or email * Improved metered entitlements table in the customer portal — clearer layout and consistent styling * Customer portal hides legacy usage history for v1 subscriptions (line-item billing shows invoice data instead) **April 2026** ## Migration: `billingInterval` → `billingCadence` Plans now use `billingCadence` (ISO 8601 duration) as the primary billing period field. `billingInterval` is deprecated in responses and will be removed in a future version. ### Mapping | Old `billingInterval` | New `billingCadence` | | - | - | | `"monthly"` | `"P1M"` | | `"quarterly"` | `"P3M"` | | `"yearly"` | `"P1Y"` | ### Input (create/update plan) * New: send `billingCadence: "P3M"` for quarterly billing * The old `billingInterval` field is still accepted for backwards compatibility * When both are provided, `billingCadence` takes precedence ### Output (plan response) * Both fields are present in responses during the deprecation window * `billingCadence` is the source of truth (ISO 8601 duration) * `billingInterval` is derived from `billingCadence` and marked **deprecated** ### SDK update Update any code that reads or writes `billingInterval` to use `billingCadence` instead. The SDK will emit deprecation warnings on the old field. **March 18, 2026** ## Revenue analytics * New revenue dashboard for billing v1 — visualize revenue by hour, day, or as a cumulative total * Drill into revenue by customer or subscription, and track financials from a single consolidated view ## Payment links * Payment links can now be created and managed directly from the dashboard * Supports line items, customer assignment, and status tracking ## Payments API * New Payments API to process payments programmatically * Subscribe to payment lifecycle events via webhooks ## Grants API * Manage grants mid-cycle: create, list, retrieve, and void grants on any entitlement via REST * `POST /v1/entitlements/{entitlementId}/grants` * `GET /v1/entitlements/{entitlementId}/grants` * `DELETE /v1/entitlements/{entitlementId}/grants/{grantId}` * Grant purchase and direct creation are now available in the public API and SDK ## Webhooks * New `invoice.issued.v0` webhook event fires when an invoice is issued ## API * New endpoint to manually create line items on an invoice * `listCustomers` now supports filtering by name and email ## Platform * Duplicate any plan (including all its prices) from the plan actions menu * New usage onboarding flow with a metric wizard for usage-based plan setup * Customers list now paginates for large customer counts **March 1, 2026** ## Python SDK * Official [Paygentic Python SDK](https://pypi.org/project/paygentic/) now available, powered by Speakeasy * Full parity with the TypeScript SDK for all API interactions ## Metered entitlements * Metered entitlements now supported — charge customers based on actual usage of features * Metered line items automatically collected and synced to invoices on your billing schedule * New `GET /v2/invoices/lineItems` endpoint to retrieve detailed line item breakdowns per invoice * SDK updated to support metered entitlements and subscription-scoped entitlement listing ## API enhancements ### Currencies * Added support for **GBP** and **AUD** as merchant billing currencies ### Customers * New endpoint to delete customers — historical data is preserved ### Billing metrics * Billable metric meter endpoint now available in the public API and SDK — query real-time usage data for a given customer and metric ### Entitlements * Filter entitlement checks by subscription when a customer has multiple active subscriptions ### Email notifications * Custom email routing: configure a custom "from" address for billing notification emails sent to your customers * Invoice and portal links in emails now expire after 7 days for security ### Plans * Plans now include a `billingVersion` field distinguishing legacy and line-item-based billing ## Customer portal * Customers can now add and remove their own payment methods directly in the portal * New entitlements view showing customers their active features and usage entitlements * Address fields on the customer creation form now support autocompletion ## Platform updates * "Show exact balance" toggle replaces nano-unit labels for clearer wallet balance display * Streamlined merchant onboarding — the consumer/merchant type selection step has been removed for a simpler signup flow ## Bug fixes * Fixed metered line items to correctly apply payment term `in_arrears` * Fixed sandbox invite links to preserve the return URL after login * Standardized required field indicators across all platform forms **February 13, 2026** ## Multi-currency support * Notifications for invoices, payments, and subscriptions now display amounts in the merchant's configured currency * Payment sessions updated with multi-currency support * Tax provider contact details now kept automatically in sync ## Platform updates ### Customer portal * Refreshed customer portal UI * Enhanced wallet balance display with a new balance header ### Bug fixes * Fixed inconsistent address autocomplete behavior ## SDK * Official [Paygentic TypeScript SDK](https://www.npmjs.com/package/@paygentic/sdk) now available (beta) with automated publishing **January 5-27, 2026** ## Major release: features and entitlements ### Feature management * Define features that can be gated for your customers (e.g., "SSO Access", "Premium Support") * New Feature Management UI to create and manage features directly in the dashboard * Link features to prices when creating or editing pricing plans * Automatic entitlement provisioning when customers subscribe to plans with linked features ### Entitlement access API * New public API endpoint (`/v1/entitlements`) to check if a customer has access to a specific feature * Support for static (config-based) and boolean (on/off) feature types ## API enhancements ### Webhooks * New `subscription.renewed.v0` webhook event when subscriptions enter a new billing period ### Customer management * Customer name and email now editable directly from the customer detail page * Fee management endpoints added to public API documentation ### Payments * Expired payment session links now automatically regenerate with a new email sent to customers * Added Australia to merchant eligible countries ## Email notifications * Email notification when invoice is **issued** (for manual payment invoices) * Email notification when invoice is **paid** with links to invoice and receipt * Email reminder before subscription renewal ## Bug fixes * Fixed micro-pricing truncation in percentage-based prices * Fixed payment retry flow when initial payment attempt fails * Fixed fee dropdown showing fees from other products **October 21-27, 2025** ## API improvements ### Enhanced invoice management * Added `merchantId` field to all invoice V2 endpoint responses for better multi-merchant support * Improved manual Event Source sync capabilities with rate limiting for better integration control ### Security and environment management * API keys now include environment prefixes for clearer identification across different environments * Enhanced security for API key management ## Platform updates ### User experience improvements * Added pagination to subscriptions table for better performance with large datasets * Fixed return URL configuration for payment topups * Minor bug fixes ### Environment awareness * New banner displays current environment (sandbox, staging, production) for clearer context * Added quick navigation links to sandbox environment **October 14-20, 2025** ## Major release: Tax integration ### Paygentic Tax * Complete tax automation with Paygentic Tax integration * Automatic tax calculation and reporting * Support for international tax compliance ## API enhancements ### Customer management * Enabled tax ID and tax rate updates for merchant-managed customers * Added address modification capabilities for merchant-managed consumers * Enhanced subscription and customer ID tracking in source event responses ### Data integrity * Prevented duplicate prices per billable metric in plans * Improved conflict detection for existing subscriptions ## Platform features ### Payment methods portal * New self-service payment methods management in customer portal * Improved payment method handling and invoice card filtering * Enhanced off-session payment flow for automatic billing ## Documentation updates * Comprehensive documentation for payment terms * Detailed metric modes explanation * Updated billing guides # Errors Source: https://docs.paygentic.io/errors The shape of an error response, how to tell errors apart, and the request id to send to support. When a request fails, the API returns a `4xx` or `5xx` status and a JSON body. Every response, failed or not, also has a `request-id` header. ## Error body ```json theme={null} { "error": "bad_request", "message": "A committed billing period would change", "code": "INTERVAL_PERIOD_ALREADY_BILLED", "details": { "priceKey": "pk_m4n5o6p7q8r9s0t1" }, "requestId": "105445aa7843bc8bf206b12000100000" } ``` | Field | Meaning | | - | - | | `error` | The category of the error, such as `bad_request`, `forbidden` or `not_found`. It follows the HTTP status. | | `message` | A description for people. Its text can change, so do not parse it in code. | | `code` | Optional. A stable code for one failure, such as `TAX_NOT_ENABLED`. Check this field in code. | | `details` | Optional. Structured data about the failure. | | `requestId` | The id of this request. It has the same value as the `request-id` header. | A request that fails schema validation returns `"error": "validation_error"` and adds an `errors` array. Each entry names one `field` and gives its `message`. ## Request id The `request-id` header identifies one request in the Paygentic logs. JSON error bodies also have it in `requestId`. When you contact [support@paygentic.io](mailto:support@paygentic.io) about a failed request, include the request id. Support can then find the exact request without a search by time and account. Log the `request-id` header with your own error logs. ## Retrying A `429` or `503` response has a `retry-after` header that says how many seconds to wait before you send the request again. See [Rate limits](/rate-limits) for how to retry. ## Related pages * [Rate limits](/rate-limits): the limits and the `429` response * [Authentication](/authentication): how to send your API key # Environments Source: https://docs.paygentic.io/getting-started/environments Use sandbox and live environments to test and deploy your Paygentic integration safely Paygentic provides two separate environments to support your development workflow: **Sandbox** and **Live**. Use them to test your integration thoroughly before going to production. ## Environment overview > [card] Sandbox Environment > > Test your integration without affecting real data or processing actual payments > [card] Live Environment > > Production environment for real customers and actual payment processing ## Sandbox environment Sandbox runs the same billing engine and the same API as live, on separate data. Use it to build and test your integration without moving real money. ### Accessing sandbox * **Platform Dashboard**: [https://platform.sandbox.paygentic.io](https://platform.sandbox.paygentic.io) * **API Base URL**: `https://api.sandbox.paygentic.io` ### Key features * **Same login credentials**: Use the same email and password as your live environment account * **Isolated data**: All data is completely separated from the live environment * **Unique IDs**: All resource IDs (customers, subscriptions, products, etc.) are unique to sandbox * **Same API**: Every endpoint in live is also in sandbox, served from the same codebase. See [What differs from live](#what-differs-from-live) for the exceptions * **Test API keys**: API keys are prefixed with `sk_test_` and only work in sandbox > [!NOTE] > > While you use the same login credentials for both environments, all data, API keys, and resource IDs are completely separate between sandbox and live. ### What differs from live * **No real money moves.** Payment providers run in their test modes. Card payments and refunds complete without a transfer of funds. * **Sandbox-only test controls.** The dashboard adds controls to advance payment onboarding and simulate payment events without a real provider account. The API adds [test clocks](#simulating-time) and a [data reset](#resetting-sandbox-data). None of these exist in live. * **Sandbox tax calculation has a quota.** Each sandbox account can produce a limited number of tax documents. When the quota is used up, invoice creation fails with a `400` error until support resets the quota. * **Data never crosses over.** Products, plans, customers, usage and webhooks you create in sandbox do not exist in live. See [Data synchronization](#data-synchronization). ### When to use sandbox Use the sandbox environment to: * Test your integration during development * Validate new features before deploying to production * Experiment with pricing models and configurations * Train team members on the platform * Debug issues without affecting real customers * Run automated integration tests > [!WARNING] > > **Test data only**: The sandbox environment is exclusively for testing purposes. Never add real user data, personal information, or production customer data to sandbox. Always use synthetic test data only. ### Simulating time A test clock replaces the current time for the subscriptions attached to it. Use one to test renewals, resets and invoices without waiting, or to build months of usage and invoice history. 1. Create a clock with `POST /v0/testClocks`. `currentTime` can be in the past, so a subscription on the clock can start on a past date and bill its periods as the clock advances. 2. Create subscriptions with `testClockId` set to the clock's ID. The clock's time is "now" for those subscriptions: their start, their billing, and their allowances. 3. Send usage with `timestamp` set to the clock's current time. 4. Advance the clock with `PATCH /v0/testClocks/{id}`, with either `advanceBy` (an ISO 8601 duration, such as `"P1M"`) or a later `currentTime`. 5. Repeat steps 3 and 4 for each period you want to simulate. ```bash Advance a test clock by one month theme={null} curl -X PATCH "https://api.sandbox.paygentic.io/v0/testClocks/tc_a1b2c3d4e5f6g7h8" \ -H "Authorization: Bearer sk_test_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "advanceBy": "P1M" }' ``` Rules to know: * **A clock moves forward only**, and at most 1 year per call. A step back, or a step of more than 1 year, returns `400 Bad Request`. To move further, advance more than once. * **Usage counts once the clock moves past it.** Usage dated at the clock's current time doesn't count yet, so advance the clock before you read a balance or an invoice. Paygentic processes usage events in the background, so a balance can take a short time to include them. * **Usage dated before an allowance starts never counts.** Send usage dated at the clock's time, not earlier. See [Usage dated in the past](/platform/billing/metered-entitlements#usage-dated-in-the-past). * **Invoices follow in the background.** After an advance, Paygentic closes the periods the clock has passed. An invoice can take a short time to appear. ### Resetting sandbox data `POST /v0/merchants/{merchantId}/reset` deletes sandbox data so you can start again. Use it to fix a mistake in a test setup, such as a paid invoice you can't undo, instead of contacting support. ```bash Delete every customer, keep the catalog theme={null} curl -X POST "https://api.sandbox.paygentic.io/v0/merchants/org_abc123/reset" \ -H "Authorization: Bearer sk_test_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "scope": "merchant", "keepCatalog": true }' ``` | Body | What it deletes | | - | - | | `{ "scope": "merchant", "keepCatalog": true }` | Every customer and everything attached to them: subscriptions, invoices and their stored PDFs, payments, entitlements, grants, orders, usage events and test clocks. If a Quaderno tax account is connected, every document and contact in its sandbox account too. The catalog (products, plans, prices, fees, features and billable metrics) stays. | | `{ "scope": "merchant", "keepCatalog": false }` | All of the above, and the catalog too. | | `{ "scope": "customer", "customerId": "cus_..." }` | One customer and everything attached to it, including its stored invoice PDFs. Test clocks and Quaderno tax documents stay. | * Nothing is deleted by default: with `scope: "merchant"`, `keepCatalog` is required. Your account configuration is always kept. * The reset exists in sandbox only. Only an organization owner or admin can call it. An API key has the permissions of the user it belongs to. * Send no usage events while a reset runs. An event that arrives during the reset can survive it. * `204 No Content` means every delete is done or scheduled. Usage events finish deleting in the background, so wait a short time before you create new data. * `502 Bad Gateway` means the reset is incomplete. Call it again with the same body to finish it. Calling it again is always safe. ## Live environment The live environment is your production environment where real transactions occur. ### Accessing live * **Platform Dashboard**: [https://platform.paygentic.io](https://platform.paygentic.io) * **API Base URL**: `https://api.paygentic.io` ### Key features * **Production data**: Real customers and actual payment processing * **Live API keys**: API keys are prefixed with `sk_live_` and only work in live * **Real payments**: All transactions process actual payments ## API keys and environments API keys are environment-specific and identified by their prefix: | Environment | API Key Prefix | Example | | - | - | - | | Sandbox | `sk_test_` | `sk_test_abc123...` | | Live | `sk_live_` | `sk_live_xyz789...` | ### Key restrictions * **Sandbox keys** (`sk_test_`) can only be used with `https://api.sandbox.paygentic.io` * **Live keys** (`sk_live_`) can only be used with `https://api.paygentic.io` * Using a key with the wrong environment will result in authentication errors ```bash Sandbox API Request theme={null} curl -H "Authorization: Bearer sk_test_YOUR_API_KEY" \ https://api.sandbox.paygentic.io/v0/products ``` ```bash Live API Request theme={null} curl -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ https://api.paygentic.io/v0/products ``` ## Best practices ### Development workflow 1. **Develop in sandbox**: Build and test your integration in sandbox first 2. **Use environment variables**: Store API keys and base URLs in environment variables 3. **Automated testing**: Run integration tests against sandbox in your CI/CD pipeline 4. **Validate changes**: Test all changes in sandbox before deploying to live 5. **Monitor both environments**: Set up monitoring for both environments ### Security considerations * Never commit API keys to version control * Use separate API keys for each environment * Rotate keys regularly in both environments * Restrict live API keys to production servers only * Use sandbox keys for local development and testing ## Switching between environments To switch between environments: 1. **Update API key**: Use the appropriate `sk_test_` or `sk_live_` key 2. **Update base URL**: Point to the correct API endpoint 3. **Verify environment**: Check that you're working with the intended environment before making changes > [!TIP] > > Add environment indicators to your application's admin panel or logs to clearly show which environment you're working with. ## Data synchronization > [!WARNING] > > Data is **not** synchronized between sandbox and live environments. Each environment maintains its own independent database. When moving from sandbox to live: * You'll need to recreate products, plans, and pricing configurations in live * Customer data must be created fresh in live * Usage events and billing history are separate in each environment * API keys and webhooks must be configured separately > [!WARNING] > > **Important**: Never copy real customer data or personal information from live to sandbox. Sandbox should only contain synthetic test data. Similarly, never use production customer data for testing purposes. ## Troubleshooting ### Wrong API key for environment ```json Error Response theme={null} { "error": "Unauthorized", "message": "Invalid API key" } ``` **Solution**: Verify you're using the correct API key prefix (`sk_test_` for sandbox, `sk_live_` for live) and the matching API base URL. ### Data not found in new environment If you're switching from sandbox to live and can't find your data, remember that environments are completely isolated. You need to recreate your configuration in the new environment. ### Testing payments in sandbox Sandbox environment uses test payment credentials that simulate real payment flows without processing actual charges. Contact [support@paygentic.io](mailto:support@paygentic.io) for test payment credentials. # Introduction Source: https://docs.paygentic.io/getting-started/introduction Infrastructure for consumption-based monetization Paygentic is infrastructure for consumption-based monetization. Built for software where costs scale with usage — LLMs, data processing, compute resources — not user seats. ## Why Paygentic exists Software economics changed. Fixed monthly subscriptions break when your costs vary per request. When running GPT-4 costs \$0.03 per thousand tokens, charging \$20/month regardless of usage creates unsustainable unit economics. The technical challenges multiply: **Metering at scale** Tracking millions of events per second — tokens processed, queries executed, bytes stored — without impacting application performance. **Pricing flexibility** Supporting per-token, per-query, per-gigabyte, and hybrid models simultaneously across different customer segments, with both upfront and usage-based charges in the same plan. **Payment collection** Collecting upfront fees before a subscription activates, then billing metered usage at period end — all through a single integration. **Subscription lifecycle** Managing activations, renewals, upgrades, and cancellations with correct proration and invoicing at every transition. ## Architecture philosophy Paygentic unifies metering, pricing, invoicing, and payments into a single pipeline. You define what to measure, how to price it, and when to bill — Paygentic handles the rest. This design eliminates entire categories of problems: * No reconciliation between usage logs and billing records * No separate integration points for metering vs invoicing vs payments * No manual invoice generation or payment chasing * No custom logic to gate activation on upfront payment ## Core primitives **Products and metrics** Define services and measurable units. An LLM service tracks input tokens, output tokens, and fine-tuning hours as distinct billable metrics. **Plans and prices** Package pricing strategies. Supported rates include standard prices and percentage-style multipliers or revenue share — a unit price of `0.1` charges 10% of the metered value. Each price uses a payment term: `in_advance` for upfront charges or `in_arrears` for metered usage. Plans bundle prices into subscribable offerings with a billing interval and currency. **Subscriptions and invoices** Connect customers to plans. When a subscription includes upfront charges, Paygentic generates an initial invoice the customer must pay before the subscription activates. Paygentic then generates subsequent invoices automatically at each billing period. **Meter events** Report consumption as it occurs. Each event carries a `type`, the customer in `subject` (the Paygentic customer ID) or `externalSubject` (your own ID), a `source`, and `data` with the values to measure. An event whose `type` matches a billable metric counts as usage. One whose `type` matches a cost metric records what serving the customer cost you. Paygentic returns `202 Accepted` for an event that is well-formed, names a customer with `subject` or `externalSubject`, and has a `type` that matches a billable metric or cost metric. See [Error handling](/platform/metering/meter-events#error-handling) for the other responses. Send an `idempotencyKey` with every event you might retry. On a 5xx response, retry with the same `idempotencyKey`, and wait the `Retry-After` time on a `503`. On a `429`, follow [Rate limits](/rate-limits). Paygentic aggregates usage events for invoicing at period end. **Features and entitlements** Grant access to capabilities through your pricing. Attach entitlements to prices with quota limits, reset periods, and rollover behavior. When a customer subscribes, Paygentic provisions entitlements automatically. ## Implementation patterns **AI services** * Input/output token differentiation * Model-specific pricing tiers * Platform access fees (in advance) plus token usage (in arrears) * Fine-tuning compute billing **Data platforms** * Storage per GB-month * Query compute seconds * Egress bandwidth charges * Reserved vs on-demand pricing **Developer tools** * Build minutes * Deployment slots * Bandwidth consumption * Concurrent execution limits ## Technical integration Single API surface. Define your monetization model programmatically: 1. Create products and billable metrics 2. Configure prices and plans 3. Onboard customers and create subscriptions 4. Report meter events 5. Paygentic generates and collects invoices automatically No payment gateway complexity. No manual reconciliation. ## Design principles **Real-time by default.** Meter events are ingested and aggregated in real time. Invoicing and settlement follow automatically. **Precision matters.** Atomic unit accounting enables sub-cent transactions at scale. **Idempotent everything.** Network failures don't create duplicate charges or lost events. **Geographic distribution.** Edge processing for low-latency event ingestion globally. ## Getting started Follow the [Quickstart](/getting-started/quickstart) for a hands-on walkthrough. Then explore [Pricing](/platform/pricing/overview) to model your monetization strategy. # Quickstart Source: https://docs.paygentic.io/getting-started/quickstart Four steps from zero to billing Four steps from zero to billing. This guide walks through the essential Paygentic setup. A sandbox environment is available at [platform.sandbox.paygentic.io](https://platform.sandbox.paygentic.io) for risk-free testing with identical credentials. > [!TIP] > > Using [Claude Code](https://www.anthropic.com/claude-code)? Install the [Paygentic skills plugin](/platform/building-with-llms#claude-code-skills) first so Claude can generate the integration code as you read along. **1. Define a product** A product represents the service you sell. Give it a clear name (e.g., "LLM Inference Engine", "Vision AI Platform"), a description, and associate it with your merchant account. You can create products through the API or the dashboard. See [Products](/platform/pricing/products) for the full reference. **2. Set up pricing** With a product in place, configure three things: what you measure, how you price it, and how you package it. **Billable metrics** define the units you track — input tokens, output tokens, GPU minutes, API calls, or anything else your service meters. **Prices** attach a standard pricing model to each metric — including percentage-style multipliers and revenue share (a unit price of `0.1` charges 10% of the metered value). Each price also carries a payment term: `in_advance` for upfront charges like platform fees, or `in_arrears` for metered usage billed at period end. **Plans** bundle your prices into a subscribable offering. Every plan has a [billing cadence](/platform/pricing/plans#billing-cadence) (monthly, quarterly, or yearly), a currency, and a set of prices. See [Billable Metrics](/platform/pricing/billable-metrics), [Prices](/platform/pricing/prices), and [Plans](/platform/pricing/plans) for details on each. **3. Create a customer and subscribe** Create a customer for each organization you bill, then create a subscription to connect that customer to a plan. If the plan includes in-advance charges, Paygentic generates an initial invoice covering the first period's upfront fees. The subscription activates once that invoice is paid. If the plan has no upfront fees, there is nothing to collect and the subscription activates immediately. See [Customer Lifecycle](/platform/billing/customer-lifecycle) for the full activation flow. **4. Report usage** Once the subscription is active, send meter events to record consumption. Send each event to `POST /v0/events` with `type` (the billable metric's `eventType`), `subject` (the customer ID), `source` (where the event came from) and `data` (the values to measure, such as a quantity). If you don't have the Paygentic customer ID, send your own ID in `externalSubject` instead of `subject`. This example assumes a billable metric whose `eventType` is `ai.inference` and whose `valueProperty` is `$.tokens`. Without a matching metric, the call returns `422`. ```json theme={null} { "type": "ai.inference", "source": "https://api.myapp.com", "subject": "cus_abc123", "data": { "tokens": 1500 }, "idempotencyKey": "req_xyz789" } ``` Paygentic returns `202 Accepted` for an event that is well-formed, names a customer with `subject` or `externalSubject`, and has a `type` that matches a billable metric or cost metric. See [Error handling](/platform/metering/meter-events#error-handling) for the other responses. Send an `idempotencyKey` with every event you might retry. On a 5xx response, retry with the same `idempotencyKey`, and wait the `Retry-After` time on a `503`. On a `429`, follow [Rate limits](/rate-limits). See [Meter Events](/platform/metering/meter-events) for the event schema and examples. Setup complete. Continue with the [Pricing Overview](/platform/pricing/overview) for a deeper look at how products, metrics, prices, and plans fit together. # External Mappings Source: https://docs.paygentic.io/integrations/external-mappings Map records across external systems with the Item and ExternalReference resources Paygentic often sits between external systems — a CRM, an ERP, a data warehouse, or any other. It needs a stable place to record "this external record is the same thing as that one." Two thin, billing-decoupled resources own that translation: the **`Item`** and the **`ExternalReference`**. ## Why these resources exist Mapping between external systems is a pure translation — it never touches the billing engine. Rather than overload the billing `Product` with integration concerns, Paygentic models the mapping anchor as its own resource. The `Item` is the canonical "thing you sell"; the `ExternalReference` records each link from an `Item` to a record in an external system. The `Item` is **CRM/ERP agnostic** — it knows nothing about which external systems map to it. All of that lives on its `ExternalReference` rows, where `provider` is just a lowercase identifier. A common use case is bridging an upstream CRM such as Salesforce to a downstream ERP such as NetSuite. The resources make no assumption about provider, direction, or authority — those are conventions a consumer layers on top. > [!NOTE] > > The full design rationale (including the comparison to Orb's model and the variant analysis) lives in the [Item Resource — Design Rationale](https://linear.app/paygentic/document/item-resource-design-rationale-brainstorm-37bfbfc2fd3d) document on PAYG-1142. ## The Item An `Item` is intentionally thin — `id`, `merchantId`, `name`, and `metadata`. It carries no pricing, plan, currency, or metering, and it is independent of the billing `Product`. ```bash theme={null} curl -X POST https://api.paygentic.io/v0/items \ -H "Authorization: Bearer $PAYGENTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "org_…", "name": "Tines Enterprise License" }' ``` You can create an `Item` with just a name and attach external references later, in any order. ## The ExternalReference An `ExternalReference` links an entity to its identifier in an external system. For mapping work the `entityType` is always `item`, and `provider` is a lowercase identifier such as `salesforce` or `netsuite`. ```bash theme={null} curl -X POST https://api.paygentic.io/v0/externalReferences \ -H "Authorization: Bearer $PAYGENTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "merchantId": "org_…", "entityType": "item", "entityId": "itm_…", "provider": "netsuite", "externalId": "1234", "externalLabel": "Cloud revenue" }' ``` The `entityId` must resolve to a live `Item` in the same merchant. ### Multiple references per provider An `Item` may carry several references for the same provider. For example, aliases for renamed or legacy codes that all point at the same `Item`, or several valid downstream posting targets. Additional references beyond the primary are non-primary aliases (see below). A consumer selects the specific target it needs at the point of use. ### isPrimary vs isDefault Two independent boolean flags express two different guarantees: * **`isPrimary`** — at most one *claiming* reference per `(merchant, provider, externalId)`. This is the deduplication guarantee: a claimed code resolves back to exactly one `Item`. Additional unclaimed references with the same code are allowed as aliases, which is what lets several items share a ledger account. Omitting it claims the code; pass `false` for a code that is only ever sent outward. It cannot be cleared once set — claim the code on the item it should resolve to instead, which moves the claim in one write. * **`isDefault`** — at most one *designated* code per `(merchant, entityType, entityId, provider)`: the one sent when a consumer needs a single answer. Omitting it designates the entity's first code for that provider, so an entity with one code needs no further action, and it cannot be cleared — designate another of the entity's codes, which moves the designation. Neither carries a schema default any more. Omission has to stay distinguishable from `false`, because both flags resolve differently when unstated, and a generated client materialises a declared default into every request body — which is how the designation silently stopped happening for one dashboard release. ## Resolution Resolve an external code to its `Item`(s) by listing with the `provider` + `externalId` filter (you must supply both together). Resolution returns **every** live `Item` mapped to that `(provider, externalId)` — the canonical primary plus any non-primary aliases. Resolution returns the primary `Item` **first**; its matching reference's `isPrimary: true` identifies it unambiguously (the partial-unique index guarantees **at most one** primary per code). An unknown code returns an empty list rather than an error. Callers that only want the canonical owner take the first result; callers reconciling renamed or legacy codes get the full alias set. ```bash theme={null} curl "https://api.paygentic.io/v0/items?merchantId=org_…&provider=salesforce&externalId=SKU_A" \ -H "Authorization: Bearer $PAYGENTIC_API_KEY" ``` Fetching an `Item` returns its live external references in the `externalReferences` array. The `Item` itself reports no provider-specific lifecycle state. The consumer derives any gating (for example, "is this mapped to a downstream system yet?") from the presence of the relevant references. There is no hard stop at import time; an `Item` that carries only inbound references is still valid and simply has no downstream reference attached yet. See the [API Reference](/openapi.json) for the full request and response schemas. # Monocle Source: https://docs.paygentic.io/integrations/monocle Meter and monetize AI workloads instrumented with Monocle [Monocle](https://github.com/monocle2ai/monocle) ships with a Paygentic span exporter that streams inference traces into your Paygentic account as CloudEvents. Once configured, Monocle's traces feed your billable metrics directly — no separate instrumentation for billing. This guide covers the Paygentic-side setup. It assumes you already have Monocle installed and instrumenting your application. ## Before you begin * An application instrumented with Monocle via `setup_monocle_telemetry(...)` * A [Paygentic account](https://platform.paygentic.io) (or [sandbox account](/getting-started/environments) for testing) * An [API key](/api-keys) with `events:create` permission ## Step 1: Define a product and billable metric In the Paygentic dashboard, create a product (for example, "Monocle Agent") and a [billable metric](/platform/pricing/billable-metrics) that matches the Monocle span you want to bill on. The Paygentic exporter derives the event `type` from the span's `entity.1.type` attribute, prefixed with `ai.`. For example, an OpenAI chat completion (`entity.1.type = "inference.openai"`) arrives at Paygentic with `type = "ai.inference.openai"`. Map Monocle spans to billable-metric fields as follows: | Field | Value for Monocle | Example | | - | - | - | | `eventType` | `ai.` + the Monocle entity type | `ai.inference.openai` | | `valueProperty` | JSONPath into the span's metadata event | `$.total_tokens` | | `groupBy` | Optional dimensions you care about | `{ "model": "$.model_name" }` | Create one billable metric per provider you want to bill on. Paygentic rejects an event with `422` and the error `invalid_event_type` when its type matches no billable metric and no cost metric. The exporter then stops sending that event type for an hour. > [!NOTE] > > When you use a framework like LangChain or LlamaIndex, the event type still reflects the underlying provider. A LangChain `ChatOpenAI` call emits `ai.inference.openai`, a `ChatAnthropic` call emits `ai.inference.anthropic`, and so on. Unknown or unmapped LLM clients fall back to `ai.inference.generic`. The `data` payload contains the attributes from the span's `metadata` event (plus `span_id`, `trace_id`, and `name`). Common metadata fields across Monocle's provider integrations include `total_tokens`, `completion_tokens`, `prompt_tokens`, and `model_name`. See [Meter Events](/platform/metering/meter-events) for the full list of aggregation options and JSONPath rules. > [!NOTE] > > Monocle spans can also feed a [cost metric](/platform/metering/cost-tracking) alongside your billable metric, so the same event drives both customer billing and internal margin tracking. ## Step 2: Enable the Paygentic exporter Configure the exporter via environment variables: ```bash theme={null} export PAYGENTIC_API_KEY=sk_live_YOUR_API_KEY ``` Sandbox keys are prefixed `sk_test_` and live keys `sk_live_`. When targeting the sandbox, also set `PAYGENTIC_SANDBOX=true` so events are routed to `api.sandbox.paygentic.io`. See [Environments](/getting-started/environments) for details. Then add the `paygentic` exporter to your Monocle setup call: ```python theme={null} from monocle_apptrace import setup_monocle_telemetry setup_monocle_telemetry( workflow_name="my-app", monocle_exporters_list="paygentic", ) ``` Event data should now flow into the **Meters** section of the Paygentic dashboard. Use this view to confirm that events arrive. The Meters view does not show if the usage is billed — Step 3 makes sure it is. > [!NOTE] > > By default the exporter only exports `inference` spans — other Monocle span types are filtered out. The event `source` field defaults to `"monocle"`; override it per-app with `PAYGENTIC_SOURCE=my-app`. ## Step 3: Tag usage with the customer ID Paygentic bills usage by customer. The exporter sets each event's `subject` from a Monocle trace scope, so set the `customerId` scope to the Paygentic customer ID (`cus_...`) that you get when you create the customer. Create a customer, subscribe them to a plan with a price on your Monocle metric, then tag traces with the customer ID before your instrumented workload runs: ```python theme={null} from monocle_apptrace import monocle_trace_scope with monocle_trace_scope("customerId", "cus_demo_123"): # your instrumented workload ... ``` > [!WARNING] > > Do not set a `subscriptionId` scope. The exporter checks `subscriptionId` before `customerId` and sends the subscription ID as the event's `subject`. Paygentic stores those events and shows them in the Meters view, but never invoices them. Use the Paygentic customer ID, not your own customer identifier. The exporter sends only `subject`, so it cannot use the [`externalSubject` lookup](/platform/metering/meter-events#reporting-with-your-own-customer-id-externalsubject). If neither scope is set on the span, the exporter drops the event. See [Customer Lifecycle](/platform/billing/customer-lifecycle) for the full subscription activation flow. ## Troubleshooting * **Events aren't showing up in the Meters view.** Confirm your billable metric's `eventType` matches the `ai.`-prefixed type the exporter emits (e.g. `ai.inference.openai`, not `inference.openai`). Paygentic rejects an unknown `type` with `422`, and the exporter then stops sending that type for an hour. * **`No subscriptionId or customerId scope set on span` in application logs.** The span has no `customerId` scope, so the exporter drops the event. Wrap the traced call in `monocle_trace_scope("customerId", ...)`. * **Usage shows in the Meters view but not on the invoice.** The event's `subject` is not a Paygentic customer ID. Most often a `subscriptionId` scope is set on the span. Remove it and tag with `customerId` instead. Paygentic does not re-link events that are already stored. * **Sandbox key with live endpoint (or vice versa).** Set `PAYGENTIC_SANDBOX=true` when using an `sk_test_` key. ## Next steps * [Billable Metrics](/platform/pricing/billable-metrics) — pricing models and aggregation options for metered usage * [Cost Tracking](/platform/metering/cost-tracking) — track provider costs alongside customer billing * [Customer Lifecycle](/platform/billing/customer-lifecycle) — how subscriptions activate and renew # Cookie Policy Source: https://docs.paygentic.io/legal/cookie-policy How Paygentic uses cookies and similar technologies on its website **Last Updated:** 16 December 2025 This Cookie Policy explains how Paygentic, Inc. ("**Paygentic**", "**we**", "**us**", or "**our**") uses cookies and similar technologies on its website at docs.paygentic.io/introduction (the "**Website**"). It explains what these technologies are and why we use them, as well as your rights to control our use of them. This Cookie Policy should be read in conjunction with our [Privacy Policy](/legal/privacy-policy). If you have any questions or concerns about the Cookie Policy or its implementation, please contact us at **[support@paygentic.io](mailto:support@paygentic.io)** or as otherwise described in our [Privacy Policy](/legal/privacy-policy). *** ## 1. What are cookies and similar technologies? **Cookies**. A cookie is a text file containing a string of characters that is sent to your device when you visit a website. When you visit the site again, the cookie allows that site to recognize your browser. Cookies may store user preferences and other information. Cookies set by the website owner (in this case, Paygentic) are called "first party cookies." Cookies set by parties other than the website owner are called "third party cookies." Third party cookies enable third party features or functionality to be provided on or through the Website (e.g., analytics). The parties that set these third party cookies can recognise your computer both when it visits the Website in question and also when it visits certain other websites. This Cookie Policy refers to all these technologies collectively as "**cookies**." *** ## 2. Why do we use cookies? We use cookies for several reasons. Some cookies are required for technical reasons in order for our Website to operate, and we refer to these as "strictly necessary" cookies. Other cookies also enable us to track our users to enhance the experience on our Website and services more broadly. For example, our cookies may help to distinguish you from other users of our services for the purposes of helping you navigate between pages efficiently, remembering your preferences, enabling functionality and helping us understand activity and patterns. Third parties set cookies on our Website for analytics and other purposes. This is described in more detail below. *** ## 3. How do we use cookies? We, our service providers, automatically log information about an individual's interactions with our Website, such as: * **Device information**, such as computer or mobile device operating system type and version, manufacturer and model, browser type, screen resolution, RAM and disk size, CPU usage, device type (e.g., phone, tablet), IP address, language settings, mobile device carrier, radio/network information (e.g., WiFi, LTE, 5G), and general location information such as city, state, or geographic area. * **Online activity information**, such as pages or screens viewed, how long individuals spend on a page or screen, the website they visited before browsing to our Website, navigation paths between pages or screens, information about activity on a page or screen, access times and duration of access, and whether individuals open our marketing emails or click links within them. We use both persistent cookies and session cookies. Persistent cookies stay on your device for a set period of time or until you delete them, while session cookies are deleted once you close your web browser. We use persistent cookies, for example, to remember any preferences you have or choices you make when you use our Website. *** ## 4. What types of cookies do we use? In this section, we outline the specific types of cookies served through our Website and the purposes they serve. These cookies include: * **Strictly necessary cookies**: These cookies are strictly necessary to provide you with services available through our Website. They provide page navigation functionality and access to secure areas. You can set your browser to block these cookies, but then some parts of the services will not work. * **Analytics/Performance cookies**: These are analytics cookies that allow us to collect information about how visitors use a website, for instance which pages visitors go to most often, and if they get error messages from web pages. This helps us to improve the way the Website works and allows us to test different ideas on the Website. * **Functionality cookies**: These cookies enhance the performance of our Website (e.g., they allow us to remember your preferences and settings). Without these cookies, certain functionality may become unavailable. For more information on the types of cookies we use, please see our cookies banner page. Depending on your location, the maximum expiration period for the cookies above is 1 year. *** ## 5. How can you control cookies? Depending on where you access our Website from, you may be presented with a cookie banner or other tool to provide permissions before we or our service providers set non-Essential cookies. In this case, we only set these non-essential cookies with your consent. Where this option is available, you may revoke your consent at any time with future effect by clicking on the cookie settings link on our Website at any time. You can also limit online tracking by: * **Blocking cookies in your browser**. Most browsers let you remove or reject cookies. To do this, follow the instructions in your browser settings. Many browsers accept cookies by default until you change your settings. For more information about cookies, including how to see what cookies have been set on your device and how to manage and delete them, visit [www.allaboutcookies.org](http://www.allaboutcookies.org). Use the following links to learn more about how to control cookies and online tracking through your browser: * [Firefox](https://support.mozilla.org/en-US/kb/clear-cookies-and-site-data-firefox) * [Chrome](https://support.google.com/chrome/answer/95647?hl=en-GB\&co=GENIE.Platform=Desktop#:~:text=that%2520web%2520page.-,On%2520your%2520computer%252C%2520open%2520Chrome%2520.,Allow%2520all%2520cookies.) * [Microsoft Edge](https://support.microsoft.com/en-us/microsoft-edge/delete-cookies-in-microsoft-edge-63947406-40ac-c3b8-57b9-2a946a29ae09) * [Safari](https://support.apple.com/en-gb/guide/safari/sfri11471/mac) * **Platform opt-outs**. Some of our partners (e.g., Posthog) offer opt-out features that let you opt out of use of cookies. Note that because these opt-out mechanisms are specific to the device or browser on which they are exercised, you will need to opt out on each browser and device that you use. **Do Not Track**. Some Internet browsers can be configured to send "**Do Not Track**" signals to the online services that you visit. We currently do not respond to "Do Not Track" or similar signals. To find out more about "Do Not Track," please visit [http://www.allaboutdnt.com](http://www.allaboutdnt.com). *** ## 6. How often will we update this Cookie Policy? We may update this Cookie Policy from time to time in order to reflect, for example, changes to the cookies we use or for other operational, legal or regulatory reasons. We will notify you of any material changes to this Cookie Policy prior to the changes becoming effective by posting the changes on this page and providing a more prominent notice with on-site or email notifications. Please therefore re-visit this Cookie Policy regularly to stay informed about our use of cookies and related technologies. The date at the top of this Cookie Policy indicates when it was last updated. *** ## 7. Where can you get further information? If you have any questions about our use of cookies, please email us at **[support@paygentic.io](mailto:support@paygentic.io)**. # Privacy Policy Source: https://docs.paygentic.io/legal/privacy-policy How Paygentic collects, uses, and protects your personal information **Effective Date:** 16 December 2025 This Privacy Policy explains how Paygentic, Inc. ("**Paygentic**", "**we**", "**us**", or "**our**") handles your personal information when you use our website at docs.paygentic.io/introduction ("**Website**"), the Paygentic platform ("**Platform**"), accounts, and any related services (collectively, the "**Services**"). Paygentic provides billing and payment infrastructure for AI applications, enabling Merchants to configure pricing models, track usage, manage billing, and facilitate payment processing through integrated payment processors and licensed financial institutions. This Privacy Policy applies to: * Merchants who use the Paygentic Platform to monetize their products, services, or APIs; * End Users (also referred to as "End Customers" or "Consumers") who purchase services from Merchants via the Platform and/or maintain account balances; * Visitors to the Paygentic Website; * Vendors and service providers who interact with Paygentic; * Job applicants and potential users submitting personal information to Paygentic. *** ## 1. Personal Information We Collect ### 1.1 Personal information you provide when you use our Services: * **Contact details**, such as name, email address, postal address, phone number, company information (including company name, job role, address, location). * **Account information**: if you are a Consumer and wish to interact with multiple merchants, you can create an account. If you do, we will collect your username and password. * **Identity verification details**, such as government-issued ID, date of birth, and liveness/selfie checks for KYC/AML purposes. * **Payment information**, including your bank account information. * **Communications** that we exchange with you, including when you contact us with questions, feedback, or otherwise correspond with us online. * **Marketing information**, such as your preferences for receiving our newsletters and marketing communications about our Services, and the types of products we think will interest you based on your past purchases and use of our Services. * **Job applicants**, we may collect personal data from you when you enquire or apply for a vacancy with us, such as your name, contact details, curriculum vitae (such as, qualifications, previous employment history and profession activities), results of background checks (such as, references, qualifications, and to the extent permitted by law, criminal background checks (unspent convictions)). * **Other data** not specifically listed here, which we will use as described in this Privacy Policy or as otherwise disclosed at the time of collection. Where you provide us with the personal information of third parties, it is your responsibility to inform them about the processing of their personal information in accordance with this Privacy Policy, and to confirm that they have given their permission. ### 1.2 Automatic data collection: We and our service providers may automatically log information about you, your computer or mobile device, and your interactions with our Services and our communications, such as: * **Device and network data**, such as your computer's or mobile device's operating system type and version, manufacturer and model, browser type, screen resolution, device type (e.g., phone, tablet), IP address, general location (e.g., derived from your IP address), unique identifiers, and language settings. * **Usage data**, such as pages or screens you viewed, the website you visited before browsing to the Services, navigation paths between pages or screens, information about your activity on a page or screen, access times, and whether you have opened or otherwise engage with our communications, such as our marketing emails, and what kind of content you're interested in. * **Location information**, such as your city, state, zip or postal code, to personalize content provided to you, or to show you prices and promotions. We collect this information using cookies, pixels, and other similar technologies. For more information, please visit our [Cookie Policy](/legal/cookie-policy). ### 1.3 Information we obtain from other sources * **Social media information**. We maintain pages on social media platforms, such as LinkedIn, and other third-party platforms. When you visit or interact with our pages on those platforms, the platform provider's privacy policy will apply to your interactions and their collection, use, and processing of your personal information. You or the platforms may provide us with your information through the platform, and we will treat such information in accordance with this Privacy Policy. * **Other sources**. We may obtain personal information from other third parties, such as identity verification service providers, payment processors and licensed financial institutions, fraud prevention and sanctions screening tools, credit reference agencies and public databases where permitted by law, information provided by Merchants about their End Users as necessary to provide Services, analytics and marketing partners and publicly available sources, including from partners that help us advertise and market our Services. *** ## 2. How We Use Your Personal Information We collect and process your personal data where we have a legal basis to do so. The legal basis for our collection and use of your personal data varies depending on the manner and purpose for which we collected it: * **Provide and maintain the Services.** To perform our contract with you, or when it is in our legitimate business interests to do so, we will use personal information to operate, provide and maintain our Services, including to create and manage your account so you can log in, build a profile, and interact with us to benefit from our products and Services. * **Improve, monitor and personalize the Services**. It is in our legitimate interests to improve and keep our Services safe, which includes protecting the security of our Services, and preventing and detecting security threats, fraud or other criminal or malicious activities. * **Facilitate your login to the Services**. It is in our legitimate business interests to use personal information to enable you to access our Services, increasing your access options and the efficiency of using the Services. * **Communicate with you about the Services**, including by sending you announcements, updates, security alerts, and support and administrative messages. To perform our contractual obligations to you, or when it is in our legitimate interests to do so, we will use your personal information to sending you announcements, updates, security alerts, and support and administrative messages respond to your requests, questions, and feedback, and communicate with you about our Services, including by sending announcements, updates, security alerts, and user support and administrative messages. * **Research and development.** We use personal information to help us better understand how people use our Services and how we can develop, analyse and improve them where it is in our legitimate interests to do so. This includes analyzing trends, testing new features, and making design or product decisions based on user behaviour. We may also create or use aggregated data to support research and insights that help us build better offerings as part of our Services. This data no longer identifies you. * **Marketing and Advertising**. We and our advertising partners may collect and use your personal information for marketing and advertising purposes, including * **Direct marketing.** We may send you curated content as permitted by law, including, but not limited to, newsletters and notifications about special promotions, offers, and events that we think may be of interest to you, including by email. You may opt out of our marketing communications as described in the "Opt-out of marketing communications" section below. Except where consent is required, we undertake such marketing on the basis of our legitimate business interests to use your personal information for the purposes described above. Where we rely on your consent, you may withdraw your consent at any time, including by following the opt-out instructions in the "Your Privacy Rights and Choices" section below. Except where consent is required, we carry out marketing and advertising where it is in our legitimate business interests. Where we seek your consent, you may withdraw your consent at any time. * **Compliance and protection.** We use your personal information to comply with our legal obligations and to defend us against legal claims or disputes where it is in our legitimate business interests to do so, including to: * Comply with applicable laws, lawful requests, and legal process, such as to respond to subpoenas or requests from government authorities. * Audit our internal processes for compliance with legal and contractual requirements and internal policies. * Enforce the terms and conditions that govern our Services. * Where we have a legitimate interest, to prevent, identify, investigate, and deter fraudulent, harmful, unauthorized, unethical, or illegal activity, including cyberattacks and identity theft. * Where we have a legitimate interest, to protect our, your or others' rights, privacy, safety or property (including by making and defending legal claims). *** ## 3. How We Disclose Your Personal Information We may disclose personal information to the following parties: * **Affiliates.** We may disclose your personal information to our subsidiaries and affiliates for purposes consistent with this Privacy Policy. * **Service providers.** We may disclose your personal information to third-party companies and individuals that provide services on our behalf or help us operate our Services (e.g., our third-party vendors providing hosting, information technology, customer support, payment processing platforms, email delivery, and website analytics services). * **Professional advisors.** We may disclose your personal information to professional advisors, such as lawyers, auditors, bankers, and insurers, where necessary in the course of the professional services that they render to us. * **Authorities and others.** We may disclose your personal information to law enforcement, government authorities, and private parties, as we believe in good faith to be necessary or appropriate for the compliance and protection purposes described above. * **Advertising partners and other third parties.** Third parties, such as advertising companies, social media providers, search engines and data providers, for interest-based advertising and other marketing purposes. These third parties may use the information we share to develop and improve their services, including to improve their ability to target ads on our and their other clients' behalf. To learn about your choices, please see the "Your Privacy Rights and Choices" section below. * **Business transferees.** We may disclose your personal information to acquirers and other relevant participants in business transactions (or negotiations for such transactions) involving a corporate divestiture, merger, consolidation, acquisition, reorganization, sale, or other disposition of all or any portion of the business or assets of, or equity interests in, our business (including, in connection with a bankruptcy or similar proceedings). * **With your instruction or permission.** We may disclose personal information to relevant third parties, where you give us permission to do so in the course of your relationship with us from time to time. *** ## 4. International Data Transfers In the context of providing you with our Services, we may transfer your personal information to our affiliates and service providers in the United States and other jurisdictions. Please note that such jurisdictions may not provide the same protections as the data protection laws in your home country. When we engage in cross-border data transfers, we will ensure that relevant safeguards are in place to afford adequate protection for personal information and we will comply with applicable data protection laws, in particular by relying on an EU Commission or UK government adequacy decision or on contractual protections for the transfer of personal information. For more information about how we transfer personal information internationally, please contact us as set out in the "How to contact us" section below. *** ## 5. Your Privacy Rights and Choices ### 5.1 Opt-out of marketing communications. You may opt out of marketing-related emails, SMS and other communications by following the opt-out or unsubscribe instructions in the communications you receive from us or by contacting us as provided in the "How to Contact Us" section below. You may continue to receive Services-related and other non-marketing emails and SMS. ### 5.2 Account deactivation and deletion. If you have an account on our Services, you may deactivate and delete your account by contacting us as described in the "How to Contact Us" section below. Note that deactivating your account may not cause us to fully delete all of your personal information. To request that we do so, please submit a data deletion request as described in the "Personal information requests" section. ### 5.3 Personal information requests. In addition to the above, depending on where you are based, and as provided under applicable law and subject to any limitations in such law, you may have the right to: * **Information** about how we have collected and used your personal information. We have made this information available to you without having to request it by including it in this Privacy Policy. * **Access** to a copy of the personal information that we have collected about you. Where applicable, we will provide the information in a portable, machine-readable, readily usable format. * **Correction** of personal information that is inaccurate, incomplete or otherwise out of date. * **Deletion** of personal information that we no longer need to provide the Services or for other lawful purposes. * **Additional choices for residents of the European Economic Area ("EEA") and United Kingdom ("UK")**: * **Request we restrict** our handling of your personal information. * **Opt out** of "profiling" in connection with decisions that produce legal or similarly significant effects. We do not engage in profiling in connection with decisions that produce legal or similarly significant effects. * **Object** to how we are using your personal information. * **Withdraw** your consent to us handling your personal information, where we are relying on your consent to process such personal information. * **Right to complain.** You have the right to complain to a data protection regulator where you live or work, or where you feel a violation has occurred. If you reside in the EEA, click [here](https://edpb.europa.eu/about-edpb/about-edpb/members_en) to find your local supervisory authority, and [here](https://ico.org.uk/make-a-complaint) if you are in the United Kingdom. To make a request, please email us or write to us as provided in the "How to Contact Us" section below. We may ask for specific information from you to help us confirm your identity. Depending on where you reside, you may be entitled to empower an authorized agent to submit requests on your behalf. We will require authorized agents to confirm their identity and authority, in accordance with applicable laws. You are entitled to exercise the rights described above free from discrimination. In some instances, your choices may be limited, such as where fulfilling your request would impair the rights of others, our ability to provide a service you have requested, or our ability to comply with our legal obligations and enforce our legal rights. If you are not satisfied with how we address your request, you may submit a complaint by contacting us as provided in the "How to Contact Us" section below. * **Limit online tracking.** There are a number of ways to limit online tracking, which we have summarized below. Please note that these tools are not associated with us and we cannot guarantee that they work as their providers advertise them: * **Blocking cookies in your browser**. Most browsers let you remove or reject cookies. To do this, follow the instructions in your browser settings. Many browsers accept cookies by default until you change your settings. For more information about cookies, including how to see what cookies have been set on your device and how to manage and delete them, visit [https://www.allaboutcookies.org/](https://www.allaboutcookies.org/). * **Using privacy plug-ins or browsers**. You can block our Website from setting cookies by using a browser with privacy features, like [Brave](https://brave.com/), or installing browser plugins like [Privacy Badger](https://privacybadger.org/), [Ghostery](https://www.ghostery.com/), or [uBlock Origin](https://ublock.org/), and configuring them to block third party cookies/trackers. You can also opt out of Google Analytics by downloading and installing the browser plug-in available at: [https://tools.google.com/dlpage/gaoptout](https://tools.google.com/dlpage/gaoptout). * **Blocking advertising ID use in your mobile settings**. Your mobile device settings may provide functionality to limit use of the advertising ID associated with your mobile device for interest-based advertising purposes. * **Advertising industry opt-out tools**. You can also use these opt-out options to limit use of your information for interest-based advertising by participating companies: * Digital Advertising Alliance * [Network Advertising Initiative](https://optout.networkadvertising.org/?c=1) * **Do Not Track.** Some Internet browsers may be configured to send "Do Not Track" signals to the online services that you visit. We currently do not respond to "Do Not Track" signals. To find out more about "Do Not Track," please visit [http://www.allaboutdnt.com](http://www.allaboutdnt.com). Note that because these opt-out mechanisms are specific to the device or browser on which they are exercised, you will need to opt out on every browser and device that you use. *** ## 6. Other Sites and Services Our Services may contain links to websites and other online services operated by third parties. In addition, our content may be included on web pages or in mobile applications or online services that are not associated with us. These links and integrations are not an endorsement of, or representation that we are affiliated with, any third party. We do not control third party websites, mobile applications or online services, and we are not responsible for their actions. Other websites and services follow different rules regarding the collection, use and disclosure of your personal information. We encourage you to read the privacy policies of the other websites and mobile applications and online services you use. *** ## 7. Security We use reasonable organizational, technical, and administrative measures designed to protect against unauthorized access, misuse, loss, disclosure, alteration, and destruction of personal information we maintain. Unfortunately, data transmission over the Internet cannot be guaranteed as completely secure. Therefore, while we strive to protect your personal information, we cannot guarantee the security of personal information. *** ## 8. Children's Privacy While our Website is designed for a general audience, we do not knowingly collect any data from children under the age of 18. If we learn that we have collected personal information through the Website from a child under 18 without the consent of the child's parent or guardian as required by law, we will delete it. *** ## 9. Retention of Personal Information Where required under applicable laws, we retain personal information only for as long as is necessary to fulfill the purposes for which it was collected and processed in accordance with applicable laws and regulatory obligations or until you withdraw your consent (where applicable). To determine the appropriate retention period for personal information, we consider the amount, nature, and sensitivity of the personal information, the potential risk of harm from unauthorized use or disclosure of personal information, the purposes for which we use personal information and whether we can achieve those purposes through other means, and the applicable legal and regulatory requirements. *** ## 10. Changes to this Privacy Policy We reserve the right to modify this Privacy Policy at any time. If we make material changes to this Privacy Policy, we will notify you by updating the date of this Privacy Policy and posting it on the Website. *** ## 11. How to Contact Us Paygentic, Inc. is the entity responsible for the processing of personal information under this Privacy Policy (as a controller, where provided under applicable law). If you have any questions or comments about this Privacy Policy, our privacy practices, or if you would like to exercise your rights with respect to your personal information, please contact us by email at: [support@paygentic.io](mailto:support@paygentic.io) or write to us at: 2443 Fillmore St #380-3755, San Francisco, CA 94115, USA. If you are based in the UK or European Economic Area, please email: [dpo@paygentic.io](mailto:dpo@paygentic.io). # Terms and Conditions Source: https://docs.paygentic.io/legal/terms-and-conditions Legal terms and conditions for using Paygentic services **Last Updated:** December 16, 2025 ## Acceptance of These Terms of Service Paygentic, Inc. ("Paygentic," "we," "us," or "our") provides our services (described below) and related content to you through our website located at [https://www.paygentic.io](https://www.paygentic.io) (the "Site") and through our application programming interfaces related technologies ("APIs", and collectively, such APIs and the Site, including any updated or new features, functionality and technology, the "Service"). All access and use of the Service is subject to the terms and conditions contained in these Terms of Service (as amended from time to time, these "Terms of Service"). By accessing, browsing, or otherwise using the Site or any other aspect of the Service, you acknowledge that you have read, understood, and agree to be bound by these Terms of Service. If you do not accept the terms and conditions of these Terms of Service, you will not access, browse, or otherwise use the Service. If you are entering into these Terms of Service on behalf of a company, business or other legal entity, you represent that you have the authority to bind such entity to these Terms of Service, in which case the terms "you" or "your" shall refer to such entity (other than the references in this sentence and the following sentence). If you do not have such authority, you must not accept these Terms of Service and may not use the Service on behalf of such entity. We reserve the right, at our sole discretion, to change or modify portions of these Terms of Service at any time. If we do this, we will post the changes on this page and will indicate at the top of this page the date these Terms of Service were last revised. You may read a current, effective copy of these Terms of Service by visiting the "Terms of Service" link on the Site. We will also notify you of any material changes, either through the Service user interface, a pop-up notice, email, or through other reasonable means. Your continued use of the Service after the date any such changes become effective constitutes your acceptance of the new Terms of Service. You should periodically visit this page to review the current Terms of Service so you are aware of any revisions. If you do not agree to abide by these or any future Terms of Service, you will not access, browse, or use (or continue to access, browse, or use) the Service. **IF YOU ARE ENTERING INTO THESE TERMS OF SERVICE AS AN INDIVIDUAL: READ THESE TERMS OF SERVICE CAREFULLY, AS THEY CONTAIN AN AGREEMENT TO ARBITRATE AND OTHER IMPORTANT INFORMATION REGARDING YOUR LEGAL RIGHTS, REMEDIES, AND OBLIGATIONS. THE AGREEMENT TO ARBITRATE REQUIRES (WITH LIMITED EXCEPTION) THAT YOU SUBMIT CLAIMS YOU HAVE AGAINST US TO BINDING AND FINAL ARBITRATION, AND FURTHER (1) YOU WILL ONLY BE PERMITTED TO PURSUE CLAIMS AGAINST PAYGENTIC ON AN INDIVIDUAL BASIS, NOT AS A PLAINTIFF OR CLASS MEMBER IN ANY CLASS OR REPRESENTATIVE ACTION OR PROCEEDING, (2) YOU WILL ONLY BE PERMITTED TO SEEK RELIEF (INCLUDING MONETARY, INJUNCTIVE, AND DECLARATORY RELIEF) ON AN INDIVIDUAL BASIS, AND (3) YOU MAY NOT BE ABLE TO HAVE ANY CLAIMS YOU HAVE AGAINST US RESOLVED BY A JURY OR IN A COURT OF LAW.** **Your Privacy:** At Paygentic, we respect the privacy of our users. For more information please see our [Privacy Policy](/legal/privacy-policy) (the "Privacy Policy"). By using the Service, you consent to our collection, use and disclosure of personal data and other data as outlined therein. **Additional Terms**: In addition, when using certain features through the Service, you will be subject to any additional terms applicable to such features that may be posted on or within the Service from time to time. All such terms are hereby incorporated by reference into these Terms of Service. *** ## Access and Use of the Service ### Service Description The Service provides a billing and payment infrastructure platform that enables merchants to configure and manage pricing models (usage-based, outcome-based, subscription, hybrid, revenue-share), track and meter usage data in real-time, generate invoices and billing records, facilitate payment collection and access account management functionality and analytics and reporting tools. The Service also includes APIs for payment integrations with users' AI agents. Paygentic is a financial technology company, not a bank or money services business. Payment services are provided by licensed financial institutions and payment processors. ### Your Registration Obligations You may be required to register with Paygentic or provide information about yourself (e.g., name and email address) in order to access and use certain features of the Service. If you choose to register for the Service, you agree to provide and maintain true, accurate, current, and complete information as prompted by the Service's registration form. Registration data and certain other information about you are governed by our [Privacy Policy](/legal/privacy-policy). You must be 18 years of age or older to use the Service. ### Member Account, Password and Security You are responsible for maintaining the confidentiality of your password and account details, if any, and are fully responsible for any and all activities that occur under your password or account. You agree to (a) immediately notify Paygentic of any unauthorized use of your password or account or any other breach of security, and (b) ensure that you exit from your account at the end of each session when accessing the Service. Paygentic will not be liable for any loss or damage arising from your failure to comply with this paragraph. ### Modifications to Service Paygentic reserves the right to modify or discontinue, temporarily or permanently, the Service (or any part thereof) with or without notice. You agree that Paygentic will not be liable to you or to any third party for any modification, suspension or discontinuance of the Service. ### General Practices Regarding Use and Storage You acknowledge that Paygentic may establish general practices and limits concerning use of the Service, including the maximum period of time that data or other content will be retained by the Service and the maximum storage space that will be allotted on Paygentic's or its third-party service providers' servers on your behalf. You agree that Paygentic has no responsibility or liability for the deletion or failure to store any data or other content maintained or uploaded by the Service. You acknowledge that Paygentic reserves the right to terminate accounts that are inactive for an extended period of time. You further acknowledge that Paygentic reserves the right to change these general practices and limits at any time, in its sole discretion, with or without notice. *** ## Conditions of Access and Use ### User Conduct You are solely responsible for all data, information, feedback, suggestions, text, content and other materials that you upload, post, deliver, provide or otherwise transmit or store in or through the Service or otherwise make available to Paygentic (collectively, "User Content"). The following are examples of the kinds of content and/or uses that are illegal or prohibited by Company. Company reserves the right to investigate and take appropriate legal action against anyone who, in Company's sole discretion, violates this provision, including removing the offending content from the Service, suspending or terminating the account of such violators, and reporting the violator to law enforcement authorities. You agree to not use the Service to: a) email or otherwise upload any content that (i) infringes any intellectual property or other proprietary rights of any party; (ii) you do not have a right to upload under any law or under contractual or fiduciary relationships; (iii) contains software viruses or any other computer code, files or programs designed to interrupt, destroy, or limit the functionality of any computer software or hardware or telecommunications equipment; (iv) poses or creates a privacy or security risk to any person; (v) constitutes unsolicited or unauthorized advertising, promotional materials, commercial activities and/or sales, "junk mail," "spam," "chain letters," "pyramid schemes," "contests," "sweepstakes," or any other form of solicitation; (vi) is unlawful, harmful, threatening, abusive, harassing, tortious, excessively violent, defamatory, vulgar, obscene, pornographic, libelous, invasive of another's privacy, hateful, discriminatory, or otherwise objectionable; or (vii) in the sole judgment of Company, is objectionable or which restricts or inhibits any other person from using or enjoying the Service, or which may expose Company or its users to any harm or liability of any type; b) interfere with or disrupt the Service or servers or networks connected to the Service, or disobey any requirements, procedures, policies, or regulations of networks connected to the Service; c) violate any applicable local, state, national, or international law, or any regulations having the force of law; d) impersonate any person or entity, or falsely state or otherwise misrepresent your affiliation with a person or entity; e) solicit personal information from anyone under the age of 18; f) harvest or collect email addresses or other contact information of other users from the Service by electronic or other means for the purposes of sending unsolicited emails or other unsolicited communications; g) further or promote any criminal activity or enterprise or provide instructional information about illegal activities; h) obtain or attempt to access or otherwise obtain any content or information through any means not intentionally made available or provided for through the Service; i) circumvent, remove, alter, deactivate, degrade, or thwart any of the content protections in or geographic restrictions on any content (including Service Content (as defined below)) available on or through the Service, including through the use of virtual private networks; or j) engage in or use any data mining, robots, scraping, or similar data gathering or extraction methods. If you are blocked by Company from accessing the Service (including by blocking your IP address), you agree not to implement any measures to circumvent such blocking (e.g., by masking your IP address or using a proxy IP address or virtual private network). ### Competitors No employee, independent contractor, agent, or affiliate of company that provides any competing platform that facilitates billing, payments or monetization is permitted to view, access, or use any portion of the Service without express written permission from Paygentic. By viewing, using, or accessing the Service, you represent and warrant that you are not a competitor of Paygentic or any of its affiliates, or acting on behalf of a competitor of Paygentic in using or accessing the Service. ### Payment Processing PAYGENTIC DOES NOT PROCESS PAYMENT FOR ANY SERVICES. To receive a payment from your customer, or to remit a payment to your service provider via bank account, credit card, or debit card, we engage with one or more third-party payment processors ("Payment Processors"). These payment processing services are provided by the Payment Processors and are subject to their terms and conditions and privacy policies ("Payment Processor Agreements"). By agreeing to these Terms of Service, users that use the payment functions of the Service also agree to be bound by the Payment Processor Agreements, as the same may be modified by the Payment Processors from time to time. The terms and conditions of the sale of services through the Site are entered into by the sellers and buyers, and you acknowledge that Paygentic is not a party to these transactions. All inquiries, questions or disputes about the quality of the services or any other issues arising out of the transactions must be resolved between the sellers and buyers directly. Paygentic assumes no liability or responsibility for any payments you make through the Service. **If you are a buyer purchasing services from other users on the Site**: To the extent we permit you to prefund your Paygentic account for future spending with sellers on the Site, your funds will be held by a qualified Payment Processor in a depository institution for your benefit. You acknowledge and agree that your Paygentic account is not a checking, prepaid or savings account, the prefunded balance is not insured by the Federal Deposit Insurance Corporation and does not earn interest, and you may not transfer any prefunded balance to any third party other than making purchases from sellers on the Site. We may limit the amount or frequency you may prefund your account or transact through your Paygentic account from time to time without notice to you. Prefunded balance is not refundable unless required by law, and the balance is subject to escheatment if your Paygentic account is inactive for an extended period of time. If the Payment Processor reports your remaining balance to the state as abandoned property, you must claim your funds from the state directly. **If you are a seller providing services to other users on the Site**: You must clearly disclose to prospective buyers the terms and conditions of using your services and your refund and return policy. You must promptly resolve all inquiries and complaints from other users, and process all refunds in accordance with your refund policy and payment network rules. You are solely responsible for any transaction disputes or chargebacks. You must link a valid bank account or supported payment method to your Paygentic account to receive payout for sales you conducted on the Site. You hereby authorize us or our Payment Processor to credit your payment method in the amount of your requested payout. Fees may apply for certain payout methods, which will be disclosed to you before you confirm to proceed. We may limit the frequency and amount of your payout requests from time to time, or to delay your payout request, to protect us against risks to our system other users. You authorize us to debit your linked payment method for all chargebacks, fees, fines, penalties and other losses you owe us under these Terms of Service. In our sole discretion, we may require you to maintain a reserve account if we detect unusual activities or excessive risks associated with your account or your use of the Service. ### Fees You may be required to select a payment plan and provide information regarding your credit card or other payment instrument through the Service. You represent and warrant to Paygentic that such information is true and that you are authorized to use the payment instrument. You will promptly update your account information with Paygentic or its Payment Processor, as applicable, of any changes (for example, a change in your billing address or credit card expiration date) that may occur. You hereby authorize the Payment Processors to store and continue billing your specified payment method even after such payment method has expired, to avoid interruptions in payment for your use of the Service. You agree to pay Paygentic the amount that is specified in the payment plan in accordance with the terms of such plan and these Terms of Service. **If your payment plan includes an ongoing subscription that is automatically renewed periodically, you hereby authorize Paygentic (through the Payment Processor) to bill your payment instrument in advance on such periodic basis in accordance with the terms of the applicable payment plan until you terminate your account, and you further agree to pay any charges so incurred.** If you dispute any charges, you must let Paygentic know within sixty (60) days after the date that Paygentic charges you, or within such longer period of time as may be required under applicable Law. We reserve the right to change Paygentic's prices. If Paygentic does change prices, Paygentic will provide notice of the change through the Service user interface, a pop-up notice, email, or through other reasonable means, at Paygentic's option, at least thirty (30) days before the change is to take effect. Your continued use of the Service after the price change becomes effective constitutes your agreement to pay the changed amount. You will be responsible for all taxes associated with the Service, other than taxes based on Paygentic's net income. ### Commercial Use Unless otherwise expressly authorized herein or in the Service, you agree not to display, distribute, license, perform, publish, reproduce, duplicate, copy, create derivative works from, modify, sell, resell, exploit, transfer, or upload for any commercial purposes, any portion of the Service, use of the Service, or access to the Service. If you are entering into these Terms of Service as an individual, the Service is only for your personal use. If you are entering into these Terms of Service on behalf of an entity, the Service is only for your internal business purposes. *** ## Mobile Services and Software ### Mobile Services The Service includes certain services that are available via a mobile device, including the ability to browse the Site and access and use the Service from a mobile device (the "Mobile Services"). To the extent you access the Service through a mobile device, your wireless service carrier's standard charges, data rates, and other fees may apply. In addition, downloading, installing or using certain Mobile Services may be prohibited or restricted by your carrier, and not all Mobile Services may work with all carriers or devices. By using the Mobile Services, you agree that we may communicate with you regarding Paygentic and other entities by SMS, MMS, text message, or other electronic means to your mobile device and that certain information about your usage of the Mobile Services may be communicated to us. In the event you change or deactivate your mobile telephone number, you agree to promptly update your Paygentic account information to ensure that your messages are not sent to the person that acquires your old number. ### Ownership; Restrictions The technology and software underlying the Service or distributed in connection therewith, including the APIs, are the property of Paygentic, its affiliates, and its licensors (the "Software"). You agree not to copy, modify, create a derivative work of, reverse engineer, reverse assemble, or otherwise attempt to discover any source code, sell, assign, sublicense, or otherwise transfer any right in the Software. Any rights not expressly granted herein are reserved by Paygentic. ### APIs Subject to the terms and conditions in these Terms of Service, Paygentic hereby grants you the limited, non-exclusive, non-transferable, non-sublicensable right and license to download and use the APIs solely to access and use the Service for your internal business purposes. ### Special Notice for International Use; Export Controls You are solely responsible for ensuring compliance with the laws of your specific jurisdiction. Software available in connection with the Service and the transmission of applicable data, if any, is subject to United States export controls. No Software may be downloaded from the Service or otherwise exported or re-exported in violation of U.S. export laws. Downloading or using the Software is at your sole risk. *** ## Intellectual Property Rights ### Service Content You acknowledge and agree that the Service may contain content or features ("Service Content") that are protected by copyright, patent, trademark, trade secret, or other proprietary rights and laws. Except as expressly authorized by Paygentic, you agree not to modify, copy, frame, scrape, rent, lease, loan, sell, distribute, or create derivative works based on the Service or the Service Content, in whole or in part, except that the foregoing does not apply to your own User Content that you upload to or make available through the Service in accordance with these Terms of Service. Any use of the Service or the Service Content other than as specifically authorized herein is strictly prohibited. ### Trademarks The Paygentic name and logos are trademarks and service marks of Paygentic (collectively the "Paygentic Trademarks"). Other company, product, and service names and logos used and displayed via the Service may be trademarks or service marks of their respective owners who may or may not endorse or be affiliated with or connected to Paygentic. Nothing in these Terms of Service or the Service should be construed as granting, by implication, estoppel, or otherwise, any license or right to use any of Paygentic Trademarks displayed on the Service, without our prior written permission in each instance. All goodwill generated from the use of Paygentic Trademarks will inure to our exclusive benefit. ### Third-Party Material Under no circumstances will Paygentic be liable in any way for any content or materials of any third parties (including users), including for any errors or omissions in any content, or for any loss or damage of any kind incurred as a result of the use of any such content. You acknowledge that Company does not pre-screen content, but that Company and its designees will have the right (but not the obligation) in their sole discretion to refuse or remove any content that is available via the Service. Without limiting the foregoing, Company and its designees will have the right to remove any content that violates these Terms of Service or is deemed by Company, in its sole discretion, to be otherwise objectionable. You agree that you must evaluate, and bear all risks associated with, the use of any content, including any reliance on the accuracy, completeness, or usefulness of such content. ### User Content You represent and warrant that you own all right, title and interest in and to the User Content, including all copyrights and rights of publicity contained therein. You hereby grant Company and its affiliated companies, successors, and assigns a non-exclusive, worldwide, royalty-free, fully paid-up, transferable, sublicensable (directly and indirectly through multiple tiers), perpetual, and irrevocable license to copy, display, upload, perform, distribute, store, modify, and otherwise use your User Content (including the data therein, but subject to the [Privacy Policy](/legal/privacy-policy)) in connection with the operation of the Service, developing and improving Paygentic's products and services and creating aggregated and/or anonymous data sets and analytics (which such aggregated and/or anonymized data sets shall not be deemed "User Content" hereunder). You assume all risk associated with your User Content and the transmission of your User Content, and you have sole responsibility for the accuracy, quality, legality and appropriateness of your User Content. In addition to the foregoing, you hereby authorize Paygentic and its third-party service providers to derive statistical and usage data relating to your use of the Service ("Usage Data"). We may use Usage Data for any purpose in accordance with applicable law and our [Privacy Policy](/legal/privacy-policy). Any questions, comments, suggestions, ideas, feedback, reviews, or other information about the Service ("Submissions"), provided by you to Paygentic are non-confidential and Paygentic will be entitled to the unrestricted use and dissemination of these Submissions for any purpose, commercial or otherwise, without acknowledgment, attribution, or compensation to you. You acknowledge and agree that Company may preserve User Content and may also disclose User Content if required to do so by law or in the good faith belief that such preservation or disclosure is reasonably necessary to: (a) comply with legal process, applicable laws, or government requests; (b) enforce these Terms of Service; (c) respond to claims that any content violates the rights of third parties; or (d) protect the rights, property, or personal safety of Company, its users, or the public. You understand that the technical processing and transmission of the Service, including your User Content, may involve (i) transmissions over various networks; and (ii) changes to conform and adapt to technical requirements of connecting networks or devices. *** ## Third-Party Services and Websites The Service may provide links or other access to services, sites, technology, and resources that are provided or otherwise made available by third parties (the "Third-Party Services"). Additionally, you may enable or log into the Service via online Third-Party Services, such as Google. Your access and use of the Third-Party Services may also be subject to additional terms and conditions, privacy policies, or other agreements with such third party, and you may be required to authenticate to or create separate accounts to use Third-Party Services on the websites or via the technology platforms of their respective providers. Some Third-Party Services will provide us with access to certain information that you have provided to third parties, including through such Third-Party Services, and we will use, store and disclose such information in accordance with our [Privacy Policy](/legal/privacy-policy). For more information about the implications of activating Third-Party Services and our use, storage and disclosure of information related to you and your use of such Third-Party Services within the Service, please see our [Privacy Policy](/legal/privacy-policy). Paygentic has no control over and is not responsible for such Third-Party Services, including for the accuracy, availability, reliability, or completeness of information shared by or available through Third-Party Services, or on the privacy practices of Third-Party Services. We encourage you to review the privacy policies of the third parties providing Third-Party Services prior to using such services. You, and not Paygentic, will be responsible for any and all costs and charges associated with your use of any Third-Party Services. Paygentic enables these Third-Party Services merely as a convenience and the integration or inclusion of such Third-Party Services does not imply an endorsement or recommendation. Any dealings you have with third parties while using the Service are between you and the third party. Paygentic will not be responsible or liable, directly or indirectly, for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any Third-Party Services. *** ## Indemnification You agree to defend, indemnify, and hold harmless Paygentic, its affiliates, and its and their respective officers, employees, directors, service providers, licensors, and agents (collectively, the "Paygentic Parties") from any and all losses, damages, expenses, including reasonable attorneys' fees, rights, claims, actions of any kind, and injury (including death) arising out of or relating to your use of the Service, any User Content, your connection to the Service, your violation of these Terms of Service, or your violation of any rights of another. Notwithstanding the foregoing, you will have no obligation to indemnify or hold harmless any Paygentic Party from or against any liability, losses, damages, or expenses incurred as a result of any action or inaction of such Paygentic Party. Paygentic will provide notice to you of any such claim, suit, or proceeding. Paygentic reserves the right to assume the exclusive defense and control of any matter which is subject to indemnification under this section, and you agree to cooperate with any reasonable requests assisting Paygentic's defense of such matter. You may not settle or compromise any claim against the Paygentic Parties without Paygentic's written consent. *** ## Disclaimers YOUR USE OF THE SERVICE IS AT YOUR SOLE RISK. THE SERVICE IS PROVIDED ON AN "AS IS" AND "AS AVAILABLE" BASIS. THE PAYGENTIC PARTIES EXPRESSLY DISCLAIM ALL WARRANTIES OF ANY KIND, WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. THE PAYGENTIC PARTIES MAKE NO WARRANTY THAT (A) THE SERVICE WILL MEET YOUR REQUIREMENTS; (B) THE SERVICE WILL BE UNINTERRUPTED, TIMELY, SECURE, OR ERROR-FREE; (C) THE RESULTS THAT MAY BE OBTAINED FROM THE USE OF THE SERVICE WILL BE ACCURATE OR RELIABLE; OR (D) THE QUALITY OF ANY PRODUCTS, SERVICES, INFORMATION, OR OTHER MATERIAL PURCHASED OR OBTAINED BY YOU THROUGH THE SERVICE WILL MEET YOUR EXPECTATIONS. *** ## Limitation of Liability YOU EXPRESSLY UNDERSTAND AND AGREE THAT THE PAYGENTIC PARTIES WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY DAMAGES, OR DAMAGES FOR LOSS OF PROFITS INCLUDING DAMAGES FOR LOSS OF GOODWILL, USE, OR DATA OR OTHER INTANGIBLE LOSSES (EVEN IF THE PAYGENTIC PARTIES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES), WHETHER BASED ON CONTRACT, TORT, NEGLIGENCE, STRICT LIABILITY, OR OTHERWISE, RESULTING FROM: (A) THE USE OR THE INABILITY TO USE THE SERVICE; (B) THE COST OF PROCUREMENT OF SUBSTITUTE GOODS AND SERVICES RESULTING FROM ANY GOODS, DATA, INFORMATION, OR SERVICES PURCHASED OR OBTAINED OR MESSAGES RECEIVED OR TRANSACTIONS ENTERED INTO THROUGH OR FROM THE SERVICE; (C) UNAUTHORIZED ACCESS TO OR ALTERATION OF YOUR TRANSMISSIONS OR DATA; (D) STATEMENTS OR CONDUCT OF ANY THIRD PARTY ON THE SERVICE; OR (E) ANY OTHER MATTER RELATING TO THE SERVICE. IN NO EVENT WILL THE PAYGENTIC PARTIES' TOTAL LIABILITY TO YOU FOR ALL DAMAGES, LOSSES, OR CAUSES OF ACTION EXCEED THE AMOUNT RECEIVED BY PAYGENTIC FROM YOU IN THE LAST SIX (6) MONTHS, OR, IF GREATER, ONE HUNDRED DOLLARS (\$100). SOME JURISDICTIONS DO NOT ALLOW THE DISCLAIMER OR EXCLUSION OF CERTAIN WARRANTIES OR THE LIMITATION OR EXCLUSION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES. ACCORDINGLY, SOME OF THE ABOVE LIMITATIONS SET FORTH ABOVE MAY NOT APPLY TO YOU OR BE ENFORCEABLE WITH RESPECT TO YOU. IF YOU ARE DISSATISFIED WITH ANY PORTION OF THE SERVICE OR WITH THESE TERMS OF SERVICE, YOUR SOLE AND EXCLUSIVE REMEDY IS TO DISCONTINUE USE OF THE SERVICE. IF YOU ARE A USER FROM NEW JERSEY, THE FOREGOING SECTIONS TITLED "DISCLAIMER OF WARRANTIES" AND "LIMITATION OF LIABILITY" ARE INTENDED TO BE ONLY AS BROAD AS IS PERMITTED UNDER THE LAWS OF THE STATE OF NEW JERSEY. IF ANY PORTION OF THESE SECTIONS IS HELD TO BE INVALID UNDER THE LAWS OF THE STATE OF NEW JERSEY, THE INVALIDITY OF SUCH PORTION WILL NOT AFFECT THE VALIDITY OF THE REMAINING PORTIONS OF THE APPLICABLE SECTIONS. *** ## Dispute Resolution By Binding Arbitration – For Users Entering into these Terms of Service as Individuals **PLEASE READ THIS SECTION CAREFULLY AS IT AFFECTS YOUR RIGHTS.** ### a. Agreement to Arbitrate This Dispute Resolution by Binding Arbitration section is referred to in these Terms of Service as the "Arbitration Agreement." If you are entering into these Terms of Service as an individual (as opposed to on behalf of an entity), you agree that any and all disputes or claims that have arisen or may arise between you and Paygentic, whether arising out of or relating to these Terms of Service (including any alleged breach thereof), the Service, any advertising, or any aspect of the relationship or transactions between us, will be resolved exclusively through final and binding arbitration, rather than a court, in accordance with the terms of this Arbitration Agreement, except that you may assert individual claims in small claims court, if your claims qualify. Further, this Arbitration Agreement does not preclude you from bringing issues to the attention of federal, state, or local agencies, and such agencies can, if the law allows, seek relief against us on your behalf. You agree that, by entering into these Terms of Service, you and Paygentic are each waiving the right to a trial by jury or to participate in a class action. Your rights will be determined by a neutral arbitrator, not a judge or jury. The Federal Arbitration Act governs the interpretation and enforcement of this Arbitration Agreement. ### b. Prohibition of Class and Representative Actions and Non-Individualized Relief **YOU AND PAYGENTIC AGREE THAT EACH OF US MAY BRING CLAIMS AGAINST THE OTHER ONLY ON AN INDIVIDUAL BASIS AND NOT AS A PLAINTIFF OR CLASS MEMBER IN ANY PURPORTED CLASS OR REPRESENTATIVE ACTION OR PROCEEDING. UNLESS BOTH YOU AND PAYGENTIC AGREE OTHERWISE, THE ARBITRATOR MAY NOT CONSOLIDATE OR JOIN MORE THAN ONE PERSON'S OR PARTY'S CLAIMS AND MAY NOT OTHERWISE PRESIDE OVER ANY FORM OF A CONSOLIDATED, REPRESENTATIVE, OR CLASS PROCEEDING. ALSO, THE ARBITRATOR MAY AWARD RELIEF (INCLUDING MONETARY, INJUNCTIVE, AND DECLARATORY RELIEF) ONLY IN FAVOR OF THE INDIVIDUAL PARTY SEEKING RELIEF AND ONLY TO THE EXTENT NECESSARY TO PROVIDE RELIEF NECESSITATED BY THAT PARTY'S INDIVIDUAL CLAIM(S), EXCEPT THAT YOU MAY PURSUE A CLAIM FOR AND THE ARBITRATOR MAY AWARD PUBLIC INJUNCTIVE RELIEF UNDER APPLICABLE LAW TO THE EXTENT REQUIRED FOR THE ENFORCEABILITY OF THIS PROVISION.** ### c. Pre-Arbitration Dispute Resolution Paygentic is always interested in resolving disputes amicably and efficiently, and most customer concerns can be resolved quickly and to the customer's satisfaction by emailing customer support at [support@paygentic.io](mailto:support@paygentic.io). If such efforts prove unsuccessful, a party who intends to seek arbitration must first send to the other, by certified mail, a written Notice of Dispute ("Notice"). The Notice to Paygentic should be sent to Paygentic, Inc., 2443 Fillmore St #380-3755, San Francisco, CA 94115 ("Notice Address"). The Notice must (i) describe the nature and basis of the claim or dispute and (ii) set forth the specific relief sought. If Paygentic and you do not resolve the claim within sixty (60) calendar days after the Notice is received, you or Paygentic may commence an arbitration proceeding. During the arbitration, the amount of any settlement offer made by Paygentic or you will not be disclosed to the arbitrator until after the arbitrator determines the amount, if any, to which you or Paygentic is entitled. ### d. Arbitration Procedures Arbitration will be conducted by a neutral arbitrator in accordance with the American Arbitration Association's ("AAA") rules and procedures, including the AAA's Consumer Arbitration Rules (collectively, the "AAA Rules"), as modified by this Arbitration Agreement. For information on the AAA, please visit its website, [http://www.adr.org](http://www.adr.org). Information about the AAA Rules and fees for consumer disputes can be found at the AAA's consumer arbitration page, [https://www.adr.org/consumer](https://www.adr.org/consumer). If there is any inconsistency between any term of the AAA Rules and any term of this Arbitration Agreement, the applicable terms of this Arbitration Agreement will control unless the arbitrator determines that the application of the inconsistent Arbitration Agreement terms would not result in a fundamentally fair arbitration. The arbitrator must also follow the provisions of these Terms of Service as a court would. All issues are for the arbitrator to decide, including issues relating to the scope, enforceability, and arbitrability of this Arbitration Agreement. Although arbitration proceedings are usually simpler and more streamlined than trials and other judicial proceedings, the arbitrator can award the same damages and relief on an individual basis that a court can award to an individual under these Terms of Service and applicable law. Decisions by the arbitrator are enforceable in court and may be overturned by a court only for very limited reasons. Unless Paygentic and you agree otherwise, any arbitration hearings will take place in a reasonably convenient location for both parties with due consideration of their ability to travel and other pertinent circumstances. If the parties are unable to agree on a location, the determination will be made by AAA. If your claim is for $10,000 or less, Paygentic agrees that you may choose whether the arbitration will be conducted solely on the basis of documents submitted to the arbitrator, through a telephonic hearing, or by an in-person hearing as established by the AAA Rules. If your claim exceeds $10,000, the right to a hearing will be determined by the AAA Rules. Regardless of the manner in which the arbitration is conducted, the arbitrator will issue a reasoned written decision sufficient to explain the essential findings and conclusions on which the award is based. ### e. Costs of Arbitration Payment of all filing, administration, and arbitrator fees (collectively, the "Arbitration Fees") will be governed by the AAA Rules, unless otherwise provided in this Arbitration Agreement. If the value of the relief sought is $75,000 or less, at your request, Paygentic will pay all Arbitration Fees. If the value of relief sought is more than $75,000 and you are able to demonstrate to the arbitrator that you are economically unable to pay your portion of the Arbitration Fees or if the arbitrator otherwise determines for any reason that you should not be required to pay your portion of the Arbitration Fees, Paygentic will pay your portion of such fees. In addition, if you demonstrate to the arbitrator that the costs of arbitration will be prohibitive as compared to the costs of litigation, Paygentic will pay as much of the Arbitration Fees as the arbitrator deems necessary to prevent the arbitration from being cost-prohibitive. Any payment of attorneys' fees will be governed by the AAA Rules. ### f. Confidentiality All aspects of the arbitration proceeding, and any ruling, decision, or award by the arbitrator, will be strictly confidential for the benefit of all parties. ### g. Severability If a court or the arbitrator decides that any term or provision of this Arbitration Agreement (other than the subsection (b) above titled "Prohibition of Class and Representative Actions and Non-Individualized Relief" above) is invalid or unenforceable, the parties agree to replace such term or provision with a term or provision that is valid and enforceable and that comes closest to expressing the intention of the invalid or unenforceable term or provision, and this Arbitration Agreement will be enforceable as so modified. If a court or the arbitrator decides that any of the provisions of subsection (b) above titled "Prohibition of Class and Representative Actions and Non-Individualized Relief" are invalid or unenforceable, then the entirety of this Arbitration Agreement will be null and void, unless such provisions are deemed to be invalid or unenforceable solely with respect to claims for public injunctive relief. The remainder of these Terms of Service will continue to apply. ### h. Future Changes to Arbitration Agreement Notwithstanding any provision in these Terms of Service to the contrary, Paygentic agrees that if it makes any future change to this Arbitration Agreement (other than a change to the Notice Address) while you are a user of the Service, you may reject any such change by sending Paygentic written notice within thirty (30) calendar days of the change to the Notice Address provided above. By rejecting any future change, you are agreeing that you will arbitrate any dispute between us in accordance with the language of this Arbitration Agreement as of the date you first accepted these Terms of Service (or accepted any subsequent changes to these Terms of Service). *** ## Dispute Resolution By Binding Arbitration – For Users Entering into these Terms of Service on behalf of an Entity You and Paygentic intend that these Terms of Service are to be construed and enforced in accordance with the laws of the State of Delaware without regard to any conflict-of-law or choice-of-law rules, and that the rule of construction that provides that a document is construed against the maker thereof be inapplicable in the construction of any of the terms of these Terms of Service. Any dispute, claim, or controversy arising out of or relating in any way to these Terms of Service or the breach, termination, enforcement, interpretation, or validity thereof, including the determination of the scope or applicability of this agreement to arbitrate, shall be determined through confidential binding arbitration in the State of Delaware before one arbitrator. The confidential binding arbitration shall be administered by AAA pursuant to its Commercial Arbitration Rules, and you and Paygentic shall maintain the confidential nature of the arbitration proceeding and the award, including the hearing. Judgment on the award may be entered in any court having jurisdiction. *** ## Termination You agree that Paygentic, in its sole discretion, may suspend or terminate your account (or any part thereof) or use of the Service and remove and discard any content within the Service if Paygentic believes that you have violated or acted inconsistently with the letter or spirit of these Terms of Service. Any suspected fraudulent, abusive, or illegal activity that may be grounds for termination of your use of the Service, may be referred to appropriate law enforcement authorities. Paygentic may also in its sole discretion and at any time discontinue providing the Service, or any part thereof, with 30 days' prior written notice. You agree that any termination of your access to the Service under any provision of these Terms of Service may be effected without prior notice, and acknowledge and agree that Paygentic may immediately deactivate or delete your account and all related information and files in your account and/or bar any further access to such files or the Service. Further, you agree that Paygentic will not be liable to you or any third party for any termination of your access to the Service. Following termination, any remaining balance in your Paygentic account will be returned to you in the payment method you linked to your account; provided that we may delay the return of, or set off against, such remaining funds to cover any fines, penalties, or losses that we reasonably determine could be owed to us after the termination of your access to the Service. *** ## User Disputes You agree that you are solely responsible for your interactions with any other user in connection with the Service, and Paygentic will have no liability or responsibility with respect thereto. Paygentic reserves the right, but has no obligation, to become involved in any way with disputes between you and any other user of the Service. *** ## General These Terms of Service (together with the terms incorporated by reference herein) constitute the entire agreement between you and Paygentic governing your access and use of the Service, and supersede any prior agreements between you and Paygentic with respect to the Service. You also may be subject to additional terms and conditions that may apply when you use Third-Party Services, third-party content or third-party software. These Terms of Service will be governed by the laws of the State of Delaware without regard to its conflict of law provisions. With respect to any disputes or claims not subject to arbitration, as set forth above, you and Paygentic submit to the personal and exclusive jurisdiction of the state and federal courts located within the State of Delaware. The failure of Paygentic to exercise or enforce any right or provision of these Terms of Service will not constitute a waiver of such right or provision. If any provision of these Terms of Service is found by a court of competent jurisdiction to be invalid, the parties nevertheless agree that the court should endeavor to give effect to the parties' intentions as reflected in the provision, and the other provisions of these Terms of Service remain in full force and effect. You agree that regardless of any statute or law to the contrary, any claim or cause of action arising out of or related to use of the Service or these Terms of Service must be filed within one (1) year after such claim or cause of action arose or be forever barred. A printed version of these Terms of Service and of any notice given in electronic form will be admissible in judicial or administrative proceedings based upon or relating to these Terms of Service to the same extent and subject to the same conditions as other business documents and records originally generated and maintained in printed form. You may not assign these Terms of Service without the prior written consent of Paygentic, but Paygentic may assign or transfer these Terms of Service, in whole or in part, without restriction. The section titles in these Terms of Service are for convenience only and have no legal or contractual effect. As used in these Terms of Service, the words "include" and "including," and variations thereof, will not be deemed to be terms of limitation, but rather will be deemed to be followed by the words "without limitation." Notices to you may be made via either email or regular mail. The Service may also provide notices to you of changes to these Terms of Service or other matters by displaying notices or links to notices generally on the Service. Paygentic will not be in default hereunder by reason of any failure or delay in the performance of its obligations where such failure or delay is due to civil disturbances, riot, epidemic, hostilities, war, terrorist attack, embargo, natural disaster, acts of God, flood, fire, sabotage, fluctuations or unavailability of electrical power, network access or equipment, or any other circumstances or causes beyond Paygentic's reasonable control. *** ## U.S. Government Restricted Rights The Service is made available to the U.S. government with "RESTRICTED RIGHTS." Use, duplication, or disclosure by the U.S. government is subject to the restrictions contained in 48 CFR 52.227-19 and 48 CFR 252.227-7013 et seq. or its successor. Access or use of the Service (including the Software) by the U.S. government constitutes acknowledgement of our proprietary rights in the Service (including the Software). *** ## Questions? Concerns? Suggestions? Please contact us at [support@paygentic.io](mailto:support@paygentic.io) or Paygentic, Inc., 2443 Fillmore St #380-3755, San Francisco, CA 94115 to report any violations of these Terms of Service or to pose any questions regarding these Terms of Service or the Service. *** **\* \* \*** # Customer emails Source: https://docs.paygentic.io/platform/billing/customer-emails Learn which billing emails Paygentic sends to your customers and how to turn them off. Paygentic sends billing emails to your customers on your behalf. Customers receive an email when an invoice is due, when a payment is confirmed, when a subscription is about to renew, and when an automatic charge fails. Each email goes to the billing email addresses on the customer's organization (`billingEmails`). If none are set, Paygentic uses the customer's email address. ## Email types | Email | When Paygentic sends it | Setting | | - | - | - | | Invoice issued | An invoice is issued and the customer needs to pay it. The email includes the invoice and a link to pay. | `invoiceIssued` | | Payment failed | An automatic charge fails and Paygentic will retry it. The email includes the next retry date and a link to pay. | `invoiceIssued` | | Payment failed, final notice | Paygentic has stopped retrying a failed charge. The email includes a link to pay. | `invoiceIssued` | | Payment confirmation | An invoice is paid. The email includes the invoice. | `invoicePaid` | | Renewal reminder | A set number of days before a subscription renews. | `renewalReminder` | When a subscription uses automatic charges and the charge succeeds, the customer receives only the payment confirmation. To learn when the payment failed emails are sent, see [When an automatic charge fails](/platform/billing/subscriptions#when-an-automatic-charge-fails). > [!NOTE] > > The payment failed emails use the `invoiceIssued` setting. If you turn off `invoiceIssued` for a customer, they also stop receiving emails about failed payments. If you send your own invoice emails, make sure they cover failed payments too. ## Turn off emails for a customer All settings are on by default. To change them, update `notificationSettings` on the customer. Paygentic only changes the settings you include in the request. ```bash cURL theme={null} curl -X PATCH "https://api.sandbox.paygentic.io/v0/customers/cus_p1q2r3s4t5u6v7w8" \ -H "Authorization: Bearer sk_test_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "notificationSettings": { "invoicePaid": false } }' ``` ```javascript JavaScript theme={null} await fetch('https://api.sandbox.paygentic.io/v0/customers/cus_p1q2r3s4t5u6v7w8', { method: 'PATCH', headers: { 'Authorization': 'Bearer sk_test_YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ notificationSettings: { invoicePaid: false } }), }); ``` ```python Python theme={null} import requests requests.patch( "https://api.sandbox.paygentic.io/v0/customers/cus_p1q2r3s4t5u6v7w8", headers={"Authorization": "Bearer sk_test_YOUR_API_KEY"}, json={"notificationSettings": {"invoicePaid": False}}, ) ``` > [!NOTE] > > **API Reference**: See the [Update Customer endpoint](/api-reference/customers/update). ## Renewal reminders You set up renewal reminders on the plan. To turn them on, set `renewalReminderEnabled` to `true`, and set `renewalReminderDays` to the number of days before renewal to send the reminder. The number of days must be shorter than the billing period. To use different settings for one subscription, set the same fields on the subscription. To go back to the plan's settings, set them to `null`. A customer only receives renewal reminders if their `renewalReminder` setting is on. If the subscription uses automatic charges and the customer has no saved payment method, the reminder asks them to add one before the renewal date. ## Next steps * [Subscriptions](/platform/billing/subscriptions) * [Invoices](/platform/billing/invoices) * [Customer Lifecycle](/platform/billing/customer-lifecycle#customer-portal) # Customer Lifecycle Source: https://docs.paygentic.io/platform/billing/customer-lifecycle Complete guide to creating and managing customers through the API, including merchant-managed and full consumer accounts The customer lifecycle in Paygentic involves creating customer relationships, establishing subscriptions, and tracking usage. This guide covers the programmatic approach to managing customers through the API. ## Overview Paygentic supports two distinct types of consumer accounts, each with different capabilities and use cases: > [card] Managed Consumers > > Created via API by merchants for quick onboarding. Customers only access Paygentic in relation to this one merchant. > These customers do not have Paygentic users and only use Paygentic through the merchant integration. > [card] Full Consumer Accounts > > When the customer interacts with multiple merchants they can choose to keep everything in one account and sign in to Paygentic to manage their usage. Customers usually start as managed and only transition to a full account when needed. The key point for you is that funds in a managed account are exclusively available to your merchant integration. ## Creating customers via API ### Prerequisites * Valid merchant API key * Merchant account ID * Customer email and preferable address > [!NOTE] > > **API Reference**: See the [Create Customer API endpoint](/api-reference/customers/create-new-customer) for complete request and response schemas. > [tab] New Managed Consumer > > When creating a new customer with consumer data, you're establishing a managed consumer account: > > ```javascript JavaScript theme={null} > const axios = require('axios'); > > async function createManagedCustomer() { > try { > const response = await axios.post( > 'https://api.paygentic.io/v0/customers', > { > merchantId: 'org_YS8jkP59V71TdUvj', > consumer: { > name: 'John Doe', > email: 'john.doe@example.com', > phone: '+1-555-0100', > address: { > line1: '123 Main St', > city: 'San Francisco', > state: 'CA', > country: 'US', > zipCode: '94105' > } > } > }, > { > headers: { > 'Authorization': 'Bearer sk_live_YOUR_API_KEY', > 'Content-Type': 'application/json' > } > } > ); > > console.log('Customer created:', response.data.customerId); > return response.data.customerId; > } catch (error) { > console.error('Error creating customer:', error.response?.data); > throw error; > } > } > ``` > > ```bash cURL theme={null} > curl -X POST https://api.paygentic.io/v0/customers \ > -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "merchantId": "org_YS8jkP59V71TdUvj", > "consumer": { > "name": "John Doe", > "email": "john.doe@example.com", > "phone": "+1-555-0100", > "address": { > "line1": "123 Main St", > "city": "San Francisco", > "state": "CA", > "country": "US", > "zipCode": "94105" > } > } > }' > ``` > > ```python Python theme={null} > import requests > > def create_managed_customer(): > url = "https://api.paygentic.io/v0/customers" > > headers = { > "Authorization": "Bearer sk_live_YOUR_API_KEY", > "Content-Type": "application/json" > } > > payload = { > "merchantId": "org_YS8jkP59V71TdUvj", > "consumer": { > "name": "John Doe", > "email": "john.doe@example.com", > "phone": "+1-555-0100", > "address": { > "line1": "123 Main St", > "city": "San Francisco", > "state": "CA", > "country": "US", > "zipCode": "94105" > } > } > } > > try: > response = requests.post(url, json=payload, headers=headers) > response.raise_for_status() > > customer_id = response.json()["customerId"] > print(f"Customer created: {customer_id}") > return customer_id > except requests.exceptions.RequestException as e: > print(f"Error creating customer: {e}") > raise > ``` > [tab] Existing Managed Consumer > > If you've already created a managed consumer, you can reuse it: > > ```javascript JavaScript theme={null} > async function createCustomerWithExistingConsumer() { > try { > const response = await axios.post( > 'https://api.paygentic.io/v0/customers', > { > merchantId: 'org_YS8jkP59V71TdUvj', > consumerId: 'org_EXISTING_CONSUMER_ID' // Must be managed consumer > }, > { > headers: { > 'Authorization': 'Bearer sk_live_YOUR_API_KEY', > 'Content-Type': 'application/json' > } > } > ); > > return response.data.customerId; > } catch (error) { > // Error code 403: Attempting to use unauthorized consumerId > if (error.response?.status === 403) { > console.error('Cannot use this consumerId - not a managed consumer'); > } > throw error; > } > } > ``` > > ```bash cURL theme={null} > curl -X POST https://api.paygentic.io/v0/customers \ > -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "merchantId": "org_YS8jkP59V71TdUvj", > "consumerId": "org_EXISTING_CONSUMER_ID" > }' > ``` > > ```python Python theme={null} > def create_customer_with_existing_consumer(): > url = "https://api.paygentic.io/v0/customers" > > headers = { > "Authorization": "Bearer sk_live_YOUR_API_KEY", > "Content-Type": "application/json" > } > > payload = { > "merchantId": "org_YS8jkP59V71TdUvj", > "consumerId": "org_EXISTING_CONSUMER_ID" # Must be managed consumer > } > > try: > response = requests.post(url, json=payload, headers=headers) > response.raise_for_status() > return response.json()["customerId"] > except requests.exceptions.HTTPError as e: > if e.response.status_code == 403: > print("Cannot use this consumerId - not a managed consumer") > raise > ``` > [!NOTE] > > **Idempotency**: If a customer already exists for the consumer-merchant pair, the API returns `200` with the existing customer ID instead of creating a duplicate. ## Creating subscriptions Once you have a customer, you can create subscriptions. The plan you choose determines which [fees](/platform/pricing/fees) and usage-based prices apply. Customers must pay prepaid fees before the subscription starts. The subscription response includes a payment link where the customer can pay for this charge. > [!NOTE] > > **API Reference**: See the [Create Subscription API endpoint](/api-reference/subscription/create-new-subscription) for complete request and response schemas. ```javascript JavaScript theme={null} async function createPostpaidSubscription(customerId, planId) { try { const response = await axios.post( 'https://api.paygentic.io/v0/subscriptions', { customerId: customerId, planId: planId, name: 'Monthly API Service', startedAt: new Date().toISOString() }, { headers: { 'Authorization': 'Bearer sk_live_YOUR_API_KEY', 'Content-Type': 'application/json' } } ); const subscription = response.data; console.log('Subscription created:', subscription.id); console.log('Payment link (if payment is required):', subscription.payment?.checkoutUrl); return subscription; } catch (error) { console.error('Error creating subscription:', error.response?.data); throw error; } } ``` ```python Python theme={null} from datetime import datetime def create_postpaid_subscription(customer_id, plan_id): url = "https://api.paygentic.io/v0/subscriptions" headers = { "Authorization": "Bearer sk_live_YOUR_API_KEY", "Content-Type": "application/json" } payload = { "customerId": customer_id, "planId": plan_id, # Must be a postpaid plan "name": "Monthly API Service", "startedAt": datetime.utcnow().isoformat() + "Z" } try: response = requests.post(url, json=payload, headers=headers) response.raise_for_status() subscription = response.json() print(f"Subscription created: {subscription['id']}") print(f"Payment details (if payment is required): {subscription.get('payment')}") return subscription except requests.exceptions.RequestException as e: print(f"Error creating subscription: {e}") raise ``` ### Starting a subscription in the past You can set `startedAt` to a date in the past, for example when you move a customer from another billing system or bill a customer for time they already used. A start is **backdated** when `startedAt` is more than 24 hours before you create the subscription. For a backdated start, `elapsedPeriodBilling` decides what Paygentic bills for the periods that have already passed: | `elapsedPeriodBilling` | What Paygentic bills | When to use it | | - | - | - | | `none` (default) | Only charges that fall due from the moment you create the subscription. The subscription is `active` immediately and Paygentic doesn't issue Invoice 0. | Another system already billed the customer for the earlier periods. | | `per_period` | Every charge that fell due from `startedAt`, on one Invoice 0. The subscription is `pending_payment` until the customer pays it. | You want to bill the customer for the periods that have passed. | `elapsedPeriodBilling` has no effect on a start that isn't backdated. A subscription that starts less than 24 hours ago, or in the future, bills from `startedAt` with either value, so you can send the field on every request. #### Example You create a subscription on 7 October with `startedAt` set to 10 August. The plan bills monthly, with a fee charged in advance and a fee charged in arrears. The in-advance fee for each period falls due at the start of the period, and the in-arrears fee falls due at the end. | Charge | Falls due | `none` | `per_period` | | - | - | - | - | | In-advance fee, 10 August to 10 September | 10 August | Not billed | Invoice 0 | | In-arrears fee, 10 August to 10 September | 10 September | Not billed | Invoice 0 | | In-advance fee, 10 September to 10 October | 10 September | Not billed | Invoice 0 | | In-arrears fee, 10 September to 10 October | 10 October | Billed | Billed | | In-advance fee, 10 October to 10 November | 10 October | Billed | Billed | With `none`, the in-arrears fee for 10 September to 10 October is billed in full, because it falls due after you created the subscription. Paygentic doesn't prorate it. If the other system already billed the customer for part of that period, take this into account. With `per_period`, Invoice 0 is due according to its payment terms, counted from the day you create the subscription. If you also set `activateImmediately` to `true`, the subscription is `active` immediately, and Paygentic still issues Invoice 0. #### Usage in elapsed periods The elapsed periods of a backdated start bill fees only, with either `elapsedPeriodBilling` value. The period you create the subscription in bills usage in one of two ways: * **A price with a metered feature** counts usage from the moment you create the subscription. Earlier usage in the period is never billed and never draws down the allowance. See [Usage dated in the past](/platform/billing/metered-entitlements#usage-dated-in-the-past). * **A usage price without a metered feature** reads the meter for the whole period, so usage dated earlier in the period is billed. To build a history of usage and invoices, for example in the sandbox, start a test clock in the past instead of backdating the subscription. See [Simulating time](/getting-started/environments#simulating-time). ```bash cURL theme={null} curl -X POST "https://api.paygentic.io/v0/subscriptions" \ -H "Authorization: Bearer sk_test_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "customerId": "cus_a1b2c3d4e5f6g7h8", "planId": "plan_h8g7f6e5d4c3b2a1", "name": "Monthly API Service", "startedAt": "2026-08-10T00:00:00Z", "elapsedPeriodBilling": "none" }' ``` ```javascript JavaScript theme={null} const response = await fetch('https://api.paygentic.io/v0/subscriptions', { method: 'POST', headers: { 'Authorization': 'Bearer sk_test_YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ customerId: 'cus_a1b2c3d4e5f6g7h8', planId: 'plan_h8g7f6e5d4c3b2a1', name: 'Monthly API Service', startedAt: '2026-08-10T00:00:00Z', elapsedPeriodBilling: 'none', }), }); const subscription = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( "https://api.paygentic.io/v0/subscriptions", headers={"Authorization": "Bearer sk_test_YOUR_API_KEY"}, json={ "customerId": "cus_a1b2c3d4e5f6g7h8", "planId": "plan_h8g7f6e5d4c3b2a1", "name": "Monthly API Service", "startedAt": "2026-08-10T00:00:00Z", "elapsedPeriodBilling": "none", }, ) subscription = response.json() ``` #### Limits * With `per_period`, `startedAt` can be at most 12 months before you create the subscription. An earlier date returns `400 Bad Request`. * With `none`, `startedAt` can be up to 10 years in the past. If you set `testClockId`, Paygentic measures the 24 hours and both limits from the test clock's time instead of the current time. #### The billing start The subscription response includes two fields: | Field | Description | | - | - | | `elapsedPeriodBilling` | The value you chose when you created the subscription. It is `null` for subscriptions created before this field existed. | | `billingStartsAt` | The billing start. Paygentic bills a charge only if it falls due at or after this time. For a backdated start with `none`, it is the moment you created the subscription. Otherwise, it is `startedAt`. It never changes. | If you send the same create request again while the subscription is `active` or `pending_payment`, Paygentic returns the existing subscription. If the new request has a different `elapsedPeriodBilling`, Paygentic returns `409 Conflict`. A request without `elapsedPeriodBilling` counts as `none`. ## Customer portal The customer portal allows your customers to view their subscription details, usage metrics, invoices, and manage payment sources - all within a secure, hosted interface. ### Generating portal links > [tab] Managed Consumer Portal > > For managed consumers, generate portal links via the subscription endpoint: > > > [!NOTE] > > > > **API Reference**: See the [Generate Portal Link API endpoint](/api-reference/subscriptions/generate-customer-portal-access-link) for complete request and response schemas. > > ```javascript JavaScript theme={null} > async function generatePortalLink(subscriptionId) { > try { > const response = await axios.post( > `https://api.paygentic.io/v0/subscriptions/${subscriptionId}/portal`, > {}, > { > headers: { > 'Authorization': 'Bearer sk_live_YOUR_API_KEY', > 'Content-Type': 'application/json' > } > } > ); > > const portalUrl = response.data.url; > console.log('Portal URL:', portalUrl); > return portalUrl; > } catch (error) { > console.error('Error generating portal link:', error.response?.data); > throw error; > } > } > ``` > > ```bash cURL theme={null} > curl -X POST https://api.paygentic.io/v0/subscriptions/{subscriptionId}/portal \ > -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{}' > ``` > > ```python Python theme={null} > import requests > > def generate_portal_link(subscription_id): > url = f"https://api.paygentic.io/v0/subscriptions/{subscription_id}/portal" > > headers = { > "Authorization": "Bearer sk_live_YOUR_API_KEY", > "Content-Type": "application/json" > } > > try: > response = requests.post(url, json={}, headers=headers) > response.raise_for_status() > > portal_url = response.json()["url"] > print(f"Portal URL: {portal_url}") > return portal_url > except requests.exceptions.RequestException as e: > print(f"Error generating portal link: {e}") > raise > ``` > > This provides read-only access to subscription data, source management, and usage tracking. > [tab] Full Platform Access > > Full consumer accounts have complete platform access at `platform.paygentic.io` with: > > * Account management > * Payment method management > * Full subscription control > * Usage history and invoices ### Embedding the portal You can embed the customer portal directly into your application, providing a seamless experience without redirecting users away. #### Setup requirements Before embedding: 1. **Domain whitelisting**: Contact [support@paygentic.io](mailto:support@paygentic.io) to whitelist your domain(s) 2. **CSP configuration**: Add `platform.paygentic.io` to your CSP `frame-src` directive: ```text theme={null} Content-Security-Policy: frame-src 'self' https://platform.paygentic.io; ``` #### Implementation ```html HTML theme={null} ``` ```jsx React theme={null} export function CustomerPortal({ portalUrl }) { return ( ``` ```jsx React theme={null} import { useEffect } from 'react'; export function PaymentCheckout({ paymentUrl, onSuccess, onError }) { useEffect(() => { const handleMessage = (event) => { if (event.origin !== 'https://platform.paygentic.io') return; if (event.data?.type === 'payment_success') { onSuccess?.(); } else if (event.data?.type === 'payment_error') { onError?.(); } }; window.addEventListener('message', handleMessage); return () => window.removeEventListener('message', handleMessage); }, [onSuccess, onError]); return (