Maxio Advanced Billing Developer Portal

The following are a few advanced/expert examples of new signups/subscriptions that you might encounter. These may be common, but it entirely depends on what features of Advanced Billing you use and how you integrate your use of Advanced Billing.

See Create Subscription for details.

Import as new signup/subscription

Example

// POST /subscriptions.json{  "subscription": {    "product_handle": "basic",    "next_billing_at": "2010-08-29T12:00:00-04:00",    "customer_attributes": {      "first_name": "John",      "last_name": "Doe",      "email": "john.doe@example.com",      "reference": "123",      "organization": "Acme Widgets"    },    "payment_profile_attributes": {      "vault_token": "12345",      "customer_vault_token": "67890",      "current_vault": "authorizenet",      "expiration_year": "2020",      "expiration_month": "12",      "card_type": "visa",      "last_four": "1111"    }  }}

New Subscription with Coupon/Trial/Component

Signups can implement coupons, custom trial periods and components right from the initial creation of the subscription, like in the following:

Example

{  "subscription": {    "product_handle": "basic",    "customer_attributes": {      "first_name": "John",      "last_name": "Smith",      "email": "john@example.com"    },    "credit_card_attributes": {      "masked_card_number": "XXXX-XXXX-XXXX-1111",      "expiration_month": "10",      "expiration_year": "2020"    },    "coupon_code": "SUB111",    "next_billing_at": "2020-06-01",    "components": [      {        "component_id": 123456,        "unit_balance": 20      }    ]  }}

New Subscription with Existing Payment Profile

Metafields and Metadata

Metafields allow you to create custom fields that store information in a customer or subscription resource in Advanced Billing. Metafields and metadata are called Custom Fields in the application and product documentation.

The following example creates a metafield, and then sets the metadata value for it.

Example

First, create a metafield. In this example, a color field is applied to the Customers resource:

// POST /customers/metafields.json{  "metafields": {    "name": "Color",    "scope": {      "csv": "1",      "invoices": "1",      "portal": "1"    }  }}

The options for scope set here would show this metafield on Public Signup Pages, show the metadata on invoices, and allow the metadata to be exported via CSV.

Next, set the color for a particular customer:

// POST /customers/{customer_id}/metadata.json{  "metadata": {    "name": "Color",    "value": "Blue"  }}

The particular customer would have the metadata for the metafield "Color" set to "Blue".

For more API information about metafields (the containers of your metadata), see Create Metafields.

Communication

Advanced Billing enables you to communicate with your subscribers through a variety of methods. For more information on these methods, read the given help article:

Email templating
The use of Liquid Syntax in your emails and communications
HTML/text emails
Mass emailing subscribers
Email archives

Dunning

Dunning is the process of how you communicate with your customers in regards to failed credit card transactions and expiring credit cards.

Advanced Billing helps manage the dunning process, or what we like to call the “unhappy path.” Or what happens when a credit card transaction fails. If you’re using Authorize.net, PayPal, or Google Checkout, you have to manually address each credit card issue as it arises. This is both tedious and time consuming and is certainly not the most efficient way to handle problems when executing a large number of transactions.

For more information about dunning - including how to setup your dunning plans, see the Dunning help article.

Referrals

Referrals are a great way to reward your customers for sharing information about your application with new potential users. Advanced Billing generates a referral code for each of your subscriptions and rewards the new customer, as well as the referrer, when a new signup is created with the code.

If referrals are enabled, then every subscription will have a ref (short for "referral code") as part of the available data in the subscription API response.

Example

// GET /subscriptions/{subscription_id}.{format}{  "subscription": {    "id": "123456789",    "state": "active",    // ...    "ref": "trdgzp"  }}

To validate the code, you can do the following:

HTTP GET: https://{subdomain}.chargify.com/referral_codes/validate.{format}?code={ref/referral_code}

If the referral code is valid, the response will be 200 OK. Otherwise, the response will be 404 NOT FOUND.

For more information about referrals, see the Referrals help article.

Notes

You can also enter and manage notes on a subscription. Notes allow you to keep non-structured data associated with individual subscriptions. If you need structured data, consider using Metafields/Metadata.

To create a simple note on a subscription, see the following:

// POST /subscriptions/{subscription_id}/notes.{format}{  "note": {    "body": "This is the note that never ends, it just goes on and on ..",    "sticky": true  }}

Setting the value for sticky to true will show the note prominently when viewing the subscription.

For more information about notes, see Create Subscription Note.

The following are some additional useful topics that you might need to handle or read up on, and are here as reference. These generally are topics which may be useful for expert usage of Advanced Billing. ## Advanced Signup Examples The following are a few advanced/expert examples of new signups/subscriptions that you might encounter. These may be common, but it entirely depends on what features of Advanced Billing you use and how you integrate your use of Advanced Billing. See [Create Subscription](/docs/advanced-billing-api/api-endpoints/subscriptions/createsubscription) for details. 1. Import as new signup/subscription **Example** ```json // POST /subscriptions.json { "subscription": { "product_handle": "basic", "next_billing_at": "2010-08-29T12:00:00-04:00", "customer_attributes": { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "reference": "123", "organization": "Acme Widgets" }, "payment_profile_attributes": { "vault_token": "12345", "customer_vault_token": "67890", "current_vault": "authorizenet", "expiration_year": "2020", "expiration_month": "12", "card_type": "visa", "last_four": "1111" } } } ``` 2. New Subscription with Coupon/Trial/Component Signups can implement coupons, custom trial periods and components right from the initial creation of the subscription, like in the following: **Example** ```json { "subscription": { "product_handle": "basic", "customer_attributes": { "first_name": "John", "last_name": "Smith", "email": "john@example.com" }, "credit_card_attributes": { "masked_card_number": "XXXX-XXXX-XXXX-1111", "expiration_month": "10", "expiration_year": "2020" }, "coupon_code": "SUB111", "next_billing_at": "2020-06-01", "components": [ { "component_id": 123456, "unit_balance": 20 } ] } } ``` 3. New Subscription with Existing Payment Profile ## Metafields and Metadata Metafields allow you to create custom fields that store information in a customer or subscription resource in Advanced Billing. Metafields and metadata are called [Custom Fields](https://docs.maxio.com/hc/en-us/articles/24178993762317-Custom-Fields) in the application and product documentation. The following example creates a metafield, and then sets the metadata value for it. **Example** First, create a metafield. In this example, a color field is applied to the Customers resource: ```json // POST /customers/metafields.json { "metafields": { "name": "Color", "scope": { "csv": "1", "invoices": "1", "portal": "1" } } } ``` The options for `scope` set here would show this metafield on Public Signup Pages, show the metadata on invoices, and allow the metadata to be exported via CSV. Next, set the color for a particular customer: ```json // POST /customers/{customer_id}/metadata.json { "metadata": { "name": "Color", "value": "Blue" } } ``` The particular customer would have the metadata for the metafield "Color" set to "Blue". For more API information about metafields (the containers of your metadata), see [Create Metafields](/docs/advanced-billing-api/api-endpoints/custom-fields/createmetafields). ## Communication Advanced Billing enables you to communicate with your subscribers through a variety of methods. For more information on these methods, read the given help article: - [Email templating](https://maxio.zendesk.com/hc/en-us/articles/24266086168461-Email-Templates) - The use of [Liquid Syntax](https://maxio.zendesk.com/hc/en-us/articles/24266086916877-Liquid-Examples) in your emails and communications - [HTML/text emails](https://maxio.zendesk.com/hc/en-us/articles/24266101040781-HTML-Emails) - [Mass emailing subscribers](https://maxio.zendesk.com/hc/en-us/articles/24266110860045-Bulk-Email-Mass-Emailing-Subscribers) - [Email archives](https://maxio.zendesk.com/hc/en-us/articles/24266109347853-Email-Archives) ## Dunning Dunning is the process of how you communicate with your customers in regards to failed credit card transactions and expiring credit cards. Advanced Billing helps manage the dunning process, or what we like to call the “unhappy path.” Or what happens when a credit card transaction fails. If you’re using Authorize.net, PayPal, or Google Checkout, you have to manually address each credit card issue as it arises. This is both tedious and time consuming and is certainly not the most efficient way to handle problems when executing a large number of transactions. For more information about dunning - including how to setup your dunning plans, see the [Dunning](https://maxio.zendesk.com/hc/en-us/articles/24287076583565-Dunning-Overview) help article. ## Referrals Referrals are a great way to reward your customers for sharing information about your application with new potential users. Advanced Billing generates a referral code for each of your subscriptions and rewards the new customer, as well as the referrer, when a new signup is created with the code. If referrals are enabled, then every subscription will have a `ref` (short for "referral code") as part of the available data in the subscription API response. **Example** ```json // GET /subscriptions/{subscription_id}.{format} { "subscription": { "id": "123456789", "state": "active", // ... "ref": "trdgzp" } } ``` To validate the code, you can do the following: HTTP GET: `https://{subdomain}.chargify.com/referral_codes/validate.{format}?code={ref/referral_code}` If the referral code is valid, the response will be `200 OK`. Otherwise, the response will be `404 NOT FOUND`. For more information about referrals, see the [Referrals](https://maxio.zendesk.com/hc/en-us/articles/24287008467725-Referrals-Overview) help article. ## Notes You can also enter and manage notes on a subscription. Notes allow you to keep non-structured data associated with individual subscriptions. If you need structured data, consider using [Metafields/Metadata](/docs/advanced-billing-api/api-endpoints/custom-fields/createmetafields). To create a simple note on a subscription, see the following: ```json // POST /subscriptions/{subscription_id}/notes.{format} { "note": { "body": "This is the note that never ends, it just goes on and on ..", "sticky": true } } ``` Setting the value for `sticky` to `true` will show the note prominently when viewing the subscription. For more information about notes, see [Create Subscription Note](/docs/advanced-billing-api/api-endpoints/subscription-notes/createsubscriptionnote).

Expert Usage

Metafields and Metadata

Communication

Dunning

Referrals

Notes

On this page

Metafields and Metadata

Communication

Dunning

Referrals

Notes