Signups

Authentication

Chargify Direct resources use different credentials than the regular Chargify API. If you receive a 401 Unauthorized response, please see the section on Authentication in the Chargify Direct Introduction.

Signup Input Attributes

When creating a signup, you must specify a product, customer, and payment_profile, all within the signup object. Credit card details may be required, depending on the options for the Product being subscribed (see Product Options).

Taxable Subscriptions

If your intent is to charge your subscribers tax via Avalara Taxes or 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:

Signup Details

The product may be specified by either product[id] or by producthandle.

  • product
    • id The id of the product your customer is signing up for
    • handle The API handle of the product your customer is signing up for

The customer may be specified by customer[id] or by customer[reference] or by the following attributes:

  • customer
    • first_name (Required)
    • last_name (Required)
    • email (Required)
    • cc_emails (Optional) A comma-separated list of emails that should be cc’d on all customer communications (i.e. “joe@example.com, sue@example.com”)
    • organization (Optional) Customer’s organization
    • reference (Optional, but encouraged) The unique identifier used within your own application for this customer
    • address (Optional) The customer’s shipping street address (i.e. “123 Main St.”).
    • address_2 (Optional) Second line of the customer’s shipping address i.e. “Apt. 100”
    • city (Optional) The customer’s shipping address city (i.e. “Boston”).
    • state (Optional) The customer’s shipping address state (i.e. “MA”)
    • zip (Optional) The customer’s shipping address zip code (i.e. “12345”).
    • country (Optional) The customer shipping address country, perferably in ISO 3166-1 alpha-2 format (i.e. “US”).
    • phone (Optional) The phone number of the customer.

The payment profile may be specified by either payment_profile[id] or by the following attributes:

  • payment_profile
    • first_name First name on card or bank account
    • last_name Last name on card or bank account
    • card_number The full credit card number (string representation, i.e. “5424000000000015”)
    • cvv (Optional if the payment method is a credit card) The 3 or 4 digit card verification value.
    • expiration_month The 1- or 2-digit credit card expiration month, as an integer or string, i.e. “5”
    • expiration_year The 4-digit credit card expiration year, as an integer or string, i.e. “2012”
    • billing_address (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing street address (i.e. “123 Main St.”). This value is merely passed through to the payment gateway.
    • billing_address_2 (Optional) Second line of the customer’s billing address i.e. “Apt. 100”
    • billing_city (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address city (i.e. “Boston”). This value is merely passed through to the payment gateway.
    • billing_state (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address state (i.e. “MA”). This value is merely passed through to the payment gateway.
    • billing_zip (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address zip code (i.e. “12345”). This value is merely passed through to the payment gateway.
    • billing_country (Optional, may be required by your product configuration or gateway settings) The credit card or bank account billing address country, preferably in ISO 3166-1 alpha-2 format (i.e. “US”). This value is merely passed through to the payment gateway. Some gateways require country codes in a specific format. Please check your gateway’s documentation. At this time, when creating a bank account, only US is accepted.
    • bank_name (Required when creating a subscription with ACH) The name of the bank where the customer’s account resides
    • bank_routing_number (Required when creating a subscription with ACH) The routing number of the bank
    • bank_account_number (Required when creating a subscription with ACH) The customer’s bank account number
    • bank_account_type (Required when creating a subscription with ACH) Either checking or savings
    • bank_account_holder_type (Required when creating a subscription with ACH) Either personal or business
    • payment_type Required for PayPal. Set to paypal_account.
    • payment_method_nonce Required for Paypal.
    • paypal_email Required for PayPal, but only used for display.
  • subscription
    • snap_day (Optional) Used for Calendar Billing. Set to a number between 1 and 28, or end.
  • components
  • agreement_terms The ACH agreement terms, if creating a subscription with a bank_account as the payment profile
  • metafields (Optional) A set of key/value pairs representing custom fields and their values. Metafields will be created “on-the-fly” in your site for a given key, if they have not been created yet.
  • ref (Optional, see Referrals for more details.) A valid referral code.
  • coupon_code (Optional, see Coupons for more details.) A valid coupon code.

Components are attached/allocated to the signup by including the component key. The sub-keys should be component IDs, and the values are the allocated quantities.

Signup Request

There are two ways to create a new signup via Chargify Direct. The first is featured below. If you are going to use this method you must be sure to include secure parameters in your request. This example features a form that could be used to create a new signup via Chargify Direct.

URL: https://api.chargify.com/api/v2/signups Method: POST

<form method="post" action="https://api.chargify.com/api/v2/signups">
  <!-- Secure parameters would go here here -->
  <!-- For brevity, this form contains no labels, only inputs -->
  <input type="hidden" name="signup[product][handle]" value="basic" />
  <input type="text" name="signup[customer][first_name]" />
  <input type="text" name="signup[customer][last_name]" />
  <input type="text" name="signup[customer][email]" />
  <input type="text" name="signup[customer][organization]" />
  <input type="text" name="signup[customer][address]" />
  <input type="text" name="signup[customer][address_2]" />
  <input type="text" name="signup[customer][city]" />
  <input type="text" name="signup[customer][state]" />
  <input type="text" name="signup[customer][zip]" />
  <input type="text" name="signup[customer][country]" />
  <input type="text" name="signup[customer][phone]" />
  <input type="text" name="signup[payment_profile][first_name]" />
  <input type="text" name="signup[payment_profile][last_name]" />
  
  <!-- begin credit card fields -->
  <input type="text" name="signup[payment_profile][card_number]" />
  <input type="text" name="signup[payment_profile][expiration_month]" />
  <input type="text" name="signup[payment_profile][expiration_year]" />
  <!-- end credit card fields -->

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

  <input type="text" name="signup[payment_profile][billing_address]" />
  <input type="text" name="signup[payment_profile][billing_address_2]" />
  <input type="text" name="signup[payment_profile][billing_city]" />
  <input type="text" name="signup[payment_profile][billing_state]" />
  <input type="text" name="signup[payment_profile][billing_country]" />
  <input type="text" name="signup[payment_profile][billing_zip]" />
  <input type="text" name="signup[payment_profile][payment_type]" />
  <input type="text" name="signup[agreement_terms]" />
  <input type="submit" value="Sign Up" />
</form>

Example with Components

In order to set components via a Chargify Direct form, you can create form elements similar to the following:

Component Allocation

Assume that there is a Quantity-based Component called “Widgets” with ID 1234 and an On/Off Component with ID 5678 called “Support”

You would like to allow your users to select 1 – 5 Widgets, and turn support On or Off.

<form method="post" action="https://api.chargify.com/api/v2/signups">
  <!-- Secure parameters would go here here -->
  <!-- This form omits product, customer, and payment profile information for brevity -->

  <label for="signup_widgets">How Many Widgets?</label>
  <select name="signup[components][1234]" id="signup_widgets">
    <option value="">Please Select</option>
    <option value="1">1</option>
    <option value="2">2</option>
    <option value="3">3</option>
    <option value="4">4</option>
    <option value="5">5</option>
  </select>

  <label><input type="radio" name="signup[components][5678]" value="1">SSL Support On</label>
  <label><input type="radio" name="signup[components][5678]" value="0">SSL Support Off</label>

  <input type="submit" value="Sign Up" />
</form>

Using A Non-Default Component Price Point

Passing in a hidden field for price_point_id will override the component’s default price point. It’s important to note that the order of the fields matter; always include the hidden field for component_id first for each component that you add.

Note: if the price_point_id that is passed in is invalid, the signup will still proceed but will default to the component’s default price point.

<form method="post" action="https://api.chargify.com/api/v2/signups">
  <!-- Secure parameters would go here here -->
  <!-- This form omits product, customer, and payment profile information for brevity -->

  <input type="hidden" name="signup[components][][component_id]" value="75" />
  <input type="hidden" name="signup[components][][price_point_id]" value="94" />
  <input type="text" name="signup[components][][quantity]" value="3" />

  <input type="hidden" name="signup[components][][component_id]" value="18" />
  <input type="text" name="signup[components][][quantity]" value="10" />

  <input type="submit" value="Sign Up" />
</form>

Example with Custom Fields

Custom Fields (or Metafields) can be included in Chargify Direct forms as follows:

<input type="text" name="signup[metafields][color]" />
<input type="text" name="signup[metafields][size]" />

Example with a Coupon Code

A coupon code can be included in Chargify Direct forms as follows:

<input type="text" name="signup[coupon_code]" />

Example via JSON

New signups can also be created by sending JSON to the same endpoint. If you are going to use this method, you must set the Content-Type header of your HTTP POST request to application/json, otherwise the request will be processed as a Chargify Direct request. JSON Example Request

URL: https://api.chargify.com/api/v2/signups Method: POST Content-Type: application/json

{
  "signup": {
    "product": {
      "handle": "pro"
    },
    "customer": {        
      "first_name": "Marky",
      "last_name": "Mark",
      "email": "marky@example.com",
      "organization": "Funky Company",
      "reference": "funky-123",
      "phone": "555-555-5555",
      "address": "123 2nd Street",
      "address_2": "Apt 5B",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "zip": "10004"
    },
    "payment_profile": {
      "first_name": "Marky",
      "last_name": "Mark",
      "card_number": "1234123412341234",
      "expiration_month": "02",
      "expiration_year": "2022",
      "billing_address": "123 2nd Street",
      "billing_address_2": "Apt 5B",
      "billing_city": "New York",
      "billing_state": "NY",
      "billing_country": "US",
      "billing_zip": "10004"
    },
    "components": {
      "1234": 4,
      "5678": 0
    }
  }
}

Note that the above example shows setting a Quantity-based Component with ID “1234” to an allocated quantity of 4, and an On/Off Component with ID “5678” to “Off”.

Example via ACH

{
  "signup": {
    "agreement_terms": "I hereby agree to ACH.",
    "product": {
      "handle": "pro"
    },
    "customer": {        
      "first_name": "Marky",
      "last_name": "Mark",
      "email": "marky@example.com",
      "organization": "Funky Company",
      "reference": "funky-123",
      "phone": "555-555-5555",
      "address": "123 2nd Street",
      "address_2": "Apt 5B",
      "city": "New York",
      "state": "NY",
      "country": "US",
      "zip": "10004"
    },
    "payment_profile": {
      "first_name": "Marky",
      "last_name": "Mark",
      "payment_type": "bank_account",                                                                                                                             
      "bank_name": "My Bank",                                                                                                                                          
      "bank_routing_number": "123412341",                                                                                                                               
      "bank_account_number": "123412341234",                                                                                                                           
      "bank_account_type": "checking",                                                                                                                                 
      "bank_account_holder_type": "personal",
      "billing_address": "123 2nd Street",
      "billing_address_2": "Apt 5B",
      "billing_city": "New York",
      "billing_state": "NY",
      "billing_country": "US",
      "billing_zip": "10004"
    }
  }
}

Example with metafields

{
  "signup": {
    [...]
    "metafields": {
      "color": "blue",
      "size": "large"
    }
  }
}

Signup Response

See Chargify Direct Response Parameters for details on Chargify Direct responses. JSON.

The following is an example of a successful JSON POST to /signups:

{
  "result": {
    "status_code": "200",
    "result_code": "2000",
    "errors": []
  },
  "meta": {
    "status_code": "200",
    "result_code": "2000",
    "errors": []
  },
  "signup": {
    "product": {
      "id": 100002,
      "handle": "pro",
      "name": "Pro",
      "accounting_code": "",
      "description": "Pro Super Widget",
      "price_in_cents": 9900,
      "interval_unit": "month",
      "interval": 1,
      "initial_charge_in_cents": null,
      "trial_price_in_cents": null,
      "trial_interval": null,
      "trial_interval_unit": "month",
      "expiration_interval_unit": "never",
      "expiration_interval": null,
      "return_url": "",
      "return_params": "",
      "require_credit_card": false,
      "request_credit_card": true,
      "created_at": "2013-08-23T14:39:41-04:00",
      "updated_at": "2013-09-05T22:58:29-04:00",
      "archived_at": null,
      "product_family_id": 100000
    },
    "customer": {
      "id": 100016,
      "reference": "funky-123",
      "first_name": "Marky",
      "last_name": "Mark",
      "email": "marky@example.com",
      "organization": "Funky Company",
      "address": "123 2nd Street",
      "address_2": "Apt 5B",
      "city": "New York",
      "state": "NY",
      "zip": "10004",
      "country": "US",
      "phone": "555-555-5555",
      "created_at": "2013-09-20T11:19:11-04:00",
      "updated_at": "2013-09-20T11:19:12-04:00"
    },
    "payment_profile": {
      "id": 56,
      "first_name": "Marky",
      "last_name": "Mark",
      "masked_card_number": "XXXX-XXXX-XXXX-1234",
      "card_type": "bogus",
      "expiration_month": 2,
      "expiration_year": 2022,
      "billing_address": "123 2nd Street",
      "billing_address_2": "Apt 5B",
      "billing_city": "New York",
      "billing_state": "NY",
      "billing_country": "US",
      "billing_zip": "10004",
      "current_vault": "bogus",
      "vault_token": "1",
      "customer_vault_token": null,
      "customer_id": 100016,
      "created_at": "2013-09-20T11:19:11-04:00",
      "updated_at": "2013-09-20T11:19:11-04:00"
    },
    "subscription": {
      "id": 100051,
      "state": "active",
      "balance_in_cents": 9900,
      "current_period_ends_at": "2013-10-20T11:19:11-04:00",
      "next_assessment_at": "2013-10-20T11:19:11-04:00",
      "trial_started_at": null,
      "trial_ended_at": null,
      "activated_at": "2013-09-20T11:19:11-04:00",
      "expires_at": null,
      "created_at": "2013-09-20T11:19:11-04:00",
      "updated_at": "2013-09-20T11:19:11-04:00",
      "cancellation_message": null,
      "cancel_at_end_of_period": false,
      "canceled_at": null,
      "current_period_started_at": "2013-09-20T11:19:11-04:00",
      "previous_state": "active",
      "signup_payment_id": 146,
      "signup_revenue": "99.00",
      "delayed_cancel_at": null,
      "customer_id": 100016,
      "product_id": 100002,
      "payment_profile_id": 56
    },
    "next_billing_manifest": {
      "total_tax_in_cents": 0,
      "start_date": "2013-10-20T11:19:11-04:00",
      "line_items": [
        {
          "discount_amount_in_cents": 0,
          "taxable_amount_in_cents": 9900,
          "transaction_type": "charge",
          "kind": "baseline",
          "amount_in_cents": 9900,
          "memo": "Pro (10/20/2013 - 11/20/2013)"
        }
      ],
      "total_discount_in_cents": 0,
      "end_date": "2013-11-20T11:19:11-05:00",
      "subtotal_in_cents": 9900,
      "total_in_cents": 9900,
      "period_type": "recurring"
    }
  }
}

Unsuccessful Responses

Any errors will be returned within the meta[errors] and result[errors] objects. For example, when trying to create a new subscription without passing in the payment_profile[expiration_month], the following is returned:

{
  "result": {
    "status_code": "422",
    "result_code": "4000",
    "errors": [
      {
        "attribute": "payment_profile.expiration_month",
        "message": "Credit card expiration month: cannot be blank."
      }
    ]
  },
  "meta": {
    "status_code": "422",
    "result_code": "4000",
    "errors": [
      {
        "attribute": "payment_profile.expiration_month",
        "message": "Credit card expiration month: cannot be blank."
      }
    ]
  }
}

Not passing in a customer at all will yield the following response:

{
  "result": {
    "status_code": "422",
    "result_code": "4000",
    "errors": [
      {
        "attribute": "customer",
        "message": "A Customer must be specified for the subscription to be valid."
      }
    ]
  },
  "meta": {
    "status_code": "422",
    "result_code": "4000",
    "errors": [
      {
        "attribute": "customer",
        "message": "A Customer must be specified for the subscription to be valid."
      }
    ]
  }
}