Migrate Subscription Product
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.
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 article in the product documentation to learn how to manage the redirect flow.
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
Response Body
application/json
application/json
curl -X POST "https://example.com/subscriptions/0/migrations.json" \ -H "Content-Type: application/json" \ -d '{ "migration": { "product_id": 3801242, "include_trial": false, "include_initial_charge": false, "include_coupons": true, "preserve_period": true } }'{ "subscription": { "id": 15054201, "state": "trialing", "trial_started_at": "2016-11-03T13:43:36-04:00", "trial_ended_at": "2016-11-10T12:43:36-05:00", "activated_at": "2016-11-02T10:20:57-04:00", "created_at": "2016-11-02T10:20:55-04:00", "updated_at": "2016-11-03T13:43:36-04:00", "expires_at": null, "balance_in_cents": -13989, "current_period_ends_at": "2016-11-10T12:43:36-05:00", "next_assessment_at": "2016-11-10T12:43:36-05:00", "canceled_at": null, "cancellation_message": null, "next_product_id": null, "cancel_at_end_of_period": false, "payment_collection_method": "automatic", "snap_day": null, "cancellation_method": null, "current_period_started_at": "2016-11-03T13:43:35-04:00", "previous_state": "active", "signup_payment_id": 160680121, "signup_revenue": "0.00", "delayed_cancel_at": null, "coupon_code": null, "total_revenue_in_cents": 14000, "product_price_in_cents": 1000, "product_version_number": 6, "payment_type": "credit_card", "referral_code": "ghnhvy", "coupon_use_count": null, "coupon_uses_allowed": null, "customer": { "id": 14543792, "first_name": "Frankie", "last_name": "Test", "organization": null, "email": "testfrankie111@test.com", "created_at": "2016-11-02T10:20:55-04:00", "updated_at": "2016-11-02T10:20:58-04:00", "reference": null, "address": null, "address_2": null, "city": null, "state": null, "zip": null, "country": null, "phone": "5555551212", "portal_invite_last_sent_at": "2016-11-02T10:20:58-04:00", "portal_invite_last_accepted_at": null, "verified": false, "portal_customer_created_at": "2016-11-02T10:20:58-04:00", "cc_emails": null }, "product": { "id": 3861800, "name": "Trial Product", "handle": "trial-product", "description": "Trial period with payment expected at end of trial.", "accounting_code": "", "request_credit_card": true, "expiration_interval": null, "expiration_interval_unit": "never", "created_at": "2016-07-08T09:53:55-04:00", "updated_at": "2016-09-05T13:00:36-04:00", "price_in_cents": 1000, "interval": 1, "interval_unit": "month", "initial_charge_in_cents": null, "trial_price_in_cents": 0, "trial_interval": 7, "trial_interval_unit": "day", "archived_at": null, "require_credit_card": true, "return_params": "", "taxable": false, "update_return_url": "", "initial_charge_after_trial": false, "version_number": 6, "update_return_params": "", "product_family": { "id": 527890, "name": "Acme Projects", "description": "", "handle": "billing-plans", "accounting_code": null }, "public_signup_pages": [ { "id": 294791, "return_url": "", "return_params": "", "url": "https://general-goods.chargify.com/subscribe/xv52yrcc3byx/trial-product" } ] }, "credit_card": { "id": 10088716, "first_name": "F", "last_name": "NB", "masked_card_number": "XXXX-XXXX-XXXX-1", "card_type": "bogus", "expiration_month": 1, "expiration_year": 2017, "customer_id": 14543792, "current_vault": "bogus", "vault_token": "1", "billing_address": "123 Montana Way", "billing_city": "Billings", "billing_state": "MT", "billing_zip": "59101", "billing_country": "US", "customer_vault_token": null, "billing_address_2": "Apt. 10", "payment_type": "credit_card" } }}Preview Renewal POST
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](https://maxio.zendesk.com/hc/en-us/articles/24252493695757-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_quantity` for quantity-based components * Current enabled/disabled status for on/off components * Current metered usage `unit_balance` for 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.
Preview Subscription Product Migration POST
Previews the charges resulting from migrating a subscription to a different product. ## Previewing a future date It is also possible to preview the migration for a date in the future, as long as it's still within the subscription's current billing period, by passing a `proration_date` along with the request (e.g., `"proration_date": "2020-12-18T18:25:43.511Z"`). This will calculate the prorated adjustment, charge, payment and credit applied values assuming the migration is done at that date in the future as opposed to right now.