/subscriptions
Creates a subscription and its first checkout. Send the customer to redirect_url; activation, renewals and cancellation arrive as webhooks. replaces cancels an older subscription of the same customer once this one is active (plan change).
Authorization
Bearer token: an app key from Apps (sk_app_live_… or sk_app_test_…), or the tenant key from Settings (sk_live_… or sk_test_…). The key picks the mode: a live key only sees live data, a test key only sandbox data.
Parameters
Any unique string per operation (an order id works). The same key returns the first result instead of creating another.
Request Body
application/json, required
Price per interval, e.g. "29.90".
Shown on the checkout and the invoices.
Language of the payment page and the gateway checkout. Also takes pt, en-US and similar. Without it the app's Checkout language applies, else the customer's browser.
Pins one gateway configuration that supports subscriptions.
A subscription of the same customer to cancel once this one is active.
Found by external_ref, created when new; the contact fields are kept up to date.
Your own user id.
CPF, CNPJ or tax id.
Two letters, e.g. SP.
Two letters, e.g. BR.
Response Body
201Subscription created, waiting for the first payment.
pending: waiting for the first payment; active: grants access (also while a cancellation is scheduled); past_due: a renewal failed and the gateway is retrying; canceled: ended.
Price per interval, decimal with a dot.
The configuration that handles the payment.
Your own id for the customer, as sent to /connect.
What the product sent with the checkout, echoed back on the subscription and on every renewal cycle.
End of the paid period, when the next renewal is charged. Can be null in subscription.activated; the date then arrives in subscription.updated.
true once a cancellation is scheduled for the end of the period.
When the cancellation was asked for.
When a scheduled cancellation ends it.
The subscription this one replaced (a plan change).
When it ended.
The session of the first payment.
Send the customer here to subscribe.
200Same Idempotency-Key as an earlier call; the first subscription comes back with `duplicate: true`.
pending: waiting for the first payment; active: grants access (also while a cancellation is scheduled); past_due: a renewal failed and the gateway is retrying; canceled: ended.
Price per interval, decimal with a dot.
The configuration that handles the payment.
Your own id for the customer, as sent to /connect.
What the product sent with the checkout, echoed back on the subscription and on every renewal cycle.
End of the paid period, when the next renewal is charged. Can be null in subscription.activated; the date then arrives in subscription.updated.
true once a cancellation is scheduled for the end of the period.
When the cancellation was asked for.
When a scheduled cancellation ends it.
The subscription this one replaced (a plan change).
When it ended.
The session of the first payment.
Send the customer here to subscribe.
401Missing or invalid secret key.
What went wrong.
422Missing Idempotency-Key, no gateway with subscriptions for the currency, an invalid amount, an invalid `replaces` or an invalid record.
One message per field (idempotency_key, gateway, amount, replaces, subscription or record).
502The gateway refused or failed the call.
The gateway's message.
The provider that failed.