Preview Renewal
Previews a subscription’s next renewal assessment. Renewal Preview is an object representing a subscription’s next assessment. You can retrieve it to see a snapshot of how much your customer will be charged on their next renewal.
The "Next Billing" amount and "Next Billing" date are already represented in the UI on each Subscriber's Summary. For more information, see Subscriber Interface Overview.
Optional Component Fields
This endpoint is particularly useful because it returns the computed billing amount for the base product and the components which are in use by a subscriber.
By default, the preview includes billing details for all components at their current quantities. This means:
- Current
allocated_quantityfor quantity-based components - Current enabled/disabled status for on/off components
- Current metered usage
unit_balancefor metered components - Current metric quantity value for events recorded thus far for events-based components
In the above statements, "current" means the quantity or value as of the call to the renewal preview endpoint. End-of-period values for components are not predicted, so metered or events-based usage may be less than it will eventually be at the end of the period.
Optionally, you can provide your own custom quantities for any component to see a billing preview for non-current quantities. This is accomplished by sending a request body with data under the components key. See the request body documentation below.
Preview Behavior
Sending a POST request to this endpoint returns preview data without modifying the subscription. This method previews data, but does not log any changes against a subscription.
Authorization
BasicAuth The username is a Maxio Chargify API key. The password is x.
In: header
Path Parameters
The Chargify id of the subscription.
Request Body
application/json
(Optional) Array of component definitions to preview. Providing any component definitions here will override the actual components on the subscription (and their quantities), and the billing preview will contain only these components (in addition to any product base fees).
Response Body
application/json
application/json
curl -X POST "https://example.com/subscriptions/0/renewals/preview.json" \ -H "Content-Type: application/json" \ -d '{ "components": [ { "component_id": 10708, "quantity": 10000 }, { "component_id": "handle:small-instance-hours", "quantity": 10000, "price_point_id": 8712 }, { "component_id": "handle:large-instance-hours", "quantity": 100, "price_point_id": "handle:startup-pricing" } ] }'{ "renewal_preview": { "next_assessment_at": "2017-03-13T12:50:55-04:00", "subtotal_in_cents": 6000, "total_tax_in_cents": 0, "total_discount_in_cents": 0, "total_in_cents": 6000, "existing_balance_in_cents": 0, "total_amount_due_in_cents": 6000, "uncalculated_taxes": false, "line_items": [ { "transaction_type": "charge", "kind": "baseline", "amount_in_cents": 5000, "memo": "Gold Product (03/13/2017 - 04/13/2017)", "discount_amount_in_cents": 0, "taxable_amount_in_cents": 0, "product_id": 1, "product_handle": "gold-product", "product_name": "Gold Product", "period_range_start": "01/10/2024", "period_range_end": "02/10/2024" }, { "transaction_type": "charge", "kind": "quantity_based_component", "amount_in_cents": 1000, "memo": "Quantity Component: 10 Quantity Components", "discount_amount_in_cents": 0, "taxable_amount_in_cents": 0, "component_id": 104, "component_handle": "quantity-component", "component_name": "Quantity Component", "period_range_start": "01/10/2024", "period_range_end": "02/10/2024" } ] }}Cancel Dunning POST
Cancels the active dunning process for a subscription and sets it to active.
Migrate Subscription Product POST
Migrates a subscription to a different product. To create a migration, you must pass the `product_id` or `product_handle` in the object when you send a POST request. You can also pass either a `product_price_point_id` or `product_price_point_handle` to choose which price point the subscription is moved to. If no price point identifier is passed, the subscription is moved to the product's default price point. The response is the updated subscription. ## Valid Subscriptions Subscriptions should be in the `active` or `trialing` state to be migrated. (For backwards compatibility reasons, it is possible to migrate a subscription that is in the `trial_ended` state via the API, however this is not recommended. Since `trial_ended` is an end-of-life state, the subscription should be canceled, the product changed, and then the subscription can be reactivated.) For more information, see [Product Changes and Migrations](https://docs.maxio.com/hc/en-us/articles/24252069837581-Product-Changes-and-Migrations). ## Failed Migrations Important note: One of the most common ways that a migration can fail is when the attempt is made to migrate a subscription to its current product. ## 3D Secure (3DS) Authentication post-authentication flow When a payment requires 3DS Authentication to adhere to Strong Customer Authentication (SCA), the request enters a post-authentication flow where a 422 Unprocessable Entity status is returned with an action_link that will direct the customer through 3DS Authentication. See the [3D Secure Post-Authentication Flow](https://docs.maxio.com/hc/en-us/articles/44277749524365-3D-Secure-Post-Authentication-Flow) article in the product documentation to learn how to manage the redirect flow.