Fixed-price subscriptions

Use fixed-price subscriptions when customers pay a known amount on a recurring schedule—for example, a monthly SaaS plan, membership, support package, or service retainer.

A plan defines the price and billing schedule. When a customer subscribes to that plan, XPay schedules recurring invoices and attempts payment using the subscription's payment token.

Follow the Fixed-price subscription quickstart to create your first subscription.

Example business#

LedgerPro is an example SaaS company used throughout these guides.

LedgerPro creates a separate product and plan for each offering. See Products to define what the company sells and Plans and billing cycles to configure its price and recurrence.

Resource model#

The main billing resources relate in the following order:

Product
  ↓
Plan
  ↓
Subscription
  ↓
Scheduled invoice ID
  ↓
Invoice
  ↓
PaymentIntent attempt

Integration flow#

1. Create the offering. Use Products to create the services or subscription tiers that customers can purchase.
2. Configure recurring billing. Use Plans and billing cycles to define the price, interval, billing anchor, and invoice limit.
3. Collect a payment token. Complete the Collect a payment token with XPay Element. XPay sends the reusable token in the verified webhook at token.id.
4. Create the subscription. Follow Create a fixed-price subscription and send the token as payment.token.
5. Store the billing identifiers. Save the subscription ID, plan ID, subscription state, and scheduled invoice IDs.

The API response communicates the immediate result of a request. Webhooks communicate subsequent billing and lifecycle changes.

Manage recurring billing#

Monitor subscription and invoice states#

Subscription and invoice states describe different objects. For example, an unpaid invoice can make its subscription inactive, but unpaid is not a subscription state.

See Subscription lifecycle and statuses for the supported states and payment-outcome mapping.

Work with invoices#

XPay reserves scheduled invoice IDs for upcoming billing slots and creates the corresponding invoice objects when billing is processed. An invoice can contain multiple payment attempts.

See Invoices and recurring payments to retrieve, pay, mark paid, or refund an invoice.

Change a subscription#

Use Manage a fixed-price subscription to update, skip, pause, resume, or cancel a subscription.

Use Prorations when a supported subscription change requires billing for the remaining portion of the current cycle.

Recover failed payments#

When a recurring invoice payment fails, the invoice remains unpaid and the subscription becomes inactive. XPay can retry payment according to the subscription's retry configuration.

See Failed payments and retries for retry timing and recovery options.

See Fixed-price subscription troubleshooting for common setup, payment, and lifecycle issues.

Guides#