Recurly

Recurly

Subscription billing platform using the v3 REST API. Manages the full billing lifecycle: accounts → subscriptions → invoices → transactions.

Entity Hierarchy

Core Billing

• Accounts — billable customer entities. Each account has a unique id (Recurly-generated UUID) and optional code (your internal ID). Contains billing info, shipping addresses, and notes.

  • Billing Infos — payment method details for an account (card, PayPal, bank). Queried by account_id.
  • Shipping Addresses — delivery addresses on an account. Queried by account_id.
  • Account Notes — internal notes. Queried by account_id.
  • Account Coupon Redemptions — coupons applied to this account. Queried by account_id.

• Subscriptions — recurring billing agreements linking an account to a plan. States: active, canceled, expired, future, paused, failed. Canceled subs remain active until current_period_ends_at.

• Plans — pricing templates defining amount, interval (monthly/annual), trial, and setup fees.

  • Add-Ons — optional extras attached to plans (e.g. extra storage, premium support). Priced per unit or flat.

Financial Documents

• Invoices — generated from subscription charges, one-time charges, or credits. States: pending, past_due, paid, failed, voided.
  • Line Items — individual charges within an invoice. Each line item has type (charge, credit), amount, description, and tax info.
• Credit Payments — credits applied against invoices.
• Transactions — payment/refund records. Each transaction references an invoice and payment method.

Promotions

• Coupons — discount codes with redemption limits, duration, and applicability rules. Can be percentage or fixed-amount.
  • Unique Coupons (parent) — bulk-generated single-use codes from a coupon template. One read path lists the parent templates; another enumerates issued child codes when you already know the parent coupon id.

Fulfillment

• Shipping Methods — available shipping options with carrier, cost, and delivery estimates.

Export

• Export Dates — available dates for bulk data export files.
• Measured Units — usage-based billing unit definitions.

Workflows

1. Customer audit: Enumerate accounts → open one account → enumerate billing infos (by account_id) → enumerate subscriptions → enumerate invoices for billing history.
2. Revenue analysis: Enumerate subscriptions → filter by state → enumerate invoices → enumerate line items for granular revenue breakdown → enumerate transactions for payment status.
3. Plan catalog review: Enumerate plans → enumerate add-ons for optional extras → enumerate coupons for active promotions → enumerate parent coupon templates for bulk codes.
4. Dunning/collections: Enumerate invoices (filter past_due) → enumerate transactions for failed payments → enumerate credit payments for applied credits.
5. Account deep-dive: Enumerate accounts → enumerate account notes + coupon redemptions + shipping addresses (all scoped by account_id).
6. Customer onboarding: Create account (code + email + name) → create subscription with a plan → enumerate invoices to confirm first charge.
7. Subscription lifecycle: Create subscription → (later) cancel subscription → enumerate subscriptions to confirm state is 'canceled' → after period ends, state becomes 'expired'.
8. One-time charge: Create purchase with line items (type=charge, unit_amount, description) to invoice a one-time fee on an account.

Gotchas

• v3 API only: This uses Recurly v3 which returns JSON. v2 (XML-based) is completely different and deprecated.
• Pagination: Cursor-based. Response includes has_more and next link. Use limit param (max 200) and order (asc/desc).
• Account-scoped data: Billing infos, shipping addresses, notes, and coupon redemptions hang off an account—resolve account_id from account listing before drilling into children.
• Coupon hierarchy: Parent coupon reads expose templates; child-code enumeration needs the parent coupon id you obtained from that template listing.
• Subscription states: canceled is NOT the same as expired. Canceled subs keep providing service until current_period_ends_at. expired means the term has ended.