Skip to main content
Plans are in early access and subject to change. To request Plans access, contact hi@natural.com.
A plan is a subscription, or 2 to 4 installments, that a payer agrees to once in checkout. A subscription charges every 1 to 25 weeks or every 1 to 5 months, so its payments are less than 180 days apart; yearly plans aren’t available yet. Natural keeps the card and the agreement, and you charge each later payment when it falls due.

​
Installments

An installment plan splits one purchase into 2 to 4 payments. In POST /plans, set each payment’s amount in terms.payments, in order, and the time between payments in terms.every, on the same intervals as a subscription:
Payment 1 is charged in checkout, on the day the payer agrees, and payment n falls n-1 intervals after that day. A payer who agrees on Jan 31 to monthly payments pays on Jan 31, Feb 28 and Mar 31. Checkout shows the payer every date before they agree, and the dates don’t change after that. nextPayment.dueDate gives the next one.

​
Lifecycle

  1. Create a plan with POST /plans. It starts pending and returns a checkoutUrl.
  2. The payer agrees to the terms and pays payment 1 in checkout. The plan becomes active, and mandateId names the card agreement it charges.
  3. Charge each later payment with POST /plans/{planId}/payments. It returns the card payment. A payment can be charged from 12:00 UTC on its due date until 30 days later, or until the next payment opens if that’s sooner. GET /plans/{planId}/payments lists a plan’s charges, newest first, as the same card payments: payment 1 from checkout, and each attempt at a later payment.
  4. A plan becomes canceled when the payer or you cancel it, when the payer’s bank stops its agreement, when checkout ends without payment 1, or when the agreement can’t be set up. An installment plan becomes finished once every payment is paid or skipped.

​
Missed payments

A declined payment is retried inside its window. If it still isn’t paid, it’s missed: missedPayments lists it and the plan is past_due. Natural never charges a missed payment late, so collect it another way. Later payments are still charged on schedule. A plan becomes needs_attention, and Natural stops collecting, when two payments in a row are missed or when the bank declines the card in a way that rules out a retry. attention.reason says which. Once you’ve collected a missed payment another way, mark it with POST /plans/{planId}/skip, so it’s no longer owed. That includes a payment whose window closed while the plan was stopped. Skipping a payment first records any earlier payments that already lapsed as missed, so they stay owed until you skip them too. Skip only settles a missed payment: it doesn’t skip an upcoming one, and it doesn’t restart a plan that needs attention. To start collecting again, call POST /plans/{planId}/resume.

​
Canceling

You can cancel a plan with POST /plans/{planId}/cancel. A subscription’s payer can also cancel it online, on its manage page. An installment plan’s payer can view it there but can’t cancel it, because they still owe its remaining payments. When a plan is canceled, Natural revokes its card agreement and sends mandate.revoked, with revocationReason payer_canceled or merchant_canceled. Natural charges nothing more and emails the payer a confirmation. A charge already under way when the plan is canceled can still go through, and the plan’s payments stay listed. To end a plan that’s still pending, cancel its payment intent instead. The payer reaches the manage page two ways:
  • From your app. Call POST /plans/{planId}/manage-links and send your signed-in customer to the url it returns. The link opens once, with no code, and expires after 5 minutes, so create one each time the customer asks to manage the plan.
  • From Natural’s emails. The plan’s confirmation, each receipt and each failed-payment email link to it: “Manage or cancel” for a subscription, “View your plan” for an installment plan. The link asks for a code sent to the email the payer confirmed in checkout.
The manage page shows the plan’s terms and status, its next payment, its payments and the card on file, and lets a subscription’s payer cancel.

​
Plan payments and webhooks

Every charge of a plan is a card payment with plan fields only plans carry:
  • plan has the plan’s id, its kind, and the paymentNumber the charge pays. Payment 1 is the checkout payment.
  • A later payment has channel api, because Natural charged the card without the payer present, and mandateId names the card agreement it was charged on.
Read a plan’s charges with GET /plans/{planId}/payments, GET /card-payments and GET /card-payments/{cardPaymentId}. Every charge, payment 1 included, sends cardPayment.created, then cardPayment.succeeded or cardPayment.failed, each with the same fields. A successful charge also sends paymentIntent.completed.