Class: AdvancedBilling::SubscriptionsController

Inherits:
BaseController show all
Defined in:
lib/advanced_billing/controllers/subscriptions_controller.rb

Overview

SubscriptionsController

Constant Summary

Constants inherited from BaseController

BaseController::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseController

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseController

#initialize, #new_api_call_builder, #new_parameter, #new_request_builder, #new_response_handler, user_agent, user_agent_parameters

Constructor Details

This class inherits a constructor from AdvancedBilling::BaseController

Instance Method Details

#activate_subscription(subscription_id, body: nil) ⇒ SubscriptionResponse

Chargify offers the ability to activate awaiting signup and trialing subscriptions. This feature is only available on the Relationship Invoicing architecture. Subscriptions in a group may not be activated immediately. For details on how the activation works, and how to activate subscriptions through the application, see activation. The revert_on_failure parameter controls the behavior upon activation failure.

  • If set to true and something goes wrong i.e. payment fails, then Chargify will not change the subscription's state. The subscription’s billing period will also remain the same.
  • If set to false and something goes wrong i.e. payment fails, then Chargify will continue through with the activation and enter an end of life state. For trialing subscriptions, that will either be trial ended (if the trial is no obligation), past due (if the trial has an obligation), or canceled (if the site has no dunning strategy, or has a strategy that says to cancel immediately). For awaiting signup subscriptions, that will always be canceled. The default activation failure behavior can be configured per activation attempt, or you may set a default value under Config > Settings > Subscription Activation Settings.

Activation Scenarios

Activate Awaiting Signup subscription

  • Given you have a product without trial
  • Given you have a site without dunning strategy
  flowchart LR
    AS[Awaiting Signup] --> A{Activate}
    A -->|Success| Active
    A -->|Failure| ROF{revert_on_failure}
    ROF -->|true| AS
    ROF -->|false| Canceled
  • Given you have a product with trial
  • Given you have a site with dunning strategy
  flowchart LR
    AS[Awaiting Signup] --> A{Activate}
    A -->|Success| Trialing
    A -->|Failure| ROF{revert_on_failure}
    ROF -->|true| AS
    ROF -->|false| PD[Past Due]

Activate Trialing subscription

You can read more about the behavior of trialing subscriptions [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404494617357# trialing-subscriptions-0-0). When the revert_on_failure parameter is set to true, the subscription's state will remain as Trialing, we will void the invoice from activation and return any prepayments and credits applied to the invoice back to the subscription. subscription

Parameters:

  • subscription_id (String) —

    Required parameter: The Chargify id of the

  • body (ActivateSubscriptionRequest) (defaults to: nil) —

    Optional parameter: Example:

Returns:



898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 898

def activate_subscription(subscription_id,
                          body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/subscriptions/{subscription_id}/activate.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionResponse.method(:from_hash))
                .local_error('400',
                             'Bad Request',
                             NestedErrorResponseException))
    .execute
end

#apply_coupon_to_subscription(subscription_id, code: nil, body: nil) ⇒ SubscriptionResponse

An existing subscription can accommodate multiple discounts/coupon codes. This is only applicable if each coupon is stackable. For more information on stackable coupons, we recommend reviewing our [coupon documentation.](https://chargify.zendesk.com/hc/en-us/articles/44077559095 31#stackable-coupons)

Query Parameters vs Request Body Parameters

Passing in a coupon code as a query parameter will add the code to the subscription, completely replacing all existing coupon codes on the subscription. For this reason, using this query parameter on this endpoint has been deprecated in favor of using the request body parameters as described below. When passing in request body parameters, the list of coupon codes will simply be added to any existing list of codes on the subscription. subscription be applied to a subscription

Parameters:

  • subscription_id (String) —

    Required parameter: The Chargify id of the

  • code (String) (defaults to: nil) —

    Optional parameter: A code for the coupon that would

  • body (AddCouponsRequest) (defaults to: nil) —

    Optional parameter: Example:

Returns:



1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 1331

def apply_coupon_to_subscription(subscription_id,
                                 code: nil,
                                 body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/add_coupon.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .query_param(new_parameter(code, key: 'code'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionResponse.method(:from_hash))
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             SubscriptionAddCouponErrorException))
    .execute
end

#create_prepaid_subscription(subscription_id, body: nil) ⇒ PrepaidConfigurationResponse

Use this endpoint to update a subscription's prepaid configuration. subscription Example:

Parameters:

Returns:



1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 1291

def create_prepaid_subscription(subscription_id,
                                body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/prepaid_configurations.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PrepaidConfigurationResponse.method(:from_hash)))
    .execute
end

#create_subscription(body: nil) ⇒ SubscriptionResponse

Full documentation on how subscriptions operate within Chargify can be located under the following topics:

  • [Subscriptions Reference](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405577172 749-Subscription-Introduction)
  • [Subscriptions Actions](https://maxio-chargify.zendesk.com/hc/en-us/articles/540551055655 7-Actions)
  • [Subscription Cancellation](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405510 556557-Actions#initiate-cancellation)
  • [Subscription Reactivation](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404559 291021-Reactivating-and-Resuming)
  • [Subscription Import](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404863655821 -Imports) When creating a subscription, you must specify a product and a customer. Credit card details may be required, depending on the options for the Product being subscribed ([see Product Options](https://maxio-chargify.zendesk.com/hc/en-us/articles/540524678222 1#payment-method-settings)). The product may be specified by product_id or by product_handle (API Handle). In similar fashion, to pass a particular product price point, you may either use product_price_point_handle or product_price_point_id. An existing customer may be specified by a customer_id (ID within Chargify) or a customer_reference (unique value within your app that you have shared with Chargify via the reference attribute on a customer). You may also pass in an existing payment profile for that customer with payment_profile_id. A new customer may be created by providing customer_attributes. Credit card details may be required, depending on the options for the product being subscribed. The product can be specified by product_id or by product_handle (API Handle). If you are creating a subscription with a payment profile, the attribute to send will be credit_card_attributes or bank_account_attributes for ACH and Direct Debit. That said, when you read the subscription after creation, we return the profile details under credit_card or bank_account.

Taxable Subscriptions

If your intent is to charge your subscribers tax via [Avalara Taxes](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405275711885- Avalara-VAT-Tax) or [Custom Taxes](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405069041549- Custom-Taxes), there are a few considerations to be made regarding collecting subscription data. For subscribers to be eligible to be taxed, the following information for the customer object or payment_profile object must by supplied:

Subscription Request Examples

The subscription examples below will be split into two sections. The first section, "Subscription Customization", will focus on passing different information with a subscription, such as components, calendar billing, and custom fields. These examples will presume you are using a secure chargify_token generated by Chargify.js. The second section, "Passing Payment Information", will focus on passing payment information into Chargify. Please be aware that collecting and sending Chargify raw card details requires PCI compliance on your end; these examples are provided as guidance. If your business is not PCI compliant, we recommend using Chargify.js to collect credit cards or bank accounts.

Subscription Customization

With Components

Different components require slightly different data. For example, quantity-based and on/off components accept allocated_quantity, while metered components accept unit_balance. When creating a subscription with a component, a price_point_id can be passed in along with the component_id to specify which price point to use. If not passed in, the default price point will be used. Note: if an invalid price_point_id is used, the subscription will still proceed but will use the component's default price point. Components and their price points may be added by ID or by handle. See the example request body labeled "Components By Handle (Quantity-Based)"; the format will be the same for other component types.

With Coupon(s)

Pass an array of coupon_codes. See the example request body "With Coupon".

With Manual Invoice Collection

The invoice collection method works only on legacy Statement Architecture. On Relationship Invoicing Architecture use the remittance collection method.

Prepaid Subscription

A prepaid subscription can be created with the usual subscription creation parameters, specifying prepaid as the payment_collection_method and including a nested prepaid_subscription_configuration. After a prepaid subscription has been created, additional funds can be manually added to the prepayment account through the [Create Prepayment Endpoint](https://developers.chargify.com/docs/api-docs/7ec482de77ba7-crea te-prepayment). Prepaid subscriptions do not work on legacy Statement Architecture.

With Metafields

Metafields can either attach to subscriptions or customers. Metafields are popuplated with the supplied metadata to the resource specified. If the metafield doesn't exist yet, it will be created on-the-fly.

With Custom Pricing

Custom pricing is pricing specific to the subscription in question. Create a subscription with custom pricing by passing pricing information instead of a price point. For a custom priced product, pass the custom_price object in place of product_price_point_id. For a custom priced component, pass the custom_price object within the component object. Custom prices and price points can exist in harmony on a subscription.

Passing Payment Information

Subscription with Chargify.js token

The chargify_token can be obtained using [chargify.js](https://developers.chargify.com/docs/developer-docs/ZG9jOjE0 NjAzNDI0-overview). The token represents payment profile attributes that were provided by the customer in their browser and stored at the payment gateway. The payment_type attribute may either be credit_card or bank_account, depending on the type of payment method being added. If a bank account is being passed, the payment attributes should be changed to bank_account_attributes.

{
  "subscription": {
    "product_handle": "pro-plan",
    "customer_attributes": {
      "first_name": "Joe",
      "last_name": "Smith",
      "email": "[email protected]"
    },
    "credit_card_attributes": {
      "chargify_token": "tok_cwhvpfcnbtgkd8nfkzf9dnjn",
      "payment_type": "credit_card"
    }
  }
}

Subscription with vault token

If you already have a customer and card stored in your payment gateway, you may create a subscription with a vault_token. Providing the last_four, card type and expiration date will allow the card to be displayed properly in the Chargify UI.

{
  "subscription": {
    "product_handle": "pro-plan",
    "customer_attributes": {
      "first_name": "Joe",
      "last_name": "Smith",
      "email": "[email protected]"
    },
    "credit_card_attributes": {
      first_name: "Joe,
      last_name: "Smith",
      card_type: "visa",
      expiration_month: "05",
      expiration_year: "2025",
      last_four: "1234",
      vault_token: "12345abc",
      current_vault: "braintree_blue"
  }
}

Subscription with Credit Card

"subscription": {
    "product_handle": "basic",
    "customer_attributes": {
      "first_name": "Joe",
      "last_name": "Blow",
      "email": "[email protected]",
      "zip": "02120",
      "state": "MA",
      "reference": "XYZ",
      "phone": "(617) 111 - 0000",
      "organization": "Acme",
      "country": "US",
      "city": "Boston",
      "address_2": null,
      "address": "123 Mass Ave."
    },
    "credit_card_attributes": {
      "last_name": "Smith",
      "first_name": "Joe",
      "full_number": "4111111111111111",
      "expiration_year": "2021",
      "expiration_month": "1",
      "card_type": "visa",
      "billing_zip": "02120",
      "billing_state": "MA",
      "billing_country": "US",
      "billing_city": "Boston",
      "billing_address_2": null,
      "billing_address": "123 Mass Ave."
    }
}

Subscription with ACH as Payment Profile

{
  "subscription": {
    "product_handle": "gold-product",
    "customer_attributes": {
      "first_name": "Joe",
      "last_name": "Blow",
      "email": "[email protected]",
      "zip": "02120",
      "state": "MA",
      "reference": "XYZ",
      "phone": "(617) 111 - 0000",
      "organization": "Acme",
      "country": "US",
      "city": "Boston",
      "address_2": null,
      "address": "123 Mass Ave."
    },
    "bank_account_attributes": {
      "bank_name": "Best Bank",
      "bank_routing_number": "021000089",
      "bank_account_number": "111111111111",
      "bank_account_type": "checking",
      "bank_account_holder_type": "business",
      "payment_type": "bank_account"
    }
  }
}

Subscription with PayPal payment profile

With the nonce from Braintree JS

{ "subscription": {
    "product_handle":"test-product-b",
    "customer_attributes": {
      "first_name":"Amelia",
      "last_name":"Johnson",
      "email":"[email protected]",
      "organization":"My Awesome Company"
    },
    "payment_profile_attributes":{
      "paypal_email": "[email protected]",
      "current_vault": "braintree_blue",
      "payment_method_nonce":"abc123",
      "payment_type":"paypal_account"
    }
  }

With the Braintree Customer ID as the vault token:

{ "subscription": {
    "product_handle":"test-product-b",
    "customer_attributes": {
      "first_name":"Amelia",
      "last_name":"Johnson",
      "email":"[email protected]",
      "organization":"My Awesome Company"
    },
    "payment_profile_attributes":{
      "paypal_email": "[email protected]",
      "current_vault": "braintree_blue",
      "vault_token":"58271347",
      "payment_type":"paypal_account"
    }
  }

Subscription using GoCardless Bank Number

These examples creates a customer, bank account and mandate in GoCardless. For more information on GoCardless, please view the following two resources:

{
  "subscription": {
    "product_handle": "gold-product",
    "customer_attributes": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]"
    },
    "bank_account_attributes": {
      "bank_name": "Royal Bank of France",
      "bank_account_number": "0000000",
      "bank_routing_number": "0003",
      "bank_branch_code": "00006",
      "payment_type": "bank_account",
      "billing_address": "20 Place de la Gare",
      "billing_city": "Colombes",
      "billing_state": "Île-de-France",
      "billing_zip": "92700",
      "billing_country": "FR"
    }
  }
}

Subscription using GoCardless IBAN Number

{
  "subscription": {
    "product_handle": "gold-product",
    "customer_attributes": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]"
    },
    "bank_account_attributes": {
      "bank_name": "French Bank",
      "bank_iban": "FR1420041010050500013M02606",
      "payment_type": "bank_account",
      "billing_address": "20 Place de la Gare",
      "billing_city": "Colombes",
      "billing_state": "Île-de-France",
      "billing_zip": "92700",
      "billing_country": "FR"
    }
  }
}

Subscription using Stripe SEPA Direct Debit

For more information on Stripe Direct Debit, please view the following two resources:

{
  "subscription": {
    "product_handle": "gold-product",
    "customer_attributes": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]"
    },
    "bank_account_attributes": {
      "bank_name": "Test Bank",
      "bank_iban": "DE89370400440532013000",
      "payment_type": "bank_account"
    }
  }
}

Subscription using Stripe BECS Direct Debit

For more information on Stripe Direct Debit, please view the following two resources:

{
  "subscription": {
    "product_handle": "gold-product",
    "customer_attributes": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]"
    },
    "bank_account_attributes": {
      "bank_name": "Test Bank",
      "bank_branch_code": "000000",
      "bank_account_number": "000123456",
      "payment_type": "bank_account"
    }
  }
}

3D Secure - Stripe

It may happen that a payment needs 3D Secure Authentication when the subscription is created; this is referred to in our help docs as a [post-authentication flow](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405177432077#p sd2-flows-pre-authentication-and-post-authentication). The server returns 422 Unprocessable Entity in this case with the following response:

{
  "errors": [
    "Your card was declined. This transaction requires 3D secure
authentication."
  ],
  "gateway_payment_id": "pi_1F0aGoJ2UDb3Q4av7zU3sHPh",
  "description": "This card requires 3D secure authentication. Redirect
the customer to the URL from the action_link attribute to authenticate.
Attach callback_url param to this URL if you want to be notified about the
result of 3D Secure authentication. Attach redirect_url param to this URL
if you want to redirect a customer back to your page after 3D Secure
authentication. Example:
https://mysite.chargify.com/3d-secure/pi_1FCm4RKDeye4C0XfbqquXRYm?one_time
_token_id=128&callback_url=https://localhost:4000&redirect_url=https://you
rpage.com will do a POST request to https://localhost:4000 after payment
is authenticated and will redirect a customer to https://yourpage.com
after 3DS authentication.",
  "action_link":
"http://acme.chargify.com/3d-secure/pi_1F0aGoJ2UDb3Q4av7zU3sHPh?one_time_t
oken_id=242"
}

To let the customer go through 3D Secure Authentication, they need to be redirected to the URL specified in action_link. Optionally, you can specify callback_url parameter in the action_link URL if you’d like to be notified about the result of 3D Secure Authentication. The callback_url will return the following information:

  • whether the authentication was successful (success)
  • the gateway ID for the payment (gateway_payment_id)
  • the subscription ID (subscription_id) Lastly, you can also specify a redirect_url within the action_link URL if you’d like to redirect a customer back to your site. It is not possible to use action_link in an iframe inside a custom application. You have to redirect the customer directly to the action_link, then, to be notified about the result, use redirect_url or callback_url. The final URL that you send a customer to to complete 3D Secure may resemble the following, where the first half is the action_link and the second half contains a redirect_url and callback_url: https://mysite.chargify.com/3d-secure/pi_1FCm4RKDeye4C0XfbqquXRYm?one_tim e_token_id=128&callback_url=https://localhost:4000&redirect_url=https://yo urpage.com

3D Secure - Checkout

It may happen that a payment needs 3D Secure Authentication when the subscription is created; this is referred to in our help docs as a [post-authentication flow](https://maxio-chargify.zendesk.com/hc/en-us/articles/5405177432077#p sd2-flows-pre-authentication-and-post-authentication). The server returns 422 Unprocessable Entity in this case with the following response:

{
  "errors": [
    "Your card was declined. This transaction requires 3D secure
authentication."
  ],
  "gateway_payment_id": "pay_6gjofv7dlyrkpizlolsuspvtiu",
  "description": "This card requires 3D secure authentication. Redirect
the customer to the URL from the action_link attribute to authenticate.
Attach callback_url param to this URL if you want to be notified about the
result of 3D Secure authentication. Attach redirect_url param to this URL
if you want to redirect a customer back to your page after 3D Secure
authentication. Example:
https://mysite.chargify.com/3d-secure/pay_6gjofv7dlyrkpizlolsuspvtiu?one_t
ime_token_id=123&callback_url=https://localhost:4000&redirect_url=https://
yourpage.com will do a POST request to https://localhost:4000 after
payment is authenticated and will redirect a customer to
https://yourpage.com after 3DS authentication.",
  "action_link":
"http://mysite.chargify.com/3d-secure/pay_6gjofv7dlyrkpizlolsuspvtiu?one_t
ime_token_id=123"
}

To let the customer go through 3D Secure Authentication, they need to be redirected to the URL specified in action_link. Optionally, you can specify callback_url parameter in the action_link URL if you’d like to be notified about the result of 3D Secure Authentication. The callback_url will return the following information:

  • whether the authentication was successful (success)
  • the gateway ID for the payment (gateway_payment_id)
  • the subscription ID (subscription_id) Lastly, you can also specify a redirect_url parameter within the action_link URL if you’d like to redirect a customer back to your site. It is not possible to use action_link in an iframe inside a custom application. You have to redirect the customer directly to the action_link, then, to be notified about the result, use redirect_url or callback_url. The final URL that you send a customer to complete 3D Secure may resemble the following, where the first half is the action_link and the second half contains a redirect_url and callback_url: https://mysite.chargify.com/3d-secure/pay_6gjofv7dlyrkpizlolsuspvtiu?one_ time_token_id=123&callback_url=https://localhost:4000&redirect_url=https:/ /yourpage.com

Example Redirect Flow

You may wish to redirect customers to different pages depending on whether their SCA was performed successfully. Here's an example flow to use as a reference:

  1. Create a subscription via API; it requires 3DS
  2. You receive a gateway_payment_id in the action_link along other params in the response.
  3. Use this gateway_payment_id to, for example, connect with your internal resources or generate a session_id
  4. Include 1 of those attributes inside the callback_url and redirect_url to be aware which “session” this applies to
  5. Redirect the customer to the action_link with callback_url and redirect_url applied
  6. After the customer finishes 3DS authentication, we let you know the result by making a request to applied callback_url.
  7. After that, we redirect the customer to the redirect_url; at this point the result of authentication is known
  8. Optionally, you can use the applied "msg" param in the redirect_url to determine whether it was successful or not

Subscriptions Import

Subscriptions can be “imported” via the API to handle the following scenarios:

  • You already have existing subscriptions with specific start and renewal dates that you would like to import to Chargify
  • You already have credit cards stored in your provider’s vault and you would like to create subscriptions using those tokens Before importing, you should have already set up your products to match your offerings. Then, you can create Subscriptions via the API just like you normally would, but using a few special attributes. Full documentation on how import Subscriptions using the import tool in the Chargify UI can be located [here](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404863655821# imports-0-0).

Important Notices and Disclaimers regarding Imports

Before performing a bulk import of subscriptions via the API, we suggest reading the [Subscriptions Import](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404863655821 #important-notices-and-disclaimers) instructions to understand the repurcussions of a large import.

Subscription Input Attributes

The following additional attributes to the subscription input attributes make imports possible: next_billing_at, previous_billing_at, and import_mrr.

Current Vault

If you are using a Legacy gateway such as "eWAY Rapid (Legacy)" or "Stripe (Legacy)" then please contact Support for further instructions on subscription imports.

Braintree Blue (Braintree v2) Imports

Braintree Blue is Braintree’s newer (version 2) API. For this gateway, please provide the vault_token parameter with the value from Braintree’s “Customer ID” rather than the “Payment Profile Token”. At this time we do not use current_vault_token with the Braintree Blue gateway, and we only support a single payment profile per Braintree Customer. When importing PayPal type payment profiles, please set payment_type to paypal_account.

Stripe ACH Imports

If the bank account has already been verified, currently you will need to create the customer, create the payment profile in Chargify - setting verified=true, then create a subscription using the customer_id and payment_profile_id.

Webhooks During Import

If no next_billing_at is provided, webhooks will be fired as normal. If you do set a future next_billing_at, only a subset of the webhooks are fired when the subscription is created. Keep reading for more information as to what webhooks will be fired under which scenarios.

Successful creation with Billing Date

Scenario: If next_billing_at provided

  • signup_success
  • billing_date_change

Successful creation without Billing Date

Scenario: If no next_billing_at provided

  • signup_success
  • payment_success

Unsuccessful creation

Scenario: If card can’t be charged, and no next_billing_at provided

  • signup_failure

Webhooks fired when next_billing_at is reached:

  • renewal_success or renewal_failure
  • payment_success or payment_failure

Date and Time Formats

We will attempt to parse any string you send as the value of next_billing_at in to a date or time. For best results, use a known format like described in “Date and Time Specification” of RFC 2822 or ISO 8601 . The following are all equivalent and will work as input to next_billing_at:

Aug 06 2030 11:34:00 -0400
Aug 06 2030 11:34 -0400
2030-08-06T11:34:00-04:00
8/6/2030 11:34:00 EDT
8/6/2030 8:34:00 PDT
2030-08-06T15:34:00Z

You may also pass just a date, in which case we will assume the time to be noon

2010-08-06

Subscription Hierarchies & WhoPays

When subscription groups were first added to our Relationship Invoicing architecture, to group together invoices for related subscriptions and allow for complex customer hierarchies and WhoPays scenarios, they were designed to consist of a primary and a collection of group members. The primary would control many aspects of the group, such as when the consolidated invoice is generated. As of today, groups still function this way. In the future, the concept of a "primary" will be removed in order to offer more flexibility into group management and reduce confusion concerning what actions must be done on a primary level, rather than a member level. We have introduced a two scheme system as a bridge between these two group organizations. Scheme 1, which is relevant to all subscription groups today, marks the group as being "ruled" by a primary. When reading a subscription via API, they will return a top-level attribute called group, which will denote which scheme is being used. At this time, the scheme attribute will always be 1.

Subscription in a Customer Hierarchy

For sites making use of the [Relationship Billing](https://maxio-chargify.zendesk.com/hc/en-us/articles/540507879425 3-Introduction-to-Invoices) and [Customer Hierarchy](https://maxio-chargify.zendesk.com/hc/en-us/articles/5404900384 141) features, it is possible to create subscriptions within a customer hierarchy. This can be achieved through the API by passing group parameters in the Create Subscription request.

  • The group parameters are optional and consist of the required target and optional billing parameters. When the target parameter specifies a customer that is already part of a hierarchy, the new subscription will become a member of the customer hierarchy as well. If the target customer is not part of a hierarchy, a new customer hierarchy will be created and both the target customer and the new subscription will become part of the hierarchy with the specified target customer set as the responsible payer for the hierarchy's subscriptions. Rather than specifying a customer, the target parameter could instead simply have a value of self which indicates the subscription will be paid for not by some other customer, but by the subscribing customer. This will be true whether the customer is being created new, is already part of a hierarchy, or already exists outside a hierarchy. A valid payment method must also be specified in the subscription parameters. Note that when creating subscriptions in a customer hierarchy, if the customer hierarchy does not already have a payment method, passing valid credit card attributes in the subscription parameters will also result in the payment method being established as the default payment method for the customer hierarchy irrespective of the responsible payer. The optional billing parameters specify how some aspects of the billing for the new subscription should be handled. Rather than capturing payment immediately, the accrue parameter can be included so that the new subscription charges accrue until the next assessment date. Regarding the date, the align_date parameter can be included so that the billing date of the new subscription matches up with the default subscription group in the customer hierarchy. When choosing to align the dates, the prorate parameter can also be specified so that the new subscription charges are prorated based on the billing period of the default subscription group in the customer hierarchy also.

Subscription in a Subscription Group

For sites making use of [Relationship Billing](https://maxio-chargify.zendesk.com/hc/en-us/articles/540507879425 3-Introduction-to-Invoices) it may be desireable to create a subscription as part of a subscription group in order to rely on [invoice consolidation](https://maxio-chargify.zendesk.com/hc/en-us/articles/540498 0119949). This can be achieved through the API by passing group parameters in the Create Subscription request. The group parameters are optional and consist of the required target and optional billing parameters. The target parameters specify an existing subscription with which the newly created subscription should be grouped. If the target subscription is already part of a group, the new subscription will become a member of the group as well. If the target subscription is not part of a group, a new group will be created and both the target and the new subscription will become part of the group with the target as the group's primary subscription. The optional billing parameters specify how some aspects of the billing for the new subscription should be handled. Rather than capturing payment immediately, the accrue parameter can be included so that the new subscription charges accrue until the next assessment date. Regarding the date, the align_date parameter can be included so that the billing date of the new subscription matches up with the target subscription. When choosing to align the dates, the prorate parameter can also be specified so that the new subscription charges are prorated based on the billing period of the target subscription also.

Providing Agreement Acceptance Params

It is possible to provide a proof of customer's acceptance of terms and policies. We will be storing this proof in case it might be required (i.e. chargeback). Currently, we already keep it for subscriptions created via Public Signup Pages. In order to create a subscription with the proof of agreement acceptance, you must provide additional parameters agreement acceptance with ip_address and at least one url to the policy that was accepted: terms_url or privacy_policy_url. Additional urls that can be provided: return_refund_policy_url, delivery_policy_url and secure_checkout_policy_url.

  "subscription": {
    "product_handle": "gold-product",
    "customer_attributes": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]"
    },
    "agreement_acceptance": {
      "ip_address": "1.2.3.4",
      "terms_url": "https://terms.url",
      "privacy_policy_url": "https://privacy_policy.url",
      "return_refund_policy_url": "https://return_refund_policy.url",
      "delivery_policy_url": "https://delivery_policy.url",
      "secure_checkout_policy_url": "https://secure_checkout_policy.url"
    }
  }
}

For Maxio Payments subscriptions, the agreement acceptance params are required, with at least terms_url provided.

Providing ACH Agreement params

It is also possible to provide a proof that a customer authorized ACH agreement terms. The proof will be stored and the email will be sent to the customer with a copy of the terms (if enabled). In order to create a subscription with the proof of authorized ACH agreement terms, you must provide the additional parameter ach_agreement with the following nested parameters: agreement_terms, authorizer_first_name, authorizer_last_name and ip_address. Each of them is required.

  "subscription": {
    "product_handle": "gold-product",
    "customer_attributes": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]"
    },
    "bank_account_attributes": {
      "bank_name": "Test Bank",
      "bank_routing_number": "021000089",
      "bank_account_number": "111111111111",
      "bank_account_type": "checking",
      "bank_account_holder_type": "business",
      "payment_type": "bank_account"
    },
    "ach_agreement": {
      "agreement_terms": "ACH agreement terms",
      "authorizer_first_name": "Jane",
      "authorizer_last_name": "Doe",
      "ip_address": "1.2.3.4"
    }
  }

Parameters:

Returns:



761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 761

def create_subscription(body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions.json',
                                 Server::DEFAULT)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionResponse.method(:from_hash))
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             ErrorListResponseException))
    .execute
end

#delete_coupon_from_subscription(subscription_id, coupon_code: nil) ⇒ String

Use this endpoint to remove a coupon from an existing subscription. For more information on the expected behaviour of removing a coupon from a subscription, please see our documentation [here.](https://chargify.zendesk.com/hc/en-us/articles/4407896488987#remov ing-a-coupon) subscription

Parameters:

  • subscription_id (String) —

    Required parameter: The Chargify id of the

  • coupon_code (String) (defaults to: nil) —

    Optional parameter: The coupon code

Returns:

  • (String) —

    response from the API call.



1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 1058

def delete_coupon_from_subscription(subscription_id,
                                    coupon_code: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/subscriptions/{subscription_id}/remove_coupon.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(coupon_code, key: 'coupon_code'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:deserialize_primitive_types))
                .deserialize_into(proc do |response| response.to_s end)
                .is_primitive_response(true)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             SubscriptionRemoveCouponErrorsException))
    .execute
end

#list_subscriptions(options = {}) ⇒ Array[SubscriptionResponse]

This method will return an array of subscriptions from a Site. Pay close attention to query string filters and pagination in order to control responses from the server.

Search for a subscription

Use the query strings below to search for a subscription using the criteria available. The return value will be an array.

Self-Service Page token

Self-Service Page token for the subscriptions is not returned by default. If this information is desired, the include=self_service_page_token parameter must be provided with the request. pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query page=1. many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query per_page=200. the subscription subscription. (Note that the product handle cannot be used.) product price point. If supplied, product is required currently applied to the subscription. (This can be found in the URL when editing a coupon. Note that the coupon code cannot be used.) filter you'd like to apply to your search. Allowed Values: , current_period_ends_at, current_period_starts_at, created_at, activated_at, canceled_at, expires_at, trial_started_at, trial_ended_at, updated_at YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. Use in query start_date=2022-07-01. YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. Use in query end_date=2022-08-01. time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date. Use in query start_datetime=2022-07-01 09:00:05. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date. Use in query end_datetime=2022-08-01 10:00:05. the metadata field specified in the parameter. Use in query metadata[my-field]=value&metadata[other-field]=another_value. order in which results are returned. Use in query direction=asc. to sort

Parameters:

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • state (SubscriptionState) —

    Optional parameter: The current state of

  • product (Integer) —

    Optional parameter: The product id of the

  • product_price_point_id (Integer) —

    Optional parameter: The ID of the

  • coupon (Integer) —

    Optional parameter: The numeric id of the coupon

  • date_field (SubscriptionDateField) —

    Optional parameter: The type of

  • start_date (Date) —

    Optional parameter: The start date (format

  • end_date (Date) —

    Optional parameter: The end date (format

  • start_datetime (DateTime) —

    Optional parameter: The start date and

  • end_datetime (DateTime) —

    Optional parameter: The end date and time

  • metadata (Hash[String, String]) —

    Optional parameter: The value of

  • direction (SortingDirection | nil) —

    Optional parameter: Controls the

  • sort (SubscriptionSort) —

    Optional parameter: The attribute by which

Returns:



1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 1143

def list_subscriptions(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions.json',
                                 Server::DEFAULT)
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .query_param(new_parameter(options['state'], key: 'state'))
               .query_param(new_parameter(options['product'], key: 'product'))
               .query_param(new_parameter(options['product_price_point_id'], key: 'product_price_point_id'))
               .query_param(new_parameter(options['coupon'], key: 'coupon'))
               .query_param(new_parameter(options['date_field'], key: 'date_field'))
               .query_param(new_parameter(options['start_date'], key: 'start_date'))
               .query_param(new_parameter(options['end_date'], key: 'end_date'))
               .query_param(new_parameter(options['start_datetime'], key: 'start_datetime'))
               .query_param(new_parameter(options['end_datetime'], key: 'end_datetime'))
               .query_param(new_parameter(options['metadata'], key: 'metadata'))
               .query_param(new_parameter(options['direction'], key: 'direction')
                             .validator(proc do |value|
                               UnionTypeLookUp.get(:ListSubscriptionsInputDirection)
                                              .validate(value)
                             end))
               .query_param(new_parameter(options['sort'], key: 'sort'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::UN_INDEXED))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionResponse.method(:from_hash))
                .is_response_array(true))
    .execute
end

#override_subscription(subscription_id, body: nil) ⇒ void

This method returns an undefined value.

This API endpoint allows you to set certain subscription fields that are usually managed for you automatically. Some of the fields can be set via the normal Subscriptions Update API, but others can only be set using this endpoint. This endpoint is provided for cases where you need to “align” Chargify data with data that happened in your system, perhaps before you started using Chargify. For example, you may choose to import your historical subscription data, and would like the activation and cancellation dates in Chargify to match your existing historical dates. Chargify does not backfill historical events (i.e. from the Events API), but some static data can be changed via this API. Why are some fields only settable from this endpoint, and not the normal subscription create and update endpoints? Because we want users of this endpoint to be aware that these fields are usually managed by Chargify, and using this API means you are stepping out on your own. Changing these fields will not affect any other attributes. For example, adding an expiration date will not affect the next assessment date on the subscription. If you regularly need to override the current_period_starts_at for new subscriptions, this can also be accomplished by setting both previous_billing_at and next_billing_at at subscription creation. See the documentation on Importing Subscriptions for more information.

Limitations

When passing current_period_starts_at some validations are made:

  1. The subscription needs to be unbilled (no statements or invoices).
  2. The value passed must be a valid date/time. We recommend using the iso 8601 format.
  3. The value passed must be before the current date/time. If unpermitted parameters are sent, a 400 HTTP response is sent along with a string giving the reason for the problem. subscription fields are available to be set.

Parameters:

  • subscription_id (String) —

    Required parameter: The Chargify id of the

  • body (OverrideSubscriptionRequest) (defaults to: nil) —

    Optional parameter: Only these



818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 818

def override_subscription(subscription_id,
                          body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/subscriptions/{subscription_id}/override.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .is_response_void(true)
                .local_error('400',
                             'Bad Request',
                             APIException)
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             APIException))
    .execute
end

#preview_subscription(body: nil) ⇒ SubscriptionPreviewResponse

The Chargify API allows you to preview a subscription by POSTing the same JSON or XML as for a subscription creation. The "Next Billing" amount and "Next Billing" date are represented in each Subscriber's Summary. For more information, please see our documentation [here](https://chargify.zendesk.com/hc/en-us/articles/4407884887835#next-b illing).

Side effects

A subscription will not be created by sending a POST to this endpoint. It is meant to serve as a prediction.

Taxable Subscriptions

This endpoint will preview taxes applicable to a purchase. In order for taxes to be previewed, the following conditions must be met:

  • Taxes must be configured on the subscription
  • The preview must be for the purchase of a taxable product or component, or combination of the two.
  • The subscription payload must contain a full billing or shipping address in order to calculate tax For more information about creating taxable previews, please see our documentation guide on how to create [taxable subscriptions.](https://chargify.zendesk.com/hc/en-us/articles/44079042177 55#creating-taxable-subscriptions) You do not need to include a card number to generate tax information when you are previewing a subscription. However, please note that when you actually want to create the subscription, you must include the credit card information if you want the billing address to be stored in Chargify. The billing address and the credit card information are stored together within the payment profile object. Also, you may not send a billing address to Chargify without payment profile information, as the address is stored on the card. You can pass shipping and billing addresses and still decide not to calculate taxes. To do that, pass skip_billing_manifest_taxes: true attribute.

Non-taxable Subscriptions

If you'd like to calculate subscriptions that do not include tax, please feel free to leave off the billing information.

Parameters:

Returns:



1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 1032

def preview_subscription(body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/preview.json',
                                 Server::DEFAULT)
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionPreviewResponse.method(:from_hash)))
    .execute
end

#purge_subscription(subscription_id, ack, cascade: nil) ⇒ void

This method returns an undefined value.

For sites in test mode, you may purge individual subscriptions. Provide the subscription ID in the url. To confirm, supply the customer ID in the query string ack parameter. You may also delete the customer record and/or payment profiles by passing cascade parameters. For example, to delete just the customer record, the query params would be: ?ack={customer_id}&cascade[]=customer If you need to remove subscriptions from a live site, please contact support to discuss your use case.

Delete customer and payment profile

The query params will be: ?ack={customer_id}&cascade[]=customer&cascade[]=payment_profile subscription are "customer" or "payment_profile". Use in query: cascade[]=customer&cascade[]=payment_profile.

Parameters:

  • subscription_id (String) —

    Required parameter: The Chargify id of the

  • ack (Integer) —

    Required parameter: id of the customer.

  • cascade (Array[SubscriptionPurgeType]) (defaults to: nil) —

    Optional parameter: Options



940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 940

def purge_subscription(subscription_id,
                       ack,
                       cascade: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/subscriptions/{subscription_id}/purge.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(ack, key: 'ack')
                             .is_required(true))
               .query_param(new_parameter(cascade, key: 'cascade[]'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::CSV))
    .response(new_response_handler
                .is_nullify404(true)
                .is_response_void(true)
                .local_error('400',
                             'Bad Request',
                             APIException))
    .execute
end

#read_subscription(subscription_id, include: nil) ⇒ SubscriptionResponse

Use this endpoint to find subscription details.

Self-Service Page token

Self-Service Page token for the subscription is not returned by default. If this information is desired, the include=self_service_page_token parameter must be provided with the request. subscription including additional data in the response. Use in query: include[]=coupons&include[]=self_service_page_token.

Parameters:

  • subscription_id (String) —

    Required parameter: The Chargify id of the

  • include (Array[SubscriptionInclude]) (defaults to: nil) —

    Optional parameter: Allows

Returns:



975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 975

def read_subscription(subscription_id,
                      include: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/{subscription_id}.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(include, key: 'include[]'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::UN_INDEXED))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionResponse.method(:from_hash)))
    .execute
end

#read_subscription_by_reference(reference: nil) ⇒ SubscriptionResponse

Use this endpoint to find a subscription by its reference.

Parameters:

  • reference (String) (defaults to: nil) —

    Optional parameter: Subscription reference

Returns:



1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 1270

def read_subscription_by_reference(reference: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/subscriptions/lookup.json',
                                 Server::DEFAULT)
               .query_param(new_parameter(reference, key: 'reference'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionResponse.method(:from_hash)))
    .execute
end

#update_subscription(subscription_id, body: nil) ⇒ SubscriptionResponse

The subscription endpoint allows you to instantly update one or many attributes about a subscription in a single call.

Update Subscription Payment Method

Change the card that your Subscriber uses for their subscription. You can also use this method to simply change the expiration date of the card if your gateway allows. Note that partial card updates for Authorize.Net are not allowed via this endpoint. The existing Payment Profile must be directly updated instead. You also use this method to change the subscription to a different product by setting a new value for product_handle. A product change can be done in two different ways, product change or delayed product change.

Product Change

This endpoint may be used to change a subscription's product. The new payment amount is calculated and charged at the normal start of the next period. If you desire complex product changes or prorated upgrades and downgrades instead, please see the documentation on Migrating Subscription Products. To perform a product change, simply set either the product_handle or product_id attribute to that of a different product from the same site as the subscription. You can also change the price point by passing in either product_price_point_id or product_price_point_handle - otherwise the new product's default price point will be used.

Delayed Product Change

This method also changes the product and/or price point, and the new payment amount is calculated and charged at the normal start of the next period. This method schedules the product change to happen automatically at the subscription’s next renewal date. To perform a Delayed Product Change, set the product_handle attribute as you would in a regular product change, but also set the product_change_delayed attribute to true. No proration applies in this case. You can also perform a delayed change to the price point by passing in either product_price_point_id or product_price_point_handle Note: To cancel a delayed product change, set next_product_id to an empty string.

Billing Date Changes

Regular Billing Date Changes

Send the next_billing_at to set the next billing date for the subscription. After that date passes and the subscription is processed, the following billing date will be set according to the subscription's product period. Note that if you pass an invalid date, we will automatically interpret and set the correct date. For example, when February 30 is entered, the next billing will be set to March 2nd in a non-leap year. The server response will not return data under the key/value pair of next_billing. Please view the key/value pair of current_period_ends_at to verify that the next_billing date has been changed successfully.

Snap Day Changes

For a subscription using Calendar Billing, setting the next billing date is a bit different. Send the snap_day attribute to change the calendar billing date for a subscription using a product eligible for calendar billing. Note: If you change the product associated with a subscription that contains a snap_date and immediately READ/GET the subscription data, it will still contain evidence of the existing snap_date. This is due to the fact that a product change is instantanous and only affects the product associated with a subscription. After the next_billing date arrives, the snap_day associated with the subscription will return to null. Another way of looking at this is that you willl have to wait for the next billing cycle to arrive before the snap_date will reset to null. subscription

Parameters:

  • subscription_id (String) —

    Required parameter: The Chargify id of the

  • body (UpdateSubscriptionRequest) (defaults to: nil) —

    Optional parameter: Example:

Returns:



1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
 
# File 'lib/advanced_billing/controllers/subscriptions_controller.rb', line 1243

def update_subscription(subscription_id,
                        body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/subscriptions/{subscription_id}.json',
                                 Server::DEFAULT)
               .template_param(new_parameter(subscription_id, key: 'subscription_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_nullify404(true)
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(SubscriptionResponse.method(:from_hash))
                .local_error('422',
                             'Unprocessable Entity (WebDAV)',
                             ErrorListResponseException))
    .execute
end