A subscription (sub_*) charges a payer’s card on a schedule they agree to once in checkout: with no end, or in 2 to 4 installments. Each payment it owes is a subscription payment. To learn more, see Charge on a schedule.
The object is everything inside data. The field names below are relative to it: attributes.status is data.attributes.status in the response.
Fields
string
required
Subscription ID (sub_*).
string
required
Resource type. Always subscription.
object
required
The subscription’s details.
Hide attributes
string
required
The subscription’s status. One of: pending, active, past_due, needs_attention, canceled, completed. See Statuses.
object
required
The terms as frozen when the subscription was created.
One of 2 shapes:
Hide SubscriptionTermsNoEnd
string
required
What the payer is paying for.
object
required
The time between payments, and the subscription’s only interval. Payment 1 is charged in checkout, and payment n falls n-1 intervals after it. Every 1 to 25 weeks or 1 to 5 months, so payments are less than 180 days apart. Yearly subscriptions aren’t available yet.
Hide every
string
required
The unit of the interval. year is refused: yearly subscriptions aren’t available yet. One of: week, month, year.
integer
required
How many units are in one interval.
integer
required
Every payment’s amount in cents, tax included, payment 1 included. A card payment is at least $0.50.
integer
required
The part of amount that is tax, in cents.
null
required
Null: the subscription has no end.
Hide SubscriptionTermsWithEnd
string
required
What the payer is paying for.
object
required
The time between payments, and the subscription’s only interval. Payment 1 is charged in checkout, and payment n falls n-1 intervals after it. Every 1 to 25 weeks or 1 to 5 months, so payments are less than 180 days apart. Yearly subscriptions aren’t available yet.
Hide every
string
required
The unit of the interval. year is refused: yearly subscriptions aren’t available yet. One of: week, month, year.
integer
required
How many units are in one interval.
integer
required
What the payments add up to, in cents, tax included.
integer
required
The part of totalAmount that is tax, in cents.
integer
required
How many payments the subscription has: 2 to 4.
object[]
required
Each payment, payment 1 first: its share of totalAmount and of taxAmount.
Hide payments
integer
required
This payment’s amount in cents, tax included.
integer
required
The part of this payment that is tax, in cents.
string
required
Currency code. Always USD.
string | null
required
YYYY-MM-DD, UTC: the day the payer paid payment 1. Payment n falls n-1 intervals after it. Null until the payer pays payment 1.
string[]
Methods the payer can choose in checkout to agree to the subscription. Omitted when the subscription allows only card. Each item is one of: card, bank.
object | null
required
The first payment after the last one paid, missed or marked paid that can still be charged: the one Natural charges next, unless the subscription needs attention. A payment whose window closed unpaid is passed over. Null once the subscription is canceled or completed, or when no payment can still be charged.
Hide nextPayment
integer
required
Which payment of the subscription this is.
string | null
required
YYYY-MM-DD, UTC. Null for payment 1 while the subscription is pending: it’s due when the payer pays in checkout, and later payments fall due from that day.
integer
required
Amount in cents, tax included.
integer
required
The part of amount that is tax, in cents.
object | null
required
Why Natural stopped collecting, while the subscription needs attention.
Hide attention
string
required
card_blocked: the bank declined the card in a way that rules out a retry. card_expired: the card has expired. card_needs_update: the bank asked for new card details, as when it reissues the card. card_removed: the bank says the card can’t be used. One of: card_blocked, card_expired, card_needs_update, card_removed.
string
required
RFC 3339 timestamp when Natural stopped collecting.
string | null
required
Hosted checkout URL for payment 1 while the subscription is pending. Null once checkout ends.
string | null
required
Pass to natural.js in the browser to show the payment form for payment 1 on your page. Available whenever payUrl is, so it’s null once checkout ends. Treat it like a password: send it only to the payer’s browser.
string | null
required
RFC 3339 timestamp after which the payer can no longer pay payment 1 in checkout, and a subscription still pending reads canceled. Null when checkout doesn’t expire.
string
required
RFC 3339 timestamp when the subscription was created.
string
required
RFC 3339 timestamp when the subscription record last changed. status and nextPayment are read live.
string | null
required
The payer’s email from the agreement. Null until payment 1 sets up the agreement, when the payer gave none, and for a caller who can’t read agreements.
object
required
Objects linked to the subscription.
Hide relationships
object
required
The checkout intent for payment 1.
Hide paymentIntent
object
required
Related resource identifier.
Hide data
string
required
Resource type. Always paymentIntent.
string
required
Payment intent ID (pmi_*).
Statuses
Status
Meaning
Can become
pending
Waiting for the payer to pay payment 1 in checkout.
active, canceled
active
Natural charges each payment when it falls due.
past_due, needs_attention, canceled, completed
past_due
A payment was missed and isn’t paid or marked paid yet. Later payments are still charged.
active, needs_attention, canceled, completed
needs_attention
Natural stopped collecting: the card expired, or a charge on it, for this or another subscription, was declined in a way that rules out a retry. attention.reason says why.
active, past_due, canceled, completed
canceled
You or the payer canceled it, the payer’s bank stopped its agreement, checkout ended without payment 1, or the agreement couldn’t be set up.
Final
completed
Every payment of a subscription in installments is paid or marked paid.
Final
Events
subscription.activated: Early access (subscriptions). The payer paid payment 1 in checkout, so the subscription is active.
subscription.updated: Early access (subscriptions). A subscription’s status changed without starting or ending it, for example from active to past_due or needs_attention. data.previousStatus has the status it left.
subscription.canceled: Early access (subscriptions). A subscription was canceled. Natural starts no new charges, though a charge already under way can still go through. It also fires when a pending subscription’s checkout ends without payment 1, so it can follow no subscription.activated.
subscription.completed: Early access (subscriptions). Every payment of a subscription in installments is paid or marked paid.