Understanding Payment Plans
What is a payment plan
A payment plan is a schedule of recurring payments for a customer. The portal’s scheduler automatically creates payment intents for each upcoming payment date and processes them using the customer’s saved payment method.
Payment plans are created and managed in the portal. The API handles the individual payment intents that the scheduler creates.
Frequency options
| Frequency type | Code | Example |
|---|---|---|
| Weekly | W | Every week |
| Monthly | M | Every month |
Set a period to change the interval — period 2 with type W means every 2 weeks; period 3 with type M means every 3 months.
Amount structure
| Field | Description |
|---|---|
recurring_amount_cents | Amount for each scheduled payment (min 200, max 100,000 cents) |
first_amount_cents | Optional different amount for the first payment |
total_amount_cents | Optional fixed total — plan closes automatically when collected amount reaches this |
until_further_notice | true for open-ended plans with no total amount |
If neither total_amount_cents nor until_further_notice is set, the plan must be closed manually.
Plan states
| State | Description | Payments scheduled? |
|---|---|---|
draft | Created but not activated | No |
active | Running and scheduling payments | Yes |
inactive | Paused — future unprocessed intents deleted | No |
suspended | Temporary hold (e.g. payment method recovery) | No |
closed | Permanently ended | No |
Activate a draft plan to begin scheduling. A plan in any state except closed can be closed.
How payments are created
The scheduler creates payment intents up to 366 days in advance. Each intent has a process_at timestamp for its scheduled date. On that date:
- The intent is submitted to
PaymentIntentDOin worker-pay - worker-pay processes the payment using the customer’s saved payment instrument
- A
payment_intent.succeededorpayment_intent.failedevent is emitted - The outcome syncs back to the payment intent record in the portal
PaymentIntentDO (a Cloudflare Durable Object) is the source of truth for processing state. The portal’s PaymentIntent reflects the outcome after sync.