Chargify Documentation » API v1 Resources

API: Migrations (Prorated Upgrades/Downgrades)

Chargify offers the ability to upgrade or downgrade a Customer’s subscription in the middle of a billing period, which is called a “Migration”. For details on how upgrades/downgrades work, and how to initiate them through the Admin Interface, see Upgrades/Downgrades.

If you want a migration with proration, then you want to continue with the methods listed below. However, if you just want to change the product the customer is subscribed to (with no proration) then you’ll just want to update the subscription product.

URIs

Resource/URI	POST
Migrations `/subscriptions/<subscription_id>/migrations`	Create new migration

Input Attributes

The Chargify API allows you initiate an upgrade/downgrade by posting JSON or XML that includes:

product_id or product_handle: The ID or handle of the target Product. A Subscription can be migrated to another product for both the current Product Family and another Product Family.
Note: Going to another Product Family, components will not be migrated as well.
include_trial: Boolean, default 0. If 1 is sent the customer will migrate to the new product with a trial if one is available. If 0 is sent, the trial period will be ignored.
include_initial_charge: Boolean, default 0. If 1 is sent initial charges will be assessed. If 0 is sent initial charges will be ignored.
include_coupons: Boolean, default 1. If 1 (or nothing) is sent, any coupons associated with the subscription will be applied to the migration. If 0 is sent, coupons will not be applied.

Methods

format may be either ‘xml’ or ‘json’.

Create

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/migrations.json
Method: POST
Required Parameters: product_id or product_handle
Response: The updated subscription
Usage Examples:
XML example
XML example, with trial
JSON example
JSON example, with trial

Preview

URL: https://<subdomain>.chargify.com/subscriptions/<subscription_id>/migrations/preview.json
Method: POST
Required Parameters: product_id or product_handle
Response: Calculated migration values:

prorated_adjustment_in_cents: Integer, The amount of the prorated adjustment that would be issued for the current subscription.
charge_in_cents: Integer, The amount of the charge that would be created for the new product.
payment_due_in_cents: Integer, The amount of the payment due in the case of an upgrade.
credit_applied_in_cents: Integer, The amount of the credit that would be left in the case of a downgrade.

Usage Examples:
XML example
JSON example

Usage Examples

XML Create Migration Example


Feature: Chargify Migrations Create XML API
  In order integrate my app with Chargify
  As a developer
  I want to migrate a subscription to a new product via the Chargify XML API

  Background:
    Given I am a valid API user
    And I send and accept xml

  Scenario: Migrate a subscription successfully with a product_id
    Given I have 2 products
    And I have an active subscription to the first product
    And I have this xml subscription data
      """
        <?xml version="1.0" encoding="UTF-8"?>
        <migration>
          <product_id>[@products.last.id]</product_id>
        </migration>
      """
    When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/migrations.xml
    Then the response status should be "200 OK"
    And the response should be the xml:
      """
      <?xml version="1.0" encoding="UTF-8"?>
      <subscription>
        <id type="integer">`auto generated`</id>
        <state>active</state>
        <balance_in_cents type="integer">`auto generated`</balance_in_cents>
        <current_period_started_at type="datetime">`auto generated`</current_period_started_at>
        <current_period_ends_at type="datetime">`auto generated`</current_period_ends_at>
        <trial_started_at type="datetime">`auto generated`</trial_started_at>
        <trial_ended_at type="datetime">`auto generated`</trial_ended_at>
        <activated_at type="datetime">`auto generated`</activated_at>
        <expires_at type="datetime">`auto generated`</expires_at>
        <created_at type="datetime">`auto generated`</created_at>
        <updated_at type="datetime">`auto generated`</updated_at>
        <cancellation_message nil="true"></cancellation_message>
        <customer>
          <id type="integer">`auto generated`</id>
          <first_name>`your value`</first_name>
          <last_name>`your value`</last_name>
          <email>`your value`</email>
          <organization>`your value`</organization>
          <reference>`your value`</reference>
          <created_at type="datetime">`auto generated`</created_at>
          <updated_at type="datetime">`auto generated`</updated_at>
        </customer>
        <product>
          <id>`auto generated`</id>
          <accounting_code>`your value`</accounting_code>
          <handle>`your value`</handle>
          <description>`your value`</description>
          <interval>`your value`</interval>
          <interval_unit>`your value`</interval_unit>
          <name>`your value`</name>
          <price_in_cents>`your value`</price_in_cents>
          <product_family>
            <id>`auto generated`</id>
            <accounting_code>`your value`</accounting_code>
            <handle>`your value`</handle>
            <name>`your value`</name>
            <description>`your value`</description>
          </product_family>
        </product>
        <credit_card>
          <card_type>bogus</card_type>
          <expiration_month type="integer">`your value`</expiration_month>
          <expiration_year type="integer">`your value`</expiration_year>
          <first_name>`your value`</first_name>
          <last_name>`your value`</last_name>
          <masked_card_number>XXXX-XXXX-XXXX-1</masked_card_number>
        </credit_card>
      </subscription>
      """

XML Create Migration Example, with trial


Feature: Chargify Migrations Create XML API
  In order integrate my app with Chargify
  As a developer
  I want to migrate a subscription to a new product via the Chargify XML API

  Background:
    Given I am a valid API user
    And I send and accept xml

  Scenario: Migrate a subscription successfully with a trial
    Given I have 2 products
    And I have an active subscription to the first product
    And the second product has a trial
    And I have this xml subscription data
      """
        <?xml version="1.0" encoding="UTF-8"?>
        <migration>
          <product_id>[@products.last.id]</product_id>
          <include_trial>1</include_trial>
        </migration>
      """
    When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/migrations.xml?product_id=[@products.last.id]
    Then the response status should be "200 OK"
    And the subscription should be trialing

JSON Create Migration Example


Feature: Chargify Migrations Create JSON API
  In order integrate my app with Chargify
  As a developer
  I want to migrate a subscription to a new product via the Chargify JSON API

  Background:
    Given I am a valid API user
    And I send and accept json

  Scenario: Migrate a subscription successfully with a product_id
    Given I have 2 products
    And I have an active subscription to the first product
    And I have this json subscription data
      """
       {"migration":{
         "product_id": [@products.last.id]
       }}
      """
    When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/migrations.json
    Then the response status should be "200 OK"
    And the response should be the json:
      """
      {"subscription":{
        "id":[@subscription.id],
        "state":"active",
        "balance_in_cents":`auto generated`,
        "current_period_started_at":`auto generated`,
        "current_period_ends_at":`auto generated`,
        "activated_at":`auto generated`,
        "trial_ended_at":`auto generated`,
        "trial_started_at":`auto generated`,
        "expires_at":`auto generated`,
        "created_at":`auto generated`,
        "updated_at":`auto generated`,
        "cancellation_message":null,
        "customer":{
          "id":`auto generated`,
          "first_name":`your value`,
          "last_name":`your value`,
          "email":`your value`,
          "organization":`your value`,
          "reference":`your value`,
          "updated_at":`auto generated`,
          "created_at":`auto generated`
        },
        "product":{
          "id":[@products.last.id],
          "name":"[@products.last.name]",
          "handle":"[@products.last.handle]",
          "price_in_cents":[@products.last.price_in_cents],
          "accounting_code":"[@products.last.accounting_code]",
          "description":`your value`,
          "interval":[@products.last.interval],
          "interval_unit":"[@products.last.interval_unit]",
          "product_family":{
            "id":[@products.last.product_family.id],
            "name":"[@products.last.product_family.name]",
            "handle":"[@products.last.product_family.handle]",
            "accounting_code":"[@products.last.product_family.accounting_code]",
            "description":`your value`
          }
        },
        "credit_card":{
          "first_name":`your value`,
          "last_name":`your value`,
          "masked_card_number":`your value`,
          "card_type":`auto generated`,
          "expiration_month":`your value`,
          "expiration_year":`your value`
        }
      }}
      """

JSON Create Migration Example, with trial


Feature: Chargify Migrations Create JSON API
  In order integrate my app with Chargify
  As a developer
  I want to migrate a subscription to a new product via the Chargify JSON API

  Background:
    Given I am a valid API user
    And I send and accept json

  Scenario: Migrate a subscription successfully with a trial
    Given I have 2 products
    And I have an active subscription to the first product
    And the second product has a trial
    And I have this json subscription data
      """
      {"migration":{
        "product_id": [@products.last.id],
        "include_trial": 1
      }}
      """
    When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/migrations.json
    Then the response status should be "200 OK"
    And the subscription should be trialing
    And the response should be the json:

XML Migration Preview Example


Feature: Chargify Migrations Preview XML API
  Given I have 2 products
  And the first product costs $250
  And the second product costs $900
  And I have an active subscription to the first product
  And it is halfway through the month
  And I have this xml migration data
    """
      <?xml version="1.0" encoding="UTF-8"?>
      <migration>
        <product_id>[@products.last.id]</product_id>
      </migration>
    """
  When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/migrations/preview.xml
  Then the response status should be "200 OK"
  And the response should be the xml:
    """
    <?xml version="1.0" encoding="UTF-8"?>
    <migration>
      <prorated_adjustment_in_cents>-12500</prorated_adjustment_in_cents>
      <charge_in_cents>90000</charge_in_cents>
      <payment_due_in_cents>77500</payment_due_in_cents>
      <credit_applied_in_cents>0</credit_applied_in_cents>
    </migration>
    """

JSON Migration Preview Example


Feature: Chargify Migrations Preview JSON API
  Given I have 2 products
  And the first product costs $250
  And the second product costs $900
  And I have an active subscription to the first product
  And it is halfway through the month
  And I have this json migration data
    """
    {"migration":{
      "product_id": [@products.last.id]
    }}
    """
  When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id]/migrations/preview.json
  Then the response status should be "200 OK"
  And the response should be the json:
    """
    {"migration":{
      "prorated_adjustment_in_cents":-12500,
      "charge_in_cents":90000,
      "payment_due_in_cents":77500,
      "credit_applied_in_cents":0
    }}
    """

Next page: API: Products
Previous page: API: Metered Usage