Skip to main content
Subscriptions are in early access and subject to change. To request Subscriptions access, contact hi@natural.com.
A subscription charges a payer’s card on a schedule they agree to once in checkout: with no end, or in 2 to 4 installments. One with no end charges every 1 to 25 weeks or every 1 to 5 months, so its payments are less than 180 days apart; yearly intervals aren’t available yet. Natural keeps the card and the agreement, and charges each later payment when it falls due. In POST /subscriptions, a subscription with no end sets terms.amount, the amount of every payment (at least $0.50), and terms.every, its one interval. Its terms.paymentCount reads null.

​
Installments

A subscription in installments splits one purchase into 2 to 4 payments. In POST /subscriptions, set the purchase’s total in terms.totalAmount, the number of payments in terms.paymentCount, and the time between payments in terms.every, on the same intervals as one with no end.
Natural splits the total into equal payments and puts the cents that don’t divide evenly on payment 1, so $499.99 in 3 payments is $166.67, then $166.66 twice. Each payment must be at least $0.50: a split that makes one smaller is refused, and the error names that payment. The subscription lists each payment’s amount in terms.payments. 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.

​
Tax

amount and totalAmount are what the payer pays, tax included. To say how much of it is tax, set terms.taxAmount, which defaults to 0. Every payment of a subscription with no end carries taxAmount. In installments, the tax is split the same way as its total, with the cents that don’t divide evenly on payment 1, and terms.payments lists each payment’s taxAmount. Each payment’s payment intent carries its share. The agreement the payer accepts names each payment’s tax, and each payment’s receipt shows its tax.

​
Lifecycle

  1. Create a subscription with POST /subscriptions. It starts pending and returns a checkoutUrl and a clientSecret. To stop checkout taking payment after a deadline, set expiresAt. A pending subscription can’t be changed, and neither can its checkout’s payment intent. To offer other terms, end the subscription (see Canceling) and create a new one.
  2. The payer agrees to the terms and pays payment 1 in checkout. The subscription becomes active, and mandateId names the card agreement it charges.
  3. Natural charges each later payment automatically when it falls due. 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. To charge one yourself inside that window, use POST /subscriptions/{subscriptionId}/payments, which returns the card payment. GET /card-payments?subscriptionId={subscriptionId} lists every card payment whose subscription is that subscription, newest first: each attempt at each payment, payment 1’s checkout attempts included.
  4. A subscription becomes canceled when the payer or you cancel it, when the payer’s bank stops its agreement, when checkout ends or expires without payment 1, or when the agreement can’t be set up. One in installments becomes completed once every payment is paid or marked paid. A canceled subscription stays canceled, even if a charge already under way then pays its last payment.
GET /subscriptions lists your subscriptions, newest first. Pass status to list only those in one status, such as needs_attention.

​
Embed checkout

To take payment 1 on your own page instead of sending the payer to checkoutUrl, pass the subscription’s clientSecret from your server to the payer’s browser. It’s set whenever checkoutUrl is, so it’s null once checkout ends. Treat it like a password. Mount Natural’s payment form with it:
TypeScript
The form shows the subscription’s agreement as the hosted checkout does, verifies the payer’s phone, and charges payment 1. Your page must show what the payer is buying and its price, your country and a support email or phone, and your delivery policy if you ship goods. In live mode, the form loads only on a site in your checkout domains, which you add in the dashboard under Developers → API keys. In sandbox, it loads on any site.

​
Missed payments

A declined payment is retried inside its window. If it still isn’t paid, it’s missed: missedPayments lists it and the subscription is past_due. Natural never charges a missed payment late, so collect it another way. Later payments are still charged on schedule. A subscription 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 /subscriptions/{subscriptionId}/mark-paid, so it’s no longer owed. That includes a payment whose window closed while the subscription was stopped. Marking a payment paid first records any earlier payments that already lapsed as missed, so they stay owed until you mark them paid too. Marking paid only settles a missed payment: it doesn’t settle an upcoming one, and it doesn’t restart a subscription that needs attention. To start collecting again, call POST /subscriptions/{subscriptionId}/resume.

​
Canceling

You can cancel a subscription with POST /subscriptions/{subscriptionId}/cancel. The payer of a subscription with no end can also cancel it online, on its manage page. The payer of one in installments can view it there but can’t cancel it, because they still owe its remaining payments. When a subscription 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 subscription is canceled can still go through, and the subscription’s payments stay listed. Canceling a subscription that’s still pending cancels its checkout instead, so the payer can’t pay payment 1, and the subscription becomes canceled. There’s no agreement yet, so you get paymentIntent.canceled rather than mandate.revoked, and the payer isn’t emailed. If the payer has already submitted payment 1, the cancel is refused with subscription_pending until its outcome lands. Once it’s paid and the subscription is active, a cancel revokes the agreement as above. The payer reaches the manage page from Natural’s emails. The subscription’s confirmation, each receipt and each failed-payment email link to it: “Manage or cancel” for a subscription with no end, “View your plan” for installments. Hosted checkout’s confirmation links to it too, for a subscription with no end. The link asks for a code sent to the email the payer confirmed in checkout. The manage page shows the subscription’s terms and status, its next payment, its payments and the card on file, and lets the payer of a subscription with no end cancel.

​
Subscription payments and webhooks

Every charge of a subscription is a card payment with fields only a subscription’s payments carry:
  • subscription has the subscription’s id, the paymentNumber the charge pays, and its paymentCount, which is null when it has no end. 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 subscription’s charges with GET /card-payments?subscriptionId={subscriptionId} 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.