Zoho Billing

Zoho Billing

Zoho Billing (formerly Zoho Subscriptions) manages recurring billing, subscription plans, and payment automation for SaaS and subscription businesses.

Multi-Organization

Many Zoho accounts have multiple organizations. Call the list-organizations tool first to get the organization_id, then pass it to every subsequent call. Single-org accounts work without it, but multi-org accounts fail without it.

Data Model

• Products — top-level catalog entries that group plans and addons. Create products first, then attach plans.
• Plans — subscription pricing tiers with billing intervals (monthly/yearly), trial periods, and setup fees. Each plan belongs to a product.
• Addons — optional extras (one-time or recurring) attachable to subscriptions. Each addon has an addon_code.
• Coupons — discount codes (flat or percentage) applicable to subscriptions at checkout.
• Customers — billing contacts with addresses, payment terms, and outstanding balances.
• Subscriptions — active recurring billing relationships tying a customer to a plan, with optional addons and coupons. Core entity for revenue.
• Invoices — auto-generated from subscriptions at each billing cycle. Read-only — created by the system.
• Transactions — payment records (charges, refunds) linked to invoices. Read-only.
• Expenses — business expense entries for tracking costs.
• Recurring Expenses — repeating expense schedules (rent, SaaS tools).
• Quotes/Estimates — proposals sent to prospects before subscription creation.
• Taxes — tax rate configurations applied to plans and addons.

Workflow Patterns

1. Set up a subscription product: create product → create plan(s) under product → optionally create addons → create customer → create subscription with customer_id + plan.
2. Apply a discount: create coupon → pass coupon_code when creating or updating a subscription.
3. Upgrade/downgrade: update subscription with new plan object (different plan_code or price override).
4. Track revenue: list subscriptions (filter by status) → list invoices → list transactions.
5. Manage trials: set trial_period on plan creation, or override trial_days in the subscription's plan object.

Important Constraints

• Plans require products: Always create a product first, then create plans under it with the product_id.
• Plan codes and addon codes are unique identifiers: Used as the primary key for get/update/delete (not numeric IDs).
• Subscriptions are not deletable via API: Cancel subscriptions instead (update with cancel_at_end or immediately).
• Invoices are read-only: Generated automatically from subscriptions. Cannot be created or modified directly.
• Coupon discount_by: Must be either "flat" or "percentage" — other values are rejected.