A Plan is a blueprint for taking multiple payments over time. It can include any number of fixed point-in-time payments on specific dates, as well as a continuing schedule of recurring payments.
If you need more than one recurring payment schedule, you can create multiple plans and subscribe a payer to both/all of them.
Plans can use both fixed dollar amounts or percentages of a total amount. You can even do both! For example, I can have a $50/month plan with an upfront $100 payment; or I can do 25% upfront with 10% per month thereafter; or even $2000 after 7 days, with 25% a quarter until complete.
When dealing with amount limits, the plan will never exceed the limit. Payments are reduced to fit the totals. The current minimum payment is $5, so if a plan would leave less than that as the final payment, it is tacked onto the second last payment instead.
| Attribute | Child Attribute | Description |
|---|---|---|
| id string | The Plan ID. Plans are prefixed with "pln_" | |
| name string | A label for the plan | |
| fixedPayments array of fixedPayment | Schedule any number of fixed point-in-time payments | |
| amountInCents integer | The amount to charge in cents | |
| amountPercentage decimal | Alternatively, a percentage of the full subscription amount to charge. (0.0 to 1.0) | |
| description string | A description of the payment | |
| cancelPlanOnFailure boolean | If true, the subscription will cancel and remove all future payments when this payment fails. If false, the subscription will remain active, and it's up to you to recharge the failed amount. | |
| scheduledDateInterval string | Can be "days", "months", or "years" | |
| scheduledDateOffset integer | Schedule the payment after this many intervals. eg. 0 days is immediately, 7 days is next week, 1 month is next month, etc... | |
| recurringPayment recurringPayment | Only one recurring payment can be created. Create multiple plans if you need more than one. | |
| amountInCents integer | The amount to charge in cents | |
| amountPercentage decimal | Alternatively, a percentage of the full subscription amount to charge. (0.0 to 1.0) | |
| description string | A description of the payment | |
| cancelPlanOnFailure boolean | If true, the subscription will cancel and remove all future payments when this payment fails. If false, the subscription will remain active, and it's up to you to recharge the failed amount. | |
| startDateInterval string | Can be "days", "months", or "years" | |
| startDateOffset integer | The first payment will be scheduled after this many intervals | |
| endDateInterval string | Can be "days", "months", or "years" | |
| endDateOffset integer | The subscription will complete after this many intervals | |
| frequencyInterval string | Can be "days", "months", or "years" | |
| frequencyOffset integer | Every new payment is scheduled this many intervals from the previous one. eg. 7 days is every week on the same day. 1 month is every month on the same day. Uses sensible movement for dates that don't exist, eg Feb 30. | |
| endAfterNumberOfPayments integer | Will complete the subscription after generating this many payments | |
| endAfterTotalAmount integer | Completes the subscription after this amount in cents has been taken on a recurring basis. Does not include any fixed payments. It will reduce the final payment if this limit is exceeded. | |
| endType string | Select the end condition for the subscription. Can be "never", "end-date", "total-amount", "number-of-payments", "subscription-fully-paid". Subscription Fully Paid uses this full subscription amount to end the subscription, calculated on both fixed and recurring payments. | |
| metadata string | A free field (JSON preferred) that will be added to each payment that is generated from this plan. |