Loading article…
Loading article…
Last updated on Aug 27, 2026
Building your own subscription management experience against the Advanced Billing API gives you full control over what your customers see and do. Use the API resource tables below to find the endpoint for each action, then follow the walkthrough to assemble them into a working dashboard.
| Requirement | Detail |
|---|---|
| Feature | Advanced Billing API |
| You need | Developers, an existing frontend UI for subscription management, and a backend that recognizes a signed-in user |
| Code | Yes |
| Difficulty | Medium |
These are the API resources behind each subscription management action, grouped by the kind of change they make.
| Resource | Description |
|---|---|
| Read Customer’s Subscriptions | GET /customers/:id/subscriptions.json |
| Read Customer Payment Profiles | GET /payment_profiles.json?customer_id=:id |
| Update Customer | PUT /customers/:id.json |
| Read Subscription | GET /subscriptions/:id.json |
| Read Subscription Invoices | GET /invoices.json?subscription_id=:id |
| List Subscription’s Components (All) | GET /components.json |
| List Subscription’s Components (Only ones subscribed to) | GET /components.json > if allocated_quantity > 0, show. if kind is metered_component and price_point_id is not null, show. |
| Next billing amount and next renewal date | GET /subscriptions/:id.json > parse current_billing_amount_in_cents and next_assessment_at |
| Resource | Description |
|---|---|
| Read Products from Catalog | GET product_families/:product_family_id/products.json |
| Preview Prorated Product U/D | POST /migrations/preview.json |
| Execute Prorated Product U/D | POST /migrations.json |
| Schedule Upgrade/Downgrade for Next Renewal | PUT /subscriptions/:id.json |
| Read Subscription’s Components | GET /components.json |
| Preview Component U/D | POST /allocations/preview.json |
| Execute Component U/D | POST /allocations.json |
| Read Offers from Catalog | GET /offers.json |
| Preview Offer U/D | POST /migrations/preview.json |
| Execute Offer U/D | POST /migrations.json |
| Enforce upgrades only | In your UI, only allow changes if the total cost of the change is greater than the current cost. Additionally, if you do not want to display lower cost options at all, filter out what you display to the user, based on price. |
| Resource | Description |
|---|---|
| View Invoices | GET /invoices.json?subscription_id=:id |
| Cancel Subscription (immediate) | DELETE /subscriptions/:id.json |
| Reactivate Subscription | PUT /reactivate.json |
| Create Pending Cancellation (delayed) | POST /delayed_cancel.json |
| Remove Pending Cancellation | DELETE /delayed_cancel.json |
| Pause Subscription | POST /hold.json |
| Resume Paused Subscription | PUT /resume.json |
| Resource | Description |
|---|---|
| Collect Payment Information | Docs: Maxio.js Guide: Collect Payment Methods in your App with Maxio.js |
| Read Customer’s Payment Profiles | GET /payment_profiles.json?customer_id=:id |
| Create Payment Profile for Customer | POST /payment_profiles.json |
| Set Default Payment Method on Subscription | POST /change_payment_profile.json |
| Resource | Description |
|---|---|
| Cancel a Group (immediate) | POST /subscription_groups/:uid/cancel.json |
| Cancel a Group (delayed) | POST /subscription_groups/:uid/delayed_cancel.json |
| Read Consolidated Invoices for Group | GET /invoices.json?subscription_group_uid=:uid |
| Read Child Invoices | GET /invoices.json?subscription_id=:child_subscription_id |
| Remove Canceled Subscription from Group | DELETE /subscriptions/:id/group.json |
The dashboard lets your customers view their Subscription and Invoices, add or update payment methods, and act on the Subscription. The examples below are visual only, and no sample code accompanies them.
Read the Subscription so you can display it in your UI.
Read the subscription
You’ll need the subscription id, and then perform GET /subscriptions/:id.json.
Parse the data you want to display
For example, the subscription id sits at response.subscription.id, and the customer organization at response.subscription.customer.organization.
Pass the data to your frontend, and display it
A finished screen might look like this.
Let’s read the subscription’s invoices, so you can display them.
Read the subscription’s invoices
You’ll need the subscription id, and then perform GET /invoices.json?subscription_id=:id
Parse the data you want to display
For example, the invoice uid sits at response.invoice.uid, the invoice number at response.invoice.number, and the invoice URL at response.invoice.public_url.
Pass the data to your frontend, and display it
Here is a sample image that shows what an end result might look like in a basic table/list layout:
On your subscription dashboard, you may provide a link to let users add/update their payment information. That link takes them to an edit-payment-information page. Use the guide called Collect Payment Methods in your App with Maxio.js.
Component changes let customers update their add-ons directly in your web application.
Display the components to change
Read the subscription’s components by performing GET /components.json.
Parse the data you want to display
For example, the component name sits at response[0].component.name.
Pass the data to your frontend, and display it
A finished component-change screen might look like this.
Add a preview changes section
Make a POST to /allocations/preview.json, parse the result, and display it. This shows the customer what the change costs.
Submit the form with a “Change Add Ons” button
Make the API call with POST /allocations.json
Test your subscription dashboard
Your subscription dashboard should now reflect the changes of the subscription.
Cancellations let customers end a Subscription from your web application.
Add a cancel action
It might look like this:
Add a page in your UI, with a preview, confirmation, and submit button
It might look like this. This is a good place to state the terms of cancellation and tell the customer what happens next.
Upon submit, cancel the subscription
Choose which method you prefer:
| Method | Description | Endpoint |
|---|---|---|
| Cancel Subscription (Immediate) | The user can cancel their subscription, and the cancellation takes effect immediately. | DELETE /subscriptions/:id.json |
| Cancel Subscription (Delayed) | The user can schedule their subscription to cancel at the end of the current billing period. | POST /delayed_cancel.json |
Test your subscription dashboard
On your subscription dashboard, if you show the subscription state, it should now reflect the changes of the subscription. If there are certain actions that need to be shown/removed for a canceled subscription, or a subscription that is scheduled to cancel, do those in your UI.
Reactivations let customers restart a canceled Subscription from your web application.
Add a reactivation action, and only show it when a subscription is canceled
It might look like this:
Add a page in your UI, with a preview, confirmation, and submit button
It might look like this. This is a good place to state the terms of reactivation, including how much the customer is charged, if anything.
Upon submit, reactivate the subscription
Do this by performing a /subscriptions/:id/reactivate.json
Test your subscription dashboard
On your subscription dashboard, if you show the subscription state, it should now reflect the changes of the subscription. If there are certain actions that need to be shown/removed for an active subscription, do those in your UI.
Optional - Allow Pausing
Let’s add pausing a subscription to your web application.
Add a pause action
It might look like this:
Add a page in your UI, with a preview, confirmation, and submit button
It might look like this. This is a good place to state the terms of pausing and tell the customer what happens next.
Upon submit, cancel the subscription
Do this with POST /subscriptions/:id/hold.json
Test your subscription dashboard
On your subscription dashboard, if you show the subscription state, it should now reflect the changes of the subscription. If there are certain actions that need to be shown/removed for a paused subscription, do those in your UI.
Optional - Allow Resuming a Paused Subscription
Let’s add resuming to your web application.
Add a resume action, and only show it when a subscription is paused
It might look like this:
Add a page in your UI, with a preview, confirmation, and submit button
It might look like this. This is a good place to state the terms of resuming and tell the customer what happens next.
Upon submit, resume the subscription
Do this by performing /subscriptions/:id/resume.json
Test your subscription dashboard
On your subscription dashboard, if you show the subscription state, it should now reflect the changes of the subscription. If there are certain actions that need to be shown/removed for an active Subscription, do those in your UI.
To collect and tokenize payment details inside your own application, see Collect Payment Methods in your App with Maxio.js.
To compare building against the API with the lower-effort alternatives, see Compare Subscription Management Methods.
Still need help?
Reach out and our support team will take it from here.