# yRecurring Developer Documentation

> yRecurring is subscription and usage billing software for anything sold on repeat: software, AI and API products, memberships, media and services. Its typed JSON REST API (bearer-authenticated, idempotent mutations, RFC 7807 errors) lives at https://app.yrecurring.com/v1.

## API reference

- [OpenAPI 3.1 specification](https://docs.yrecurring.com/openapi.json): the complete machine-readable API contract, generated from the running code
- [API reference (human)](https://docs.yrecurring.com/reference): browsable three-column reference with examples

## Docs

- [Developer docs home](https://docs.yrecurring.com/): quickstart and the API's core conventions

## Product guide

- [Full guide corpus](https://docs.yrecurring.com/llms-full.txt): every public guide page as one markdown file
- [Plans, add-ons and charges](https://docs.yrecurring.com/guide/product-catalog/products.md): The three kinds of catalog item, how groups organize them, and which add-ons go with which plans.
- [Prices](https://docs.yrecurring.com/guide/product-catalog/prices.md): A price is a variant of a product, and a product can have many.
- [How the catalog becomes a subscription](https://docs.yrecurring.com/guide/product-catalog/building-a-subscription.md): How products, prices, and subscription items fit together, and what a customer is charged at signup.
- [Changing a price](https://docs.yrecurring.com/guide/product-catalog/price-versioning.md): Replace a price without disrupting the customers already on it.
- [Switching from another platform](https://docs.yrecurring.com/guide/product-catalog/switching-from-another-platform.md): What Stripe, Chargebee, Recurly, Maxio and Paddle call the things in your catalog here.
- [Flat fee](https://docs.yrecurring.com/guide/pricing-models/flat-fee.md): Charge one fixed amount per billing period, no matter the quantity or usage.
- [Per unit](https://docs.yrecurring.com/guide/pricing-models/per-unit.md): Charge a fixed price for each unit, seat, or block of usage, with an optional free allowance.
- [Tiered](https://docs.yrecurring.com/guide/pricing-models/tiered.md): Split the quantity into bands and charge each band at its own rate, then add them up.
- [Volume](https://docs.yrecurring.com/guide/pricing-models/volume.md): Find the band the total quantity lands in, then charge every unit at that band's rate.
- [Stairstep](https://docs.yrecurring.com/guide/pricing-models/stairstep.md): Charge one flat price for the whole band the quantity lands in, ignoring the exact count.
- [Package](https://docs.yrecurring.com/guide/pricing-models/package.md): Sell units in fixed blocks and charge per block, rounding partial blocks up.
- [Percentage](https://docs.yrecurring.com/guide/pricing-models/percentage.md): Charge a percentage of an amount, for transaction fees and revenue share.
- [Dynamic (you set the cost)](https://docs.yrecurring.com/guide/pricing-models/dynamic.md): Bill the exact cost your app computes per event, with an optional markup. Built for AI usage.
- [The subscription lifecycle](https://docs.yrecurring.com/guide/subscriptions/lifecycle.md): The six states a subscription can be in, and the rules for moving between them.
- [Free trials](https://docs.yrecurring.com/guide/subscriptions/trials.md): Let a customer use a plan free for a set number of days before billing starts.
- [Changing a subscription](https://docs.yrecurring.com/guide/subscriptions/changing-a-subscription.md): Add or remove items, change quantity or price, now or on a future date.
- [Pausing and resuming](https://docs.yrecurring.com/guide/subscriptions/pausing-and-resuming.md): Suspend billing for a while, then pick up where you left off.
- [Cancelling](https://docs.yrecurring.com/guide/subscriptions/cancelling.md): End a subscription now or at a future date, and undo a scheduled cancellation.
- [How proration works](https://docs.yrecurring.com/guide/proration/how-proration-works.md): The credit and charge that keep a mid-period plan change fair, computed day by day.
- [In advance or in arrears](https://docs.yrecurring.com/guide/billing-timing/in-advance-and-in-arrears.md): Charge at the start of a period or at the end.
- [Anniversary and calendar billing](https://docs.yrecurring.com/guide/billing-timing/anniversary-and-calendar-billing.md): Bill each customer on their own start day, or align everyone to one day of the month.
- [The invoice lifecycle](https://docs.yrecurring.com/guide/invoices/invoice-lifecycle.md): The states an invoice moves through, from draft to paid.
- [How invoices are generated](https://docs.yrecurring.com/guide/invoices/how-invoices-are-generated.md): The reasons an invoice is created, from a renewal to a manual bill.
- [Invoice numbering](https://docs.yrecurring.com/guide/invoices/invoice-numbering.md): How invoices are numbered, and how to set the prefix and format.
- [The hosted invoice page](https://docs.yrecurring.com/guide/invoices/hosted-invoice-page.md): A shareable link where a customer can view and pay an invoice without signing in.
- [Explain this invoice in plain English](https://docs.yrecurring.com/guide/invoices/explain-this-invoice.md): One button that turns an invoice into a short, plain summary of what the customer is paying for, why it changed from last time, and what to expect next.
- [Hosted checkout](https://docs.yrecurring.com/guide/checkout/hosted-checkout.md): Build a self-serve signup page, and choose what it asks and where it sends people.
- [The buyer's language](https://docs.yrecurring.com/guide/checkout/buyer-language.md): How hosted checkout, invoice and card-update pages pick a language, what gets translated, and what deliberately stays in English.
- [Payment page protection](https://docs.yrecurring.com/guide/checkout/payment-page-protection.md): Why a checkout, invoice pay link or card-update link can temporarily stop accepting payments, and what to do.
- [Connecting a payment gateway](https://docs.yrecurring.com/guide/payments/connecting-a-gateway.md): Connect Stripe, choose test or live keys, set the payment experience, and verify everything with test cards before real money moves.
- [Recording payments](https://docs.yrecurring.com/guide/payments/recording-payments.md): Take payment online through a gateway, or record money you received another way.
- [Automatic collection](https://docs.yrecurring.com/guide/payments/automatic-collection.md): Charge a customer's saved card automatically when a subscription invoice is finalized.
- [Saved cards and the update-card link](https://docs.yrecurring.com/guide/payments/saved-cards.md): How a customer's card gets on file, which card is charged, the shareable update-card link, and the email a card change sends.
- [Refunds](https://docs.yrecurring.com/guide/payments/refunds.md): Give money back, and decide whether the customer still owes it.
- [Credit notes](https://docs.yrecurring.com/guide/payments/credit-notes.md): Credit a customer's account without moving cash, and record why.
- [Stripe](https://docs.yrecurring.com/guide/payment-gateways/stripe.md): Connect Stripe to collect cards and wallets in 31 currencies, embedded on your pages or on Stripe's hosted checkout.
- [Adyen](https://docs.yrecurring.com/guide/payment-gateways/adyen.md): Connect Adyen to collect cards in 33 currencies, embedded with Drop-in or on a hosted payment link, with webhooks doing the settling.
- [PayPal](https://docs.yrecurring.com/guide/payment-gateways/paypal.md): Let customers pay from their PayPal balance alongside your card gateway, with saved wallets for automatic renewals.
- [GoCardless](https://docs.yrecurring.com/guide/payment-gateways/gocardless.md): Collect bank debits by mandate over Bacs, SEPA and ACH, with payments that settle over banking days and confirm by webhook.
- [Authorize.Net](https://docs.yrecurring.com/guide/payment-gateways/authorize-net.md): Collect US card payments through your Authorize.Net merchant account, with hosted payment pages and saved customer profiles.
- [Paystack](https://docs.yrecurring.com/guide/payment-gateways/paystack.md): Collect cards in Naira, Cedi, Rand, Shilling and US Dollars, with one key to configure and cards saved as they pay.
- [Flutterwave](https://docs.yrecurring.com/guide/payment-gateways/flutterwave.md): Collect cards and mobile money across Africa on Flutterwave's hosted page, with each payment recorded as what it really was.
- [Braintree](https://docs.yrecurring.com/guide/payment-gateways/braintree.md): Connect Braintree to collect cards on your own pages with the Drop-in form, with saved cards for automatic renewals.
- [Meters](https://docs.yrecurring.com/guide/usage/meters.md): Define what you measure, and how the period's events roll up into one number.
- [Recording usage](https://docs.yrecurring.com/guide/usage/recording-usage.md): Report usage events, correct mistakes, and avoid double counting.
- [Wallets](https://docs.yrecurring.com/guide/wallets/wallets.md): A prepaid balance a customer tops up and draws down.
- [Pricing units](https://docs.yrecurring.com/guide/wallets/pricing-units.md): Name your own credits or tokens and set prices in them.
- [Coupons](https://docs.yrecurring.com/guide/coupons/coupons.md): A code that discounts the bill, by a percentage or a fixed amount.
- [Applying a coupon to a subscription](https://docs.yrecurring.com/guide/coupons/applying-coupons.md): Attach a coupon, let it run for its duration, and remove it.
- [How dunning works](https://docs.yrecurring.com/guide/dunning/how-dunning-works.md): The recovery run that opens when a payment fails, and how it ends.
- [The retry schedule](https://docs.yrecurring.com/guide/dunning/the-retry-schedule.md): When retries happen after a failed payment, and how to change the timing.
- [Workflows](https://docs.yrecurring.com/guide/automation/workflows.md): Automate a response to a billing event with a trigger, conditions, and steps.
- [Workflow actions](https://docs.yrecurring.com/guide/automation/workflow-actions.md): The things a workflow can do, and the ones that need permission.
- [Outbound webhooks](https://docs.yrecurring.com/guide/automation/outbound-webhooks.md): Signed HTTP notifications to your servers when billing events happen, and how to verify them.
- [Slack](https://docs.yrecurring.com/guide/integrations/slack.md): Post billing events to your Slack channels, and choose exactly which ones.
- [HubSpot](https://docs.yrecurring.com/guide/integrations/hubspot.md): Keep your HubSpot contacts and your billing records in step, in one direction or both.
- [QuickBooks and Xero](https://docs.yrecurring.com/guide/integrations/accounting.md): Send your invoices, payments and credit notes straight into your accounting system.
- [QuickBooks Online](https://docs.yrecurring.com/guide/integrations/quickbooks.md): Every setting on the QuickBooks connection, what it does, and how your documents appear in your company file.
- [Xero](https://docs.yrecurring.com/guide/integrations/xero.md): Every setting on the Xero connection, what it does, and how your documents appear in your organisation.
- [Avalara](https://docs.yrecurring.com/guide/integrations/avalara.md): Automatic sales tax, VAT, and GST on every invoice, computed by AvaTax with your manual rates as the fallback.
- [Send from your own mailbox (Gmail / Microsoft 365)](https://docs.yrecurring.com/guide/integrations/email-mailbox.md): Connect a Google Workspace or Microsoft 365 mailbox and yRecurring sends invoices and receipts as that mailbox, with no SMTP setup.
- [The customer portal](https://docs.yrecurring.com/guide/portal/customer-portal.md): What the portal offers, how customers sign in, and what you can let them do.
- [Tax rates](https://docs.yrecurring.com/guide/taxes/tax-rates.md): Define rates for countries and regions, stack components like GST and PST, and schedule rate changes ahead of time.
- [How tax is applied](https://docs.yrecurring.com/guide/taxes/how-tax-is-applied.md): Which lines get taxed, tax-inclusive versus exclusive, and what happens when a rate is missing.
- [EU VAT and reverse charge](https://docs.yrecurring.com/guide/taxes/eu-vat.md): Validate customer VAT IDs against VIES and invoice cross-border EU business customers at 0%.
- [Features](https://docs.yrecurring.com/guide/entitlements/features.md): The three kinds of entitlement, and the codes your app checks.
- [How entitlements resolve and enforce](https://docs.yrecurring.com/guide/entitlements/how-entitlements-resolve.md): Plan defaults, per-subscription overrides, and how a grant is checked.
- [Custom fields](https://docs.yrecurring.com/guide/custom-fields/custom-fields.md): Add your own fields to customers, subscriptions, invoices, and more.
- [Custom modules](https://docs.yrecurring.com/guide/custom-fields/custom-modules.md): Define a whole new kind of record, with its own fields.
- [Running an import](https://docs.yrecurring.com/guide/import/running-an-import.md): Upload a file, preview every row, then commit, safely.
- [What you can import](https://docs.yrecurring.com/guide/import/what-you-can-import.md): The records you can bring in, the order they go in, and how re-imports match.
- [Migrating saved payment methods](https://docs.yrecurring.com/guide/import/migrating-payment-methods.md): Bring your customers' saved cards and mandates from your old billing system without anyone re-entering a card.
- [Exporting data](https://docs.yrecurring.com/guide/import/exporting-data.md): Take your data out of yRecurring, as files you can keep or move elsewhere.
- [Saved views](https://docs.yrecurring.com/guide/lists/saved-views.md): Save a list's filters, search, sort, and columns under a name, and come back to it in one click.
- [Exporting a list to CSV](https://docs.yrecurring.com/guide/lists/csv-export.md): Download any list as a CSV file that matches exactly what is on screen.
- [Bulk actions](https://docs.yrecurring.com/guide/lists/bulk-actions.md): Select many rows and act on all of them in one go, with a clear confirmation first.
- [Command palette and keyboard shortcuts](https://docs.yrecurring.com/guide/lists/command-palette-and-keyboard.md): Jump to any record or page with one shortcut, and drive lists without the mouse.
- [Dark mode](https://docs.yrecurring.com/guide/lists/dark-mode.md): Switch the app between light and dark, or let it follow your device.
- [Team members](https://docs.yrecurring.com/guide/team/team-members.md): Invite people into your organization and set what they can do.
- [Roles and permissions](https://docs.yrecurring.com/guide/team/roles-and-permissions.md): How a role bundles permissions, and how to make your own.
- [Two-factor authentication](https://docs.yrecurring.com/guide/team/two-factor-authentication.md): Protect your sign-in with a code from an authenticator app.
- [Sign-in protection](https://docs.yrecurring.com/guide/team/sign-in-protection.md): What happens after repeated failed sign-ins, and why it is a delay rather than a lockout.
- [Tags](https://docs.yrecurring.com/guide/tags/tags.md): Label records with your own colored tags, then filter by them.
- [Billing entities](https://docs.yrecurring.com/guide/billing-entities/billing-entities.md): Invoice under separate names, tax ids, and branding from one organization.
- [Using reports](https://docs.yrecurring.com/guide/reports/using-reports.md): Open a ready-made report, change its date range, and download it as a spreadsheet.
- [Asking the copilot about your revenue](https://docs.yrecurring.com/guide/copilot/asking-questions.md): How to ask questions, what the answers contain, and how the copilot keeps every number honest.
- [Your plan and billing](https://docs.yrecurring.com/guide/your-account/plan-and-billing.md): How your plan works, what happens if an invoice goes unpaid, and how to cancel.