Skip to main content
A subscription charges a payer’s card on a schedule they agree to once, in checkout. Natural charges each later payment when it falls due.

Create a subscription

Create a subscription. For a subscription with no end, send terms.amount, the amount of every payment:
For 2 to 4 installments, send terms.totalAmount and terms.paymentCount instead:
Payment 1 is charged in checkout. Payment n falls n-1 intervals after that day, counted from that day each time: a payer who agrees on Jan 31 to monthly payments pays on Jan 31, Feb 28 and Mar 31. You can’t change a pending subscription or its checkout’s payment intent. To offer other terms, cancel it and create a new one.

Take payment 1

Send the payer to payUrl, or pass clientSecret to the payment form on your own page, as in Embed the payment form. When the payer pays payment 1, the subscription becomes active.

Later payments

Natural can charge a payment from 12:00 UTC on its due date. Its window closes 30 days later, or when the next payment’s window opens, if that’s sooner. Every charge attempt, payment 1 included, is a card payment. Each sends cardPayment.created, then cardPayment.succeeded or cardPayment.failed. To list them, call GET /card-payments?subscriptionId={subscriptionId}.

Missed payments

Natural retries a declined payment within its window. When the retries run out or the window closes unpaid, the subscription payment becomes missed and the subscription becomes past_due. Natural doesn’t charge a missed payment again, but it still charges later payments. To find missed payments, call GET /subscriptions/{subscriptionId}/payments?status=missed. The payer can pay one from their manage page. If you collect it another way, mark it paid with data.attributes set to {}, so it’s no longer owed. You can mark a payment paid only when it’s missed, or its window closed without a charge. Marking it paid doesn’t restart a subscription that needs attention. When the card expires, or a charge on it, for this or another subscription, is declined in a way that rules out a retry, the subscription becomes needs_attention and Natural stops collecting. Payments still fall due. Collecting starts again when the payer adds a new card on their manage page, or when Natural receives the card’s new expiry date or number.

Cancel

Cancel a subscription to stop its payments. Natural emails the payer. A charge already under way can still go through, and the subscription stays canceled. Mark missed payments paid before you cancel: after that, they can’t be paid. Canceling a pending subscription cancels its checkout, so the payer can’t pay payment 1, and the payer isn’t emailed. While the payer’s payment 1 is processing, the cancel is refused with subscription.pending.

The payer’s manage page

The payer’s confirmation, receipt and failed-payment emails link to their manage page. It opens with a code sent to the email the payer gave in checkout. There the payer can update their card, pay a missed payment, and cancel a subscription with no end. They can’t cancel installments, because they still owe the remaining payments. In Sandbox, Natural emails no payer, and the manage page’s code is 000000.