API: Signups

Authentication

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

URI/Method

Resource/URI GET POST PUT DELETE
Signups
signups
Create new signup

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).

The product may be specified by either product[id] or by product[handle] (API Handle).

  • 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, preferably in ISO 3166-1 alpha-2 format (i.e. “US”).
    • phone (Optional) The phone number of the customer.
    • tax_exempt (Optional) The tax exempt status of the customer. Acceptable values are true or 1 for true and false or 0 for false.

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.
    • current_vault (Optional, used only for Subscription Import) The vault that stores the payment profile with the provided vault_token. May be authorizenet, trust_commerce, payment_express, beanstream, braintree1, braintree_blue, paypal, quickpay, eway, eway_rapid_std, stripe, pin, wirecard, bpoint, firstdata, elavon, cybersource, paymill, litle or moneris.
    • vault_token (Optional, used only for Subscription Import) The “token” provided by your vault storage for an already stored payment profile
  • 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. See examples below.

Signup Request

Via Chargify Direct

There are two ways to create a new signup via the Chargify API v2. The first is via Chargify Direct. If you are going to use this method you must be sure to include secure parameters in your request. Below is an example of a form that could be used to create a new signup via Chargify Direct.

Chargify Direct Example Request

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

Chargify Direct 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.

Chargify Direct 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]" />

Chargify Direct Example with a Coupon Code

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

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

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

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”.

And using ACH:

And with metafields:

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

Signup Response

Chargify Direct

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

JSON

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

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:

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