API Subscription Management
Subscriptions management can be done through Admin API to automate business processes and perform bulk operations.
Subscription management actions most often times will only affect future renewals orders/charges of the subscription.
Create Subscription
Subscriptions can be created directly through the subscriptionsCreate Admin API endpoint for scenarios such as custom order flows or importing subcriptions from another platform.
{
"lines": [ // subscription line item products and pricing
{
"product_id": 123,
"quantity": 1,
"currency": "USD",
"price": "19.99"
}
],
"shipping_code": "default-shipping", // shipping method for renewal orders
"shipping_price": "3.99", // shipping price for renewal orders
"interval": "day", // subscription renewal interval
"interval_count": 30, // subscription renewal interval count
"next_renewal_date": "2022-2-28T08:41:37+07:00", // first renewal date
"user": {
"email": "john@smiths.com", // get or create a customer based on email address
"first_name": "John",
"last_name": "Smith"
},
"use_default_billing_address": true, // alternatively pass full billing_address
"use_default_shipping_address": true, // alternatively pass full shipping_address
"payment_method": "card_token",
"payment_details": {
"card_token": "<Card Token>" // see card tokenization iFrame guide
},
}Updating Products & Pricing
Updating subscription recurring items and pricing can be done through subscriptionLinesCreate, subscriptionLinesUpdate, and subscriptionsLinesDestroy endpoints.
Adding an Additional Product
To add a new product to a subscription, use the subscriptionLinesCreate Admin API endpoint with the product, price, and quanity details.
{
"price": "9.99", // recurring price for the product
"product_id": 100, // product ID
"quantity": 1 // quantity of the product
}Updating an Existing Line Item Product Price
To update and existing product price and quantity on a subscription line, use the subscriptionsLinesUpdate Admin API endpoint with the new price, and new quanity details.
{
"price": "9.99", // new recurring price for the product
"quantity": 1 // new quantity of the product
}Removing a Product
To remove a product from a subscription, send a DELETE request to the subscriptionsLinesDestroy endpoint to remove the line item (ie the product) from future renewal orders created from the subscription.
{}Subscriptions must have at least one line item with a product, you can alternatively cancel the subscription to stop all future renewals.
Updating Renewal Schedule
Changing the renewal schedule of a subscription can be achived with a PATCH request to the subscriptionsPartialUpdate endpoint with a new interval and interval_count, ie 30 days.
{
"interval": "day",
"interval_count": 30,
"next_renewal_date": "2025-06-29T03:28:59.193252-05:00" // optional next renewal date
}Changing Next Renewal Date
Changing the next renewal date of a subscription can be achieved through updating the next_renewal_date key on the subscription object with a PATCH request to the subscriptionsPartialUpdate endpoint with your new renewal date and time.
{
"next_renewal_date": "2025-06-29T03:28:59.193252-05:00" // next renewal date & time
}If you would like to immediately renew the subscription, you can pass a date from the past and the subscription will process a renewal attempt within the next 30 minutes.
Triggering a Renewal
To immediately trigger a renewal order for an active subscription, use the subscriptionsRenewCreate endpoint. This creates a new renewal order on demand without waiting for the next scheduled renewal date.
{}The endpoint returns the full subscription object with updated renewal details on success.
The subscription must be in an active status to trigger a renewal. For subscriptions in past_due status, use the subscriptionsRetryCreate endpoint instead.
Updating Payment Details
Updating the Payment Gateway of a subscription can done through the subscriptionsPartialUpdate endpoint.
Changing Payment Gateway
To change the payment gateway used for bankcard payments of a subscription, send a PATCH request to the subscriptionsPartialUpdate endpoint with the new payment_gateway.
{
"payment_details": {
"payment_gateway": 23 // new payment gateway to be used on the next renewal
}
}Updating Bankcard Payment Method
To change the bankcard on a subscription, pass a new card_token with a PATCH request to the subscriptionsPartialUpdate endpoint.
To update a bankcard on a subscription, you must use the iFrame to tokenize the bankcard and use the card_token when updating the subscription itself.
The new bankcard will be automatically verfied with a verify request to a payment gateway to ensure the new bankcard is valid and can be used for future renewals. If the bankcard cannot be verified, the update request will fail and return an error.
New Bankcard Payment Method Flow
{
"payment_details": {
"card_token": "<New Card Token>", // new card token
"payment_gateway": 23 // optionally pass a specific gateway
},
"billing_address": {
"country": "string", // optionally pass a new billing address
"first_name": "John",
"last_name": "Doe",
"line1": "123 East West St.",
"line4": "New York",
"state": "NY",
"postcode": "90210"
}
}Retrying Renewal
Subscriptions that are past_due status can be attemted to retry the renewal, often combined with a new payment_gateway, by using the subscriptionsRetryCreate endpoint.
{
"payment_gateway": 122 // optional new payment gateway to retry with
}The subscription retry endpoint is useful for custom recovery logic when attempting to recover failing subscriptions.
Cancel
To cancel a subscription, use the subscriptionsCancelCreate endpoint to stop all future renewals.
{
"cancel_reason": "not_satisfied_with_product", // required
"cancel_reason_other_message": "Wasn't happy with result", // optional
"send_cancel_notification": true // to send the cancelation email or not
}