This documentation site is deprecated. The latest up-to-date API reference is available at https://reference.chargify.com.
This site will remain available for historical reference until June 1, 2017

API: Billing Portal

If your customer has been invited to the Billing Portal, then they will receive a link to manage their subscription (the “Management URL”) automatically at the bottom of their statements, invoices, and receipts. This link changes periodically for security and is only valid for 65 days. Please be sure to read more about the links your customers receive for the Billing Portal

If you need to provide your customer their Management URL through other means, you can retrieve it via the API. Because the URL is cryptographically signed with a timestamp, it is not possible for merchants to generate the URL without requesting it from Chargify.

In order to prevent abuse & overuse, we ask that you request a new URL only when absolutely necessary. Management URLs are good for 65 days, so you should re-use a previously generated one as much as possible. If you use the URL frequently (such as to display on your website), please do not make an API request to Chargify every time.

Rules for Management Link API

  • When retrieving a management URL, multiple requests for the same customer in a short period will return the same URL
  • We will not generate a new URL for 15 days
  • You must cache and remember this URL if you are going to need it again within 15 days
  • Only request a new URL after the new_link_available_at date
  • You are limited to 15 requests for the same URL. If you make more than 15 requests before new_link_available_at, you will be blocked from further Management URL requests (with a response code 429)

Management Link Attributes

All of the attribute fields are returned from GET (read) operations, and all are read only.

  • url The customer’s management URL
  • fetch_count Number of times this link has been retrieved (at 15 you will be blocked)
  • created_at When this link was created
  • new_link_available_at When a new link will be available and fetch_count is reset (15 days from when it was created)
  • expires_at When this link expires (65 days from when it was created)

Methods

Read/Show

URL: https://<subdomain>.chargify.com/portal/customers/<customer_id>/management_link
Method: GET
Required Parameters: customer_id

JSON example
XML example

Usage Examples

JSON Read Call Example



curl -u <API_KEY>:x -H "Accept: application/json" https://<subdomain>chargify.com/portal/customers/<customer_id>/management_link.json

{
  "url": "https://www.billingportal.com/manage/123/1383672520/a5b33efa2fdedb11",
  "fetch_count": 1,
  "created_at": "2013-11-05T00:00:00Z",
  "new_link_available_at": "2013-11-20T00:00:00Z",
  "expires_at": "2014-01-09T00:00:00Z"
}

# After too many requests (status code: 429):

{"errors":{"error":"Too many requests for this customer's management link"}}

XML Read Call Example



curl -u <API_KEY>:x -H "Accept: application/xml" https://<subdomain>chargify.com/portal/customers/<customer_id>/management_link.xml


<?xml version="1.0" encoding="UTF-8"?>
<management_link>
  <url>https://www.billingportal.com/manage/123/1383672520/a5b33efa2fdedb11</url>
  <fetch_count type="integer">1</fetch_count>
  <created_at type="datetime">2013-11-05T00:00:00Z</created_at>
  <new_link_available_at type="datetime">2013-11-20T00:00:00Z</new_link_available_at>
  <expires_at type="datetime">2014-01-09T00:00:00Z</expires_at>
</management_link>

# After too many requests (status code: 429):

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Too many requests for this customer's management link</error>
</errors>


Enabling Portal For a Customer

You can enable Billing Portal access for a Customer, with the option of sending the Customer an Invitation email at the same time.

Enabling Portal

URL: https://<subdomain>.chargify.com/portal/customers/<customer_id>/enable
Method: POST
Required Parameters: id The Customer ID
Optional Parameters: auto_invite When set to 1, an Invitation email will be sent to the Customer. When set to 0, or not sent, an email will not be sent.

XML Enable Call Example

curl -H "Content-Type: application/xml" -X POST -u <API_KEY>:x https://<subdomain>.chargify.com/portal/customers/:id/enable.xml

<?xml version="1.0" encoding="UTF-8"?>
<customer>
  <first_name>John</first_name>
  <last_name>Doe</last_name>
  <email>jd@example.com</email>
  <organization></organization>
  <reference nil="true"/>
  <id type="integer">100032</id>
  <created_at type="datetime">2014-04-17T11:13:52-04:00</created_at>
  <updated_at type="datetime">2014-04-17T15:06:52-04:00</updated_at>
  <address>123 Main St</address>
  <address_2></address_2>
  <city>New York</city>
  <state>NY</state>
  <zip>10045</zip>
  <country>US</country>
  <phone></phone>
  <verified type="boolean">true</verified>
  <portal_customer_created_at type="datetime">2014-04-17T15:06:52-04:00</portal_customer_created_at>
  <portal_invite_last_sent_at type="datetime" nil="true"/>
  <portal_invite_last_accepted_at type="datetime" nil="true"/>
</customer>

When sending an Invitation email at the same time as enabling Billing Portal:

curl -H "Content-Type: application/xml" -X POST -u <API_KEY>:x https://<subdomain>.chargify.com/portal/customers/:id/enable.xml\?auto_invite\=1

<?xml version="1.0" encoding="UTF-8"?>
<customer>
  <first_name>John</first_name>
  <last_name>Doe</last_name>
  <email>jd@example.com</email>
  <organization></organization>
  <reference nil="true"/>
  <id type="integer">100032</id>
  <created_at type="datetime">2014-04-17T11:13:52-04:00</created_at>
  <updated_at type="datetime">2014-04-17T15:06:52-04:00</updated_at>
  <address>123 Main St</address>
  <address_2></address_2>
  <city>New York</city>
  <state>NY</state>
  <zip>10045</zip>
  <country>US</country>
  <phone></phone>
  <verified type="boolean">true</verified>
  <portal_customer_created_at type="datetime">2014-04-17T15:19:42-04:00</portal_customer_created_at>
  <portal_invite_last_sent_at type="datetime">2014-04-17T15:19:42-04:00</portal_invite_last_sent_at>
  <portal_invite_last_accepted_at type="datetime" nil="true"/>
</customer>

When Billing Portal is already enabled for this Customer:

<?xml version="1.0" encoding="UTF-8"?>
<errors type="array">
  <error>Portal is already enabled for this customer.</error>
</errors>

JSON Enable Call Example

curl -H "Content-Type: application/json" -X POST -u <API_KEY>:x https://<subdomain>.chargify.com/portal/customers/:id/enable.json

{
  "customer":
  {
    "first_name":"John",
    "last_name":"Doe",
    "email":"jd@example.com",
    "organization":"",
    "reference":null,
    "id":100032,
    "created_at":"2014-04-17T11:13:52-04:00",
    "updated_at":"2014-04-17T15:37:08-04:00",
    "address":"45 Main St",
    "address_2":"",
    "city":"New York",
    "state":"NY",
    "zip":"10045",
    "country":"US",
    "phone":"",
    "verified":false,
    "portal_customer_created_at":"2014-04-17T15:37:08-04:00",
    "portal_invite_last_sent_at":null,
    "portal_invite_last_accepted_at":null
  }
}

When sending an Invitation email at the same time as enabling Billing Portal:

curl -H "Content-Type: application/json" -X POST -u <API_KEY>:x https://<subdomain>.chargify.com/portal/customers/:id/enable.json\?auto_invite\=1

{
  "customer":
  {
    "first_name":"John",
    "last_name":"Doe",
    "email":"jd@example.com",
    "organization":"",
    "reference":null,
    "id":100032,
    "created_at":"2014-04-17T11:13:52-04:00",
    "updated_at":"2014-04-17T15:37:08-04:00",
    "address":"45 Main St",
    "address_2":"",
    "city":"New York",
    "state":"NY",
    "zip":"10045",
    "country":"US",
    "phone":"",
    "verified":false,
    "portal_customer_created_at":"2014-04-17T15:37:08-04:00",
    "portal_invite_last_sent_at":"2014-04-17T15:37:08-04:00",
    "portal_invite_last_accepted_at":null
  }
}

When Billing Portal is already enabled for this Customer:


{
  "errors": [ "Portal is already enabled for this customer." ]
}