Knowledge Base: API: Subscriptions
Subscriptions in Chargify give access to a particular Product for a particular Customer. They are usually recurring in nature, and all of the complexities of renewal, dunning, and expiration management are handled by Chargify.
Creating a subscription via the Chargify API is something you may do in response to a customer attempting to signup for services on your website. You pass to us the product ID or Handle, customer ID or Reference or Attributes, and the credit card information. We in turn set up the subscription, return the subscription information, and take over the charging of the credit card.
Subscription Input Attributes
When creating a subscription, you must specify a product, a customer, and payment (credit card) details.
The product may be specified by product_id or by
product_handle (API Handle).
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). A new customer may be created by
providing customer_attributes.
product_handleThe API Handle of the product for which you are creating a subscription. Required, unless a product_id is given instead.product_idThe Product ID of the product for which you are creating a subscription. The product ID is not currently published, so we recommend using the API Handle instead.customer_idThe ID of an existing customer within Chargify. Required, unless a customer_reference or a set of customer_attributes is given.customer_referenceThe reference value (provided by your app) of an existing customer within Chargify. Required, unless a customer_id or a set of customer_attributes is given.customer_attributesfirst_nameThe first name of the customer. Required when creating a customer via attributes.last_nameThe last name of the customer. Required when creating a customer via attributes.emailThe email address of the customer. Required when creating a customer via attributes.organizationThe organization/company of the customer. Optional.referenceA customer "reference", or unique identifier from your app, stored in Chargify. Can be used so that you may reference your customers within Chargify using the same unique value you use in your application. Optional.
credit_card_attributesfirst_name(Optional) First name on card. If omitted, thefirst_namefrom customer attributes will be used.last_name(Optional) Last name on card. If omitted, thelast_namefrom customer attributes will be used.full_numberThe full credit card number (string representation, i.e. "5424000000000015")expiration_monthThe 1- or 2-digit credit card expiration month, as an integer or string, i.e. "5"expiration_yearThe 4-digit credit card expiration year, as an integer or string, i.e. "2012"cvv(Optional, may be required by your gateway settings) The 3- or 4-digit Card Verification Value. This value is merely passed through to the payment gateway.billing_address(Optional, may be required by your gateway settings) The credit card billing street address (i.e. "123 Main St."). This value is merely passed through to the payment gateway.billing_city(Optional, may be required by your gateway settings) The credit card billing address city (i.e. "Boston"). This value is merely passed through to the payment gateway.billing_state(Optional, may be required by your gateway settings) The credit card billing address state (i.e. "MA"). This value is merely passed through to the payment gateway.billing_zip(Optional, may be required by your gateway settings) The credit card 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 gateway settings) The credit card billing address country (i.e. "USA"). This value is merely passed through to the payment gateway.
cancellation_message(Optional) Can be used when canceling a subscription (via the HTTP DELETE method) to make a note about the reason for cancellation.
Subscription Output Attributes
The following attributes are returned on a subscription read/list operation.
idThe subscription unique id within Chargify.stateThe current state of the subscription. It may be "trialing", "active", "soft_failure", "past_due", "suspended", "closed", or "expired"balance_in_centsGives the current outstanding subscription balance, in the number of cents.current_period_started_atTimestamp relating to the start of the current (recurring) periodcurrent_period_ends_atTimestamp relating to the end of the current (recurring) period (i.e. when the next regularly scheduled attempted charge will occur)trial_started_atTimestamp for when the trial period (if any) begantrial_ended_atTimestamp for when the trial period (if any) endedactivated_at(Read Only) Timestamp for when the subscription began (i.e. when it came out of trial, or when it began in the case of no trial)expires_atTimestamp giving the expiration date of this subscription (if any)created_atThe creation date for this subscriptionupdated_atThe date of last update for this subscriptioncustomerFor customer attributes, see Customers APIproductFor product attributes, see Products APIcredit_cardNested credit card attributestypeThe type of card used (bogus, visa, master)expiration_monthAn integer representing the expiration month of the card(1 - 12)expiration_yearAn integer representing the 4-digit expiration year of the card(i.e. '2012')first_nameThe first name of the card holderlast_nameThe last name of the card holdermasked_card_numberA string representation of the credit card number with all but the last 4 digits masked with X's (i.e. 'XXXX-XXXX-XXXX-1234')
cancellation_messageSeller-provided reason for, or note about, the cancellation.
Subscription States
The state of a subscription is reported in the
state attribute of a subscription. The valid states
are:
- trialing
- assessing
- active
- soft_failure
- past_due
- suspended
- canceled
- expired
These states may be further broken down in to 3 categories: Live, Problem, and End of Life.
You should plan on delivering services for any state except an End of Life state.
Live States
trialing
A subscription in trialing state has a valid trial
subscription. This type of subscription may transition to
active once payment is received when the trial has
ended. Otherwise, it may go to a Problem or End of
Life state.
assessing
An internal (transient) state that indicates a subscription is in the middle of periodic assessment. Do not base any access decisions in your app on this state, as it may not always be exposed.
Noe: You may get post-backs indicating entry to this state, but we are attempting to eliminate them, as you do not need to know about this state.
active
A normal, active subscription. It is not in a trial, and is paid and up to date. This is where you want all your Customers to be :)
Problem States
soft_failure
Indicates that normal assessment/processing of the subscription has failed for a reason that cannot be fixed by the Customer. For example, a Soft Fail may result from a timeout at the gateway, or incorrect credentials on your part. The subscriptions should be retried automatically. An interface is being built for you to review problems resulting from these events to take manual action, when needed.
past_due
Indicates that the most recent payment has failed, and payment is past due for this subscription. If you have enabled our automated dunning, this subscription will be in the dunning process (additional status and callbacks from the dunning process will be available in the future). If you are handling dunning and payment updates yourself, you will want to use this state to initiate a payment update from your customers.
End of Life States
canceled
Indicates a canceled subscription. This may happen at your
request (via the API or the web interface) or due to an expiration
of the dunning process without payment. Note that another state,
suspended, may be used in the future for subscriptions
that may be restarted. Canceled subscriptions may not currently be
restarted.
expired
Indicates a subscription that has expired due to running its
normal life cycle. Some products may be configured to have an
expiration period. An expired subscription then, is
one that stayed active until it fulfilled its full
period.
suspended
Reserved and currently unused. May be used in the future for subscriptions that may be restarted (i.e. after being suspended due to non-payment, then payment resumes)
Methods
format may be either 'xml' or 'json'.
List
URL:
https://<subdomain>.chargify.com/customers/<customer_id>/subscriptions.<format>
Method: GET
Required Parameters, customer_id
Response: An array of Subscriptions
Usage Examples:
XML example
JSON
example
Read
URL:
https://<subdomain>.chargify.com/subscriptions/<subscription_id>.<format>
Method: GET
Required Parameters: subscription_id
Response: An single Subscription
XML example
JSON
example
Create
URL:
https://<subdomain>.chargify.com/subscriptions.<format>
Method: POST
Required Parameters: XML or JSON data, as specified by the required
attributes
Response: The created subscription
Usage Examples:
XML example
JSON
example
Update
The update action currently allows you to edit the attributes of the customer, payment profile (credit card), or subscribed product (although no proration or reset options are offered at this time).
This 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 also use this method to change the subscription to a
different product (upgrade or downgrade) by setting a new value for
product_handle. Note that no proration or period reset
is available at this time. This method merely changes the product,
and the new payment amount is calculated and charged at the normal
start of the next period.
URL:
https://<subdomain>.chargify.com/subscriptions/<subscription_id>.<format>
Method: PUT
Required Parameters: None
Optional Parameters: XML or JSON data with updated values for
customer_attributes or
credit_card_attributes
Response: The updated subscription
Usage Examples:
XML example
JSON
example
Delete/Cancel
The delete action causes the cancellation of a subscription,
i.e. it sets the subscription state to canceled.
URL:
https://<subdomain>.chargify.com/subscriptions/<subscription_id>.<format>
Method: DELETE
Required Parameters: None
Optional Parameters: XML or JSON data with a
cancellation_message note that will be stored with the
subscription.
Response: 200 OK on success
Usage Examples:
XML example
JSON
example
XML List Usage Example
Feature: Chargify Subscriptions List XML API
In order integrate my app with Chargify
As a developer
I want to interact with my subscriptions via the Chargify API
Background:
Given I am a valid API user
And I accept xml responses
Scenario: Retrieve a customer's subscriptions
Given I have a customer with these attributes
| id | first_name | last_name | email |
| [@customer.id] | Joe | Blow | joe@example.com |
And the customer has 2 subscriptions
When I send a GET request to https://[@subdomain].chargify.com/customers/[@customer.id]/subscriptions.xml
Then the response status should be "200 OK"
And the response should be a "subscriptions" array with 2 "subscription" elements
JSON List Usage Example
Feature: Chargify Subscriptions List JSON API
In order integrate my app with Chargify
As a developer
I want to interact with my subscriptions via the Chargify API
Background:
Given I am a valid API user
And I accept json responses
Scenario: Retrieve a customer's subscriptions
Given I have a customer with these attributes
| id | first_name | last_name | email |
| [@customer.id] | Joe | Blow | joe@example.com |
And the customer has 2 subscriptions
When I send a GET request to https://[@subdomain].chargify.com/customers/[@customer.id]/subscriptions.json
Then the response status should be "200 OK"
And the response should be a json array with 2 "subscription" objects
XML Read Usage Example
Feature: Chargify Subscriptions Read/Show/Lookup XML API
In order integrate my app with Chargify
As a developer
I want to read/show/lookup a subscription via the Chargify XML API
Background:
Given I am a valid API user
And I accept xml responses
Scenario: Retrieve a subscription via ID
Given I have an active subscription
When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].xml
Then the response status should be "200 OK"
And print the response
And the response should be the xml:
"""
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
<id type="integer">[@subscription.id]</id>
<state>active</state>
<balance_in_cents type="integer">0</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>
<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>`auto generated`</updated_at>
</customer>
<product>
<accounting_code>`your value`</accounting_code>
<handle>`your value`</handle>
<interval>`your value`</interval>
<interval_unit>`your value`</interval_unit>
<name>`your value`</name>
<price_in_cents>`your value`</price_in_cents>
<product_family>
<accounting_code>`your value`</accounting_code>
<handle>`your value`</handle>
<name>`your value`</name>
</product_family>
</product>
<credit_card>
<card_type>`auto generated`</card_type>
<expiration_month>`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>`auto generated`</masked_card_number>
</credit_card>
</subscription>
"""
Scenario: Attempt to retrieve a subscription that doesn't exist
Given I have 0 subscriptions
When I send a GET request to https://[@subdomain].chargify.com/subscriptions/9999.xml
Then the response status should be "404 Not Found"
JSON Read Usage Example
Feature: Chargify Subscriptions Read/Show/Lookup JSON API
In order integrate my app with Chargify
As a developer
I want to read/show/lookup a subscription via the Chargify JSON API
Background:
Given I am a valid API user
And I accept json responses
Scenario: Retrieve a subscription via ID
Given I have an active subscription
When I send a GET request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].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":0,
"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":`auto generated`,
"name":`your value`,
"handle":`your value`,
"price_in_cents":`your value`,
"accounting_code":`your value`,
"interval":`your value`,
"interval_unit":`your value`,
"product_family":{
"id":`auto generated`,
"name":`your value`,
"handle":`your value`,
"accounting_code":`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`
}
}}
"""
Scenario: Attempt to retrieve a subscription that doesn't exist
Given I have 0 subscriptions
When I send a GET request to https://[@subdomain].chargify.com/subscriptions/9999.json
Then the response status should be "404 Not Found"
XML Create Usage Example
Feature: Chargify Subscriptions Create XML API
In order integrate my app with Chargify
As a developer
I want to create a subscription via the Chargify XML API
Background:
Given I am a valid API user
And I accept xml responses
Scenario: Create a subscription successfully with customer data, credit card data, and a product handle
Given I have 1 product
And I have this xml subscription data
"""
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
<product_handle>[@product.handle]</product_handle>
<customer_attributes>
<first_name>Joe</first_name>
<last_name>Blow</last_name>
<email>joe@example.com</email>
</customer_attributes>
<credit_card_attributes>
<full_number>1</full_number>
<expiration_month>10</expiration_month>
<expiration_year>2020</expiration_year>
</credit_card_attributes>
</subscription>
"""
When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions.xml
Then the response status should be "201 Created"
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>
<customer>
<id type="integer">`auto generated`</id>
<first_name>Joe</first_name>
<last_name>Blow</last_name>
<email>joe@example.com</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>
<accounting_code>`your value`</accounting_code>
<handle>[@product.handle]</handle>
<interval>`your value`</interval>
<interval_unit>`your value`</interval_unit>
<name>`your value`</name>
<price_in_cents>`your value`</price_in_cents>
<product_family>
<accounting_code>`your value`</accounting_code>
<handle>`your value`</handle>
<name>`your value`</name>
</product_family>
</product>
<credit_card>
<card_type>bogus</card_type>
<expiration_month type="integer">10</expiration_month>
<expiration_year type="integer">2020</expiration_year>
<first_name>Joe</first_name>
<last_name>Blow</last_name>
<masked_card_number>XXXX-XXXX-XXXX-1</masked_card_number>
</credit_card>
</subscription>
"""
Scenario: Create a subscription using an existing customer ID
Given I have 1 product
And I have 1 customer
And I have this xml subscription data
"""
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
<product_handle>[@product.handle]</product_handle>
<customer_id>[@customer.id]</customer_id>
<credit_card_attributes>
<full_number>1</full_number>
<expiration_month>10</expiration_month>
<expiration_year>2020</expiration_year>
</credit_card_attributes>
</subscription>
"""
When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions.xml
Then the response status should be "201 Created"
Scenario: Create a subscription using an existing customer reference
Given I have 1 product
And I have a customer with these attributes
| reference | first_name | last_name | email |
| 7890 | Joe | Blow | joe@example.com |
And I have this xml subscription data
"""
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
<product_handle>[@product.handle]</product_handle>
<customer_reference>[@customer.reference]</customer_reference>
<credit_card_attributes>
<full_number>1</full_number>
<expiration_month>10</expiration_month>
<expiration_year>2020</expiration_year>
</credit_card_attributes>
</subscription>
"""
When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions.xml
Then the response status should be "201 Created"
Scenario: Creating a subscription fails due to missing or invalid attributes
Given I have 1 product
And I have this xml subscription data
"""
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
<product_handle>[@product.handle]</product_handle>
<customer_attributes>
<first_name>Joe</first_name>
</customer_attributes>
<credit_card_attributes>
<full_number>1</full_number>
</credit_card_attributes>
</subscription>
"""
When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions.xml
Then the response status should be "422 Unprocessable Entity"
And print the response
And the response should be the xml:
"""
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>Credit card expiration year: cannot be blank.</error>
<error>Last name: cannot be blank.</error>
<error>Credit card expiration month: cannot be blank.</error>
<error>Email address: cannot be blank.</error>
</errors>
"""
Scenario: Creating a subscription fails due to a missing product
Given I have 1 product
And I have this xml subscription data
"""
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
<product_handle>this-does-not-exist</product_handle>
<customer_attributes>
<first_name>Joe</first_name>
<last_name>Blow</last_name>
<email>joe@example.com</email>
</customer_attributes>
<credit_card_attributes>
<full_number>1</full_number>
<expiration_month>10</expiration_month>
<expiration_year>2020</expiration_year>
</credit_card_attributes>
</subscription>
"""
When I send a POST request with the xml data to https://[@subdomain].chargify.com/subscriptions.xml
Then the response status should be "422 Unprocessable Entity"
And print the response
And the response should be the xml:
"""
<?xml version="1.0" encoding="UTF-8"?>
<errors>
<error>Product with API Handle 'this-does-not-exist' does not exist for this merchant.</error>
</errors>
"""
JSON Create Usage Example
Feature: Chargify Subscriptions Create JSON API
In order integrate my app with Chargify
As a developer
I want to create a subscription via the Chargify JSON API
Background:
Given I am a valid API user
And I send and accept json
Scenario: Create a subscription successfully with customer data, credit card data, and a product handle
Given I have 1 product
And I have this json subscription data
"""
{"subscription":{
"product_handle":"[@product.handle]",
"customer_attributes":{
"first_name":"Joe",
"last_name":"Blow",
"email":"joe@example.com"
},
"credit_card_attributes":{
"full_number":"1",
"expiration_month":"10",
"expiration_year":"2020"
}
}}
"""
When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions.json
Then the response status should be "201 Created"
And the response should be the json:
"""
{"subscription":{
"id":`auto generated`,
"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":"Joe",
"last_name":"Blow",
"email":"joe@example.com",
"organization":`your value`,
"reference":`your value`,
"updated_at":`auto generated`,
"created_at":`auto generated`
},
"product":{
"id":`auto generated`,
"name":`your value`,
"handle":"[@product.handle]",
"price_in_cents":`your value`,
"accounting_code":`your value`,
"interval":`your value`,
"interval_unit":`your value`,
"product_family":{
"id":`auto generated`,
"name":`your value`,
"handle":`your value`,
"accounting_code":`your value`
}
},
"credit_card":{
"first_name":"Joe",
"last_name":"Blow",
"masked_card_number":"XXXX-XXXX-XXXX-1",
"card_type":`auto generated`,
"expiration_month":10,
"expiration_year":2020
}
}}
"""
Scenario: Create a subscription using an existing customer ID
Given I have 1 product
And I have 1 customer
And I have this json subscription data
"""
{"subscription":{
"product_handle":"[@product.handle]",
"customer_id":"[@customer.id]",
"credit_card_attributes":{
"full_number":"1",
"expiration_month":"10",
"expiration_year":"2020"
}
}}
"""
When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions.json
Then the response status should be "201 Created"
Scenario: Create a subscription using an existing customer reference
Given I have 1 product
And I have a customer with these attributes
| reference | first_name | last_name | email |
| 7890 | Joe | Blow | joe@example.com |
And I have this json subscription data
"""
{"subscription":{
"product_handle":"[@product.handle]",
"customer_reference":"[@customer.reference]",
"credit_card_attributes":{
"full_number":"1",
"expiration_month":"10",
"expiration_year":"2020"
}
}}
"""
When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions.json
Then print the response
Then the response status should be "201 Created"
Scenario: Creating a subscription fails due to missing or invalid attributes
Given I have 1 product
And I have this json subscription data
"""
{"subscription":{
"product_handle":[@product.handle],
"customer_attributes":{
"first_name":"Joe"
},
"credit_card_attributes":{
"full_number":"1"
}
}}
"""
When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions.json
Then the response status should be "422 Unprocessable Entity"
And the response should be the json:
"""
{"errors":
[
"Credit card expiration year: cannot be blank.",
"Last name: cannot be blank.",
"Credit card expiration month: cannot be blank.",
"Email address: cannot be blank."
]
}
"""
Scenario: Creating a subscription fails due to a missing product
Given I have 1 product
And I have this json subscription data
"""
{"subscription":{
"product_handle":"this-does-not-exist",
"customer_attributes":{
"first_name":"Joe",
"last_name":"Blow",
"email":"joe@example.com"
},
"credit_card_attributes":{
"full_number":"1",
"expiration_month":"10",
"expiration_year":"2020"
}
}}
"""
When I send a POST request with the json data to https://[@subdomain].chargify.com/subscriptions.json
Then the response status should be "422 Unprocessable Entity"
And the response should be the json:
"""
{"errors":
[
"Product with API Handle 'this-does-not-exist' does not exist for this merchant."
]
}
"""
XML Update Usage Example
Feature: Chargify Subscriptions Edit/Update XML API
In order integrate my app with Chargify
As a developer
I want to edit/update a subscription via the Chargify XML API
Background:
Given I am a valid API user
And I send and accept xml
Scenario: Update the credit card information on a subscription using credit_card_attributes
Given I have an active subscription
And I have this xml subscription data
"""
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
<credit_card_attributes>
<full_number>2</full_number>
<expiration_month>10</expiration_month>
<expiration_year>2040</expiration_year>
</credit_card_attributes>
</subscription>
"""
When I send a PUT request with the xml data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].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">[@subscription.id]</id>
<state>active</state>
<balance_in_cents type="integer">0</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>`auto generated`</updated_at>
</customer>
<product>
<id>`auto generated`</id>
<accounting_code>`your value`</accounting_code>
<handle>`your value`</handle>
<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>
</product_family>
</product>
<credit_card>
<card_type>`auto generated`</card_type>
<expiration_month type="integer">10</expiration_month>
<expiration_year type="integer">2040</expiration_year>
<first_name>`your value`</first_name>
<last_name>`your value`</last_name>
<masked_card_number>XXXX-XXXX-XXXX-2</masked_card_number>
</credit_card>
</subscription>
"""
Scenario: Update the product associated with the subscription
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"?>
<subscription>
<product_handle>[@products.last.handle]</product_handle>
</subscription>
"""
When I send a PUT request with the xml data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].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">[@subscription.id]</id>
<state>active</state>
<balance_in_cents type="integer">0</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>`auto generated`</updated_at>
</customer>
<product>
<id type="integer">[@products.last.id]</id>
<accounting_code>[@products.last.accounting_code]</accounting_code>
<handle>[@products.last.handle]</handle>
<interval type="integer">[@products.last.interval]</interval>
<interval_unit>[@products.last.interval_unit]</interval_unit>
<name>[@products.last.name]</name>
<price_in_cents type="integer">[@products.last.price_in_cents]</price_in_cents>
<product_family>
<id type="integer">[@products.last.product_family.id]</id>
<accounting_code>[@products.last.product_family.accounting_code]</accounting_code>
<handle>[@products.last.product_family.handle]</handle>
<name>[@products.last.product_family.name]</name>
</product_family>
</product>
<credit_card>
<card_type>`auto generated`</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>`your value`</masked_card_number>
</credit_card>
</subscription>
"""
JSON Update Usage Example
Feature: Chargify Subscriptions Edit/Update JSON API
In order integrate my app with Chargify
As a developer
I want to edit/update a subscription via the Chargify JSON API
Background:
Given I am a valid API user
And I send and accept json
Scenario: Update the credit card information on a subscription using credit_card_attributes
Given I have an active subscription
And I have this json subscription data
"""
{"subscription":{
"credit_card_attributes":{
"full_number":"2",
"expiration_month":"10",
"expiration_year":"2030"
}
}}
"""
When I send a PUT request with the json data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].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":`auto generated`,
"name":`your value`,
"handle":`your value`,
"price_in_cents":`your value`,
"accounting_code":`your value`,
"interval":`your value`,
"interval_unit":`your value`,
"product_family":{
"id":`auto generated`,
"name":`your value`,
"handle":`your value`,
"accounting_code":`your value`
}
},
"credit_card":{
"first_name":`your value`,
"last_name":`your value`,
"masked_card_number":"XXXX-XXXX-XXXX-2",
"card_type":`auto generated`,
"expiration_month":10,
"expiration_year":2030
}
}}
"""
Scenario: Update the product associated with the subscription
Given I have 2 products
And I have an active subscription to the first product
And I have this json subscription data
"""
{"subscription":{
"product_handle": [@products.last.handle]
}}
"""
When I send a PUT request with the json data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].json
Then the response status should be "200 OK"
And print the response
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]",
"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]"
}
},
"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`
}
}}
"""
XML Delete/Cancel Usage Example
Feature: Chargify Subscriptions Cancel XML API
In order integrate my app with Chargify
As a developer
I want to cancel a subscription via the Chargify XML API
Background:
Given I am a valid API user
And I accept xml responses
Scenario: Cancel a subscription without giving a reason/message
Given I have an active subscription
When I send a DELETE request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].xml
Then the response status should be "200 OK"
Scenario: Cancel a subscription while giving a reason/message
Given I have an active subscription
And I have this xml subscription data
"""
<?xml version="1.0" encoding="UTF-8"?>
<subscription>
<cancellation_message>
Canceling the subscription via the API
</cancellation_message>
</subscription>
"""
When I send a DELETE request with the xml data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].xml
Then the response status should be "200 OK"
JSON Delete/Cancel Usage Example
Feature: Chargify Subscriptions Cancel JSON API
In order integrate my app with Chargify
As a developer
I want to cancel a subscription via the Chargify JSON API
Background:
Given I am a valid API user
And I accept json responses
Scenario: Cancel a subscription without giving a reason/message
Given I have an active subscription
When I send a DELETE request to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].json
Then the response status should be "200 OK"
Scenario: Cancel a subscription while giving a reason/message
Given I have an active subscription
And I have this json subscription data
"""
{
'subscription': {
'cancellation_message': 'Canceling the subscription via the API'
}
}
"""
When I send a DELETE request with the json data to https://[@subdomain].chargify.com/subscriptions/[@subscription.id].json
Then the response status should be "200 OK"
-
General Questions
-
Features
-
Billing & Payment
- Can I pay by check or money order?
- Can I try it out before buying?
- Do I still have to pay the transaction fees that my merchant account requires?
- Does Chargify charge a percentage or per transaction fee like PayPal or Google Checkout?
- Does Chargify support collecting foreign currencies?
- View all (5 more)
-
API
-
What makes Chargify different?