Subscriptions

Subscription Management Coupon

After creating subscriptions, either you or your customers will need to manage them to maintain them under a number of different scenarios.


One-Time Charges

Chargify allows you to add charges to a subscription outside of the regular recurring billing cycle. This is called a “one-time” charge though it simply refers to a charge that happens once and occurs from either submitting a charge via the API or by manually creating the charge in the app.

For example, if you wanted to add a charge of $1 - it would look like the following:

// POST /subscriptions/{subscription_id}/charges.json
{
    "charge":
    {
        "amount_in_cents": 100,
        "memo": "This is the description of the reason for the $1 charge."
    }
}

For more information on the API details for creating charges, see here.

Coupons and Adjustments

In general, coupons and adjustments are other methods of changing the amount billed to a customer either on a recurring basis (as with repeat use coupons) or on a more singular basis (as with single use coupons or balance adjustments).

Coupons

Are you looking to offer current or potential customers a discount? Chargify handles all of your promotional codes, discounts, and coupons with ease. Simply name the promotion, set your desired promo code, and enter the discount. You even have the power to control the expiration date and how long the promotion runs for in conjunction with your products.

Let’s create a coupon that we can then use when creating our next subscription.

// POST /coupons.json
{
    "coupon": {
        "name": "15% off",
        "code": "15OFF",
        "description": "15% off for life",
        "percentage": "15",
        "allow_negative_balance": "false",
        "recurring": "false",
        "end_date": "2012-08-29T12:00:00-04:00",
        "product_family_id": "2"
    }
}

To create a coupon, see here.

To use a coupon when creating a new subscription, please see here.

Please see the full API documentation for coupons for more detailed information.

Adjustments

Adjustments are similar to coupons, but they are must more simple. They are one-time changes to the balance of a subscription.

Let’s say you wanted to increase the balance of a subscription by $4 (perhaps for some error in billing), you would perform the following:

// POST /subscriptions/{subscription_id}/adjustments.json
{
    "adjustment": {
        "amount": "4.00",
        "memo": "This is the description of an adjustment on a subscription that increases the balance by a certain dollar amount."
    }
}

Please see the full API documentation for adjustments for more detailed information.

Billing Dates

A common method of managing a subscription might be for the billing date to change (as in the date the subscription is next processed/assessed and charges may potentially be captured from the payment method of the subscription). This is generally done: as a common method of extending or shortening trials, or processing the subscription “immediately” or just changing the billing date for use in calandar billing scenarios.

A quick example of updating the billing date for a subscription would look like the following:

/// POST /subscriptions/{subsciption_id}.json
{
    "subscription": {
        "next_billing_at": "2016-08-29T12:00:00-04:00"
    }
}

Please see the full API documentation for updating subscription assessment date for more information.

Product Changes

Every time you make a change to a product, Chargify will create a new “version” of the project. This allows you to:

  • Not disrupt users on the original version (before you made changes)
  • Keep a historical record of the product
  • “Move” subscriptions between versions of the product.

In terms of the API, there is no access to move subscriptions or modify old versions. The API will simply return the version along with the product information.

For more information about product versions, please see the following documentation.

Updating Payment Details

Updating the payment details is how you would change the card that somebody uses for their subscription. You can also use this method to simply change the expiration date of the card.

You can update the payment details in a few different ways:

Updating via Self-Service Pages

You may allow your users to update their information themselves, using the self-service public hosted pages or even the new billing portal.

For the public service page card update, you merely direct them to a specific URL:

https://{subdomain}.chargify.com/update_payment/{subscription_id}/{token}

  • The subdomain is just your subdomain. Our imaginary company “Acme”’s URL would start like the following: https://acme.chargify.com

  • The subscription_id would be the integer ID of the subscription as it is in the Chargify site/subdomain.

  • The token is calculated using the first 10 characters of the SHA-1 hex digest of this message:

message = "update_payment--{subscription_id}--{shared_key}"
token = SHA1(message)[0..9]

For more information about the self-service card update public page, please see the following.

Your users can also self-service update their payment method if using the Chargify Billing Portal feature, please see here for more information.

Updating via API

Updating the API is very useful in situations where you are more directly integrating with Chargify.

There are many methods of performing this action via the API, you can:

  1. Update the payment profile indirectly through a subscription update
  2. Update the payment profile directly

Updating the payment profile through a subscription update would look like the following:

Note - Partial card updates for Authorize.Net are not allowed via this endpoint.

/// PUT /subscriptions/{subscription_id}.json
{
    "subscription": {
        "credit_card_attributes": {
          "full_number": "2",
          "expiration_month": "10",
          "expiration_year": "2030"
        }
    }
}

Updating the payment profile directly would look like the following:

// PUT /payment_profiles/{payment_profile_id}.json
{
    "payment_profile": {
        "full_number": "2",
        "expiration_month": "10",
        "expiration_year": "2030"
    }
}

Please see the full API documentation for more complete documentation about updating payment profiles via the API.

Updating via Chargify Direct

Depending on how you want to integrate with Chargify, you may alternatively use the Chargify Direct method where the user submits their payment method update information directly to Chargify.

Input Attributes

In order for your request to be processed, you must set up Secure Parameters. See Chargify Direct Secure Parameters for detailed information on how to authenticate requests to this endpoint.

Note: the subscription_id MUST be part of your secure[data] parameter for the card update request to be processed.

  • payment_profile
    • first_name First name on card or bank account
    • last_name Last name on card or bank account
    • card_number The full credit card number (string representation, i.e. “5424000000000015”)
    • cvv (optional if the payment method is a credit card) The 3 or 4 digit card verification value.
    • expiration_month The 1- or 2-digit credit card expiration month, as an integer or string, i.e. “5”
    • expiration_year The 4-digit credit card expiration year, as an integer or string, i.e. “2012”
    • billing_address (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing street address (i.e. “123 Main St.”). This value is merely passed through to the payment gateway.
    • billing_address_2 (Optional) Second line of the customer’s billing address i.e. “Apt. 100”
    • billing_city (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address city (i.e. “Boston”). This value is merely passed through to the payment gateway.
    • billing_state (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address state (i.e. “MA”). This value is merely passed through to the payment gateway.
    • billing_zip (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address zip code (i.e. “12345”). This value is merely passed through to the payment gateway.
    • billing_country (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address country, preferably in ISO 3166-1 alpha-2 format (i.e. “US”). This value is merely passed through to the payment gateway. Some gateways require country codes in a specific format. Please check your gateway’s documentation. At this time, when creating a bank account, only US is accepted.
    • bank_name (Required when creating a subscription with ACH) The name of the bank where the customer’s account resides
    • bank_routing_number (Required when creating a subscription with ACH) The routing number of the bank
    • bank_account_number (Required when creating a subscription with ACH) The customer’s bank account number
    • bank_account_type (Required when creating a subscription with ACH) Either checking or savings
    • bank_account_holder_type (Required when creating a subscription with ACH) Either personal or business
    • payment_type Required for PayPal. Set to paypal_account.
    • payment_method_nonce Required for Paypal.
    • paypal_email Required for PayPal, but only used for display.

Example

<form method="post" action="https://api.chargify.com/api/v2/subscriptions/{subscription.id}/card_update">

  <!-- Secure parameters, for example: -->
  <input type="hidden" name="secure[data]" value="redirect_uri=http%3A%2F%2Fexample.com%2Fcallback&amp;subscription_id={subscription_id}"/>

  <!-- For brevity, this form contains no labels, only inputs -->
  <input type="text" name="payment_profile[first_name]" />
  <input type="text" name="payment_profile[last_name]" />

  <!-- begin credit card fields -->
  <input type="text" name="payment_profile[card_number]" />
  <input type="text" name="payment_profile[expiration_month]" />
  <input type="text" name="payment_profile[expiration_year]" />
  <input type="text" name="payment_profile[cvv]" />
  <!-- end credit card fields -->

  <!-- begin bank account fields -->
  <input type="text" name="payment_profile[bank_name]" />
  <input type="text" name="payment_profile[bank_routing_number]" />
  <input type="text" name="payment_profile[bank_account_number]" />
  <input type="text" name="payment_profile[bank_account_type]" />
  <input type="text" name="payment_profile[bank_account_holder_type]" />
  <!-- end bank account fields -->

  <!-- begin paypal account fields -->
  <input type="text" name="payment_profile[payment_method_nonce]" />
  <input type="text" name="payment_profile[paypal_email]" />
  <!-- end paypal account fields -->

  <input type="submit" value="Update" />
</form>

Output Attributes When Chargify redirects back to your {redirect_uri}, it will include the following query-string parameters:

  • api_id The API ID that made the original request
  • timestamp The reflected or auto-generated timestamp
  • nonce The reflected or auto-generated nonce
  • status_code An HTTP status code that represents the status of the request
  • result_code A Chargify-specific result code, that is related to the status code but may give more specific information about the result of your request
  • call_id The ID for the stored representation of the original Call (form post). The Call may be fetched via the API for full response information (for both success and fail scenarios).
  • signature The HMAC-SHA1 hexdigest of the previous parameters, to verify their integrity

Cancelling

Cancelling subscriptions is another common task that users will need to perform, or that is performed on their behalf when payment cannot be captured.

For example, if you wanted to cancel a subscription using the API:

// DELETE /subscriptions/{subscription_id}.json
{
    "subscription": {
        "cancellation_message": "Canceling the subscription via the API"
    }
}

It is also possible to cancel a subscription at the end of the current billing period, this is called a “delayed cancellation” and it’s API call would look like the following:

// DELETE /subscriptions/{subscription_id}.json
{
    "subscription": {
        "cancel_at_end_of_period": 1,
        "cancellation_message": "Canceling the subscription via the API"
    }
}

For information about cancelling using the API, please see Cancelling via API.

For information about cancelling subscriptions in general, please see Cancellation.

Refunds

When handing charging to any payment method, there are times when you will be required to refund. Refunds are only supported for the following gateways: Authorize.Net, Braintree Blue, Stripe, eWay Rapid, Payeezy (First Data), Elavon, Pin Payments, CyberSource, Payment Express, Paymill, Litle, QuickPay, Orbital, Trust Commerce, and Moneris. For gateways like Bambora, you will need to perform a “manual refund” in that you record the refund as a transaction directly after you perform the actual refund in your gateway account.

You can perform a non-manual refund using the API, like in the following example:

{
    "refund": {
        "payment_id": "{payment_id}",
        "amount": "4.00",
        "memo": "Your memo here."
    }
}

You will substitute values for payment_id, amount and memo in this example. The payment_id is the ID of the payment transaction that the credit will be applied to.

For more information, see API Refunds.

For a manual/external refund, the API call will be almost the exact same except you also supply a value for external:

{
    "refund": {
        "payment_id": "{payment_id}",
        "amount": "4.00",
        "memo": "Your memo here."
    },
    "external": 1
}

In the case of a manual or external refund, there will be nothing which is passed through on to your gateway - it will simply be added to the subscription, modifying the balance and adding a transaction record.

For more information, see API Refunds (External).

Subscription Updates via Billing Portal

Subscriptions can also be updated, at the hands of the subscriber, via the Billing Portal. The Billing Portal serves as a method to allow your subscribers to perform certain managerial actions against their current subscription. As a merchant, you have the ability to also restrict what actions can be performed by a subscriber.

As an example, here are a few examples of actions that can be performed via the Billing Portal:

  • Plan Changes
  • Subscription Cancellation
  • Credit Card Updates
  • Component Purchase/Allocation Updates

For more information on the Chargify Billing Portal, we encourage you to view our full documentation here.


Next Steps