List plans and create checkout
Plans accepts pk_ or sk_; other billing methods require a server-side sk_. Plan includes code, name, amount in cents, currency, and interval; the Go struct drops every other field of the API response. The list itself includes trial, pay-in-arrears and pending-deletion plans, and with a pk_ key the full plans are readable by anyone who has the key. See the public plan catalog. Upsert the customer with UpsertCustomer before billing.
CheckoutResult.Type explicitly:
A paid upgrade returns
plan_upgrade_intent_id instead of invoice_id on stripe and razorpay results. On scheduled, SubscriptionID is the pending subscription. In v0.9.1, URL, PublishableKey, StripeAccount and PendingSubscriptionID were removed from CheckoutResult because checkout never returned them; code that reads them no longer compiles. CheckoutResult decodes expires_at, customer_id, recurring, mandate_max_amount_cents, plan_upgrade_intent_id, plan_code, payment_source, transition_direction, transition_policy, external_entity_id and external_subscription_id.
Checkout errors: 400 invalid_return_url when the return_url origin is not allowed (checked before anything else); 404 plan_not_found or customer_not_found; 409 subscription_selection_required when the customer has several active subscriptions and no SubscriptionID was given; 422 checkout_not_required when the plan needs no up-front payment (free, trial, or pay-in-arrears) and the customer has no subscription, so use Subscribe instead; 422 payment_provider_required when no payment provider is connected; 422 plan_already_active when the customer is already on that plan; 409 subscription_checkout_in_progress when a payment for the customer’s new-subscription checkout on a different plan is still processing, or it was paid (an abandoned checkout is replaced instead, and the same plan reopens it).
Manage a payment method
sk_ key. A pk_ key is refused with 403 (no error code, only a message). Nozle stores no card data: the customer changes their payment method in the Stripe Billing Portal. Razorpay customers pay each invoice through a Razorpay payment link, so for them the call fails with 422 razorpay_pays_by_link.
See Manage Payment Method for the HTTP contract and error codes.
Direct subscription and cancellation
Subscribe and CancelSubscription expose the returned nested Subscription and fill the convenience SubscriptionID and Status fields.
UpsertCustomer first; an unknown customer returns 404 customer_not_found and nothing is created. Calling Subscribe again for the same customer and plan returns the same subscription. Use direct subscription only when payment is not required: Subscribe accepts a paid plan without collecting payment. Cancellation accepts end_of_period or immediate.
Subscribe to another plan adds a second active subscription. It does not replace the first, and plan credit grants are granted again. To move a customer, call Checkout with SubscriptionID (needs a transition policy), or cancel and then subscribe. Pass the new subscription ID as SubscriptionID to Track.
Subscription self-service
Derive the customer from the authenticated application user and validate ownership of the selected external subscription ID. Do not pass Core’s internal UUID. These methods support the React billing portal. Changing an existing subscription’s plan needs a transition policy for that source and target plan pair. Without one, preview, checkout, and transitions return422 plan_transition_policy_required. Exception: from a $0 plan to a paid plan, the organization’s free-to-paid default applies without a pair policy.
Load options and preview a quote
CheckoutResult.Type distinguishes stripe, razorpay, hosted, processing, completed, and scheduled. Payment fulfillment is authoritative on the server. Use CheckoutStatus and VerifyCheckout with a CheckoutScope containing both customer and external subscription IDs when recovering payment.
For a signed plan-change quote, call SubscriptionOptions, then PreviewSubscriptionChange. Pass its QuoteID and the external SubscriptionID to Checkout. A quote can expire; ask the customer to confirm a fresh one after a 409.
SubscriptionOptions contains the current subscription, pending change, eligible plans, and checkout as JSON values. SubscriptionChangePreview contains the signed quote, direction, timing, EffectiveAt, RenewalAt, and exact json.Number amounts including AmountDueNowCents and AmountDueAtEffectiveCents. The API also returns transition_policy, billing_anchor, proration_behavior, and credit_action, which the type omits. Show server-provided eligibility, amounts, and dates before confirmation.
Confirm a paid upgrade
completed with payment_source: "credits" and creates a $0 invoice. An upgrade checkout to a pay-in-arrears plan returns 422 plan_upgrade_invoice_missing.
Schedule or withdraw a downgrade
PreviewSubscriptionTransition and ApplySubscriptionTransition support cancel, downgrade, and uncancel. Apply requires a caller-supplied idempotency key. WithdrawPendingSubscriptionChange requires the exact pending change ID. CancelSubscription provides the simpler immediate or end-of-period cancellation path.
{subscription: {id, external_id, plan_code, status}, withdrawn_pending_subscription_id, replayed}; the same key returns the same body with replayed: true.
A new scheduled change while a change is pending replaces it with a new pending ID. A paid upgrade checkout is refused with 409 subscription_change_pending while a downgrade or cancellation is scheduled: withdraw the downgrade, or keep the subscription, first. Scheduling a change or cancelling at period end cancels an open upgrade checkout. Withdrawing the replaced ID returns 409 pending_subscription_changed. An unknown ID returns 404 pending_subscription_not_found.
PreviewSubscriptionTransition and ApplySubscriptionTransition use the Timing you pass even when the pair’s transition policy says otherwise; Checkout always follows the policy. A downgrade on a pair whose policy direction is upgrade returns 422 target_plan_is_not_a_downgrade.
Cancel at period end and Keep
Scope payment recovery and verification
Entity subscriptions
Entity subscription methods includeEnsureEntitySubscription, GetEntitySubscription, ListEntitySubscriptions, CheckoutEntitySubscription, ChangeEntitySubscriptionPlan, CancelEntitySubscription, and RemoveEntitySubscription. CancelEntitySubscription returns EntitySubscriptionCancelResult with the Entity subscription and transition settlement details.
BillingTime accepts only calendar or anniversary. Single Entity checkout also accepts free, trial, and pay-in-arrears plans; it returns completed with payment_source: "none". ChangeEntitySubscriptionPlan needs a transition policy for the plan pair and does not send BillingTime. It returns scheduled or completed, plus ExternalEntityID and ExternalSubscriptionID. CancelEntitySubscription on a pay-in-arrears plan without CreditAction returns 422 with credit_action: not_supported_for_pay_in_arrears. RemoveEntitySubscription on an Entity with billing history returns 403 entity_subscription_has_billing_history.
Buy several Entity plans together
CheckoutEntitySubscriptions buys plans for several Entities with one payment. Do not loop over CheckoutEntitySubscription: that creates separate invoices and payments.
EntitySubscriptionCheckoutManyResult contains ID, Type (stripe, razorpay, processing, or completed), Status (pending, open, completed, failed, or expired), ClientSecret, InvoiceID, AmountCents, Currency, Replayed, ExpiresAt, and Items with each Entity’s external IDs, plan code, and subscription status. Razorpay results add CheckoutID, KeyID, and OrderID.
Send 1 to 100 unique Entities. The idempotency key is required, up to 255 bytes, and sent as the Idempotency-Key header. The same key and request returns Replayed: true and reuses the open session; replaying a failed or expired batch returns checkout_not_available. The checkout expires after 23 hours.
Every plan must require up-front payment: pay in advance with an amount above 0 and no trial, or pay-in-advance fixed charges. Otherwise the whole batch fails with 422 validation_errors and error_details.items: ["paid_plan_required"]. Other item errors are mixed_currencies and mixed_intervals. An untrusted return URL returns 422 with return_url: invalid_or_untrusted. With no payment provider connected, the call returns 422 payment_provider_required, as single checkout does.
See Entity subscriptions for lifecycle and payment behavior, and bulk Entity checkout.
Settlement transitions
For configured settlement policies, preview and apply withSubscriptionTransitionParams. Apply keys are limited to 255 UTF-8 bytes. See Subscriptions for valid combinations.
Read usage
Fromv0.12.0.
CustomerUsage with FromDatetime, ToDatetime, Currency, AmountCents, TotalAmountCents and ChargesUsage (units and amount per charge and feature). Pass a subscription ID instead of "" to read a specific subscription.
Without a subscription ID, the customer’s one active subscription is used, and a customer with none or several gets an error. The client remembers that subscription, as Track does, and shares it between Track, CurrentUsage and PastUsage. Checkout, CheckoutInvoice, CheckoutStatus, VerifyCheckout, Subscribe, CancelSubscription and ApplySubscriptionTransition forget it. A change made elsewhere, such as in the dashboard, is not seen, so pass the subscription ID when that matters.
Invoices
Fromv0.12.0.
ListInvoicesParams filters the list, newest first. Empty fields are not sent:
CheckoutInvoice.
A PDF is generated the first time it is asked for, so the download call returns no URL until it exists; ask again a few seconds later, or wait for the invoice.generated webhook.
Alerts
Fromv0.12.0.
current_usage_amount, feature_current_usage_amount and feature_current_usage_units (the feature_* ones need a feature code). Wallet alert types are wallet_balance_amount, wallet_credits_balance, wallet_ongoing_balance_amount and wallet_credits_ongoing_balance. Threshold values are cents, units or credits by type, and at most one threshold is recurring. Nozle sends the alert.triggered webhook when a threshold is crossed; verify it before acting.