Introduction

The Cheddar API enables you to leverage the full power of Cheddar directly into your custom application. You can use our API with any programming language to integrate the recurring billing and subscription management processes curated by Cheddar.

How Does It Work?

Our API utilizes a REST-like interface where method calls are made by sending HTTP GET or POST requests. Response data is returned in XML format.

The response contains an HTTP status code of 200 for a successful request. A status code of 400 or greater is returned upon an adverse condition. That makes handling errors quite simple.

Ok, That's Nice But How Do I Use It?

First, I suggest reviewing our Open Source Wrappers available for you to use. They make integrating quite easy.

You're also welcome to write your own code to work with the API. If you have questions about that, we're here to help.

Sample Integration

There are just a few things to consider when planning for an integration with the Cheddar API. We've created a KB Article on the subject based on our own PHP wrapper. Check it out.

Open Source Wrappers

The Cheddar API can be leveraged by any programming language. All publicly available code libraries will be made available as they are created. Discussion of these code libraries is welcomed in the Cheddar API Discussion Forum. Please visit the support forum for more information.

Ruby

The officially supported gem from Michael at ExpectedBehavior. The ExpectedBehavior gem fully implements the API and includes 100% test coverage. Check out the docs.

https://github.com/expectedbehavior/cheddargetter_client_ruby

PHP

The PHP Cheddar Client is a wrapper for the Cheddar API provided and supported by the Cheddar team. There's a nice Quick Start Guide. This ZF-compatible library is provided as an open source repository via GitHub here:

http://github.com/marcguyer/cheddar-client-php

Python

Smartfile has taken over maintenance of Sharpy. Thanks, @theSeanOC for the original lib!

https://github.com/smartfile/sharpy

Node.js

Michiel ter Reehorst has taken over maintenance of the Node.js lib, and published it on npm. Follow @_jamiter. Thanks, @respectTheCode for the original lib!

Java

David of Rustici Software has posted his Java offering on GitHub.

https://github.com/RusticiSoftware/CheddarClient

C#

Johnny Arguelles of CollabCoders made his extension of John Siladie’s wrapper available on NuGet.

https://github.com/collabcoders/CheddarGetter

Take a look at Nathan Arnolds's fork of John Siladie's initial release.

https://github.com/shorepound/CheddarGetter

ColdFusion

Will has posted his ColdFusion offering at RIAForge.

http://cfcheddargetter.riaforge.org/

Support

If you have questions about using the Cheddar API, the following support resources are available:

API Knowledge Base

Visit the official Cheddar API Knowledge Base. Most answers are found within this API documentation or within the Cheddar API Knowledge Base.

General Knowledge Base

We publish all known issues in our Knowledge Base because developers leveraging the Cheddar API best exercise the code and identify potential errors. If you have a problem, please search the Knowledge Base to see if we are already aware of the issue. If you verify an issue report does not exist, please describe your issue in a new post with as much detail as possible.

Public and Private Discussion

If you need help not found in the Knowledge Base, start a new public discussion. If your question contains sensitive information, feel free to mark the discussion as private.

Request/Response Format

Authentication

Authentication is achieved via HTTP Basic Authentication.

username: Email address of an authorized user of Cheddar
password: Password for the authorized user

It is recommended that you use a different user account for development accounts vs. live accounts. It's also a good idea to use a dedicated user account just for API authentication.

Request

The standard URL format is: https://getcheddar.com/xml/<PATH>/productCode/<MY_PRODUCT_CODE>[/PARAMS]

For example:

https://getcheddar.com/xml/customers/get/productCode/MY_PRODUCT_CODE

gets all customer data for the product with productCode=MY_PRODUCT_CODE

and

https://getcheddar.com/xml/customers/get/code/MY_FIRST_CUSTOMER/productCode/MY_PRODUCT_CODE

gets customer data for the customer with code=MY_FIRST_CUSTOMER in the product with code=MY_PRODUCT_CODE

Response

Response format is XML. There are three response document types: Plans, Customers, and Error. The Plans document is returned when interacting with pricing plans (a simple GET, for example). The Customers document is returned when interacting with customers.

You may also view raw API responses within the GUI. For example, if you're looking at your customer list:

https://getcheddar.com/admin/customers/get

Simply change /admin/ to /xml/:

https://getcheddar.com/xml/customers/get

Plans Response Example

Customers Response Example

Error Response Example

Request Dictionary

All API request types and parameters are logically named and should be easily understandable. The following outlines each possible API call and required parameters.

Pricing Plans

Get All Pricing Plans

Get all pricing plan data from the product with productCode=MY_PRODUCT_CODE

/plans/get/productCode/MY_PRODUCT_CODE

Get a Single Pricing Plan

Get the pricing plan data from the product with productCode=MY_PRODUCT_CODE for the pricing plan with code=MY_PLAN_CODE

/plans/get/productCode/MY_PRODUCT_CODE/code/MY_PLAN_CODE

Customers

Get All Customers

Get all customer data from the product with productCode=MY_PRODUCT_CODE

/customers/get/productCode/MY_PRODUCT_CODE

Name	Description
`subscriptionStatus`	"activeOnly" or "canceledOnly"
`planCode[]`	Your pricing plan code. This is an array and may be provided multiple times to filter by multiple plans.
`createdAfterDate`	YYYY-MM-DD
`createdBeforeDate`	YYYY-MM-DD
`canceledAfterDate`	YYYY-MM-DD
`canceledBeforeDate`	YYYY-MM-DD
`transactedAfterDate`	YYYY-MM-DD
`transactedBeforeDate`	YYYY-MM-DD
`orderBy`	"name" (default), "company", "plan", "billingDatetime" or "createdDatetime"
`orderByDirection`	"asc" (default) or "desc"
`search`	Text search customer name, company, email address and last four digits of credit card.

Get a Single Customer

Get a Single Customer

curl -u "<username>:<API key>" \
https://getcheddar.com/xml/customers/get/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

$customer = $client->getCustomer('MY_CUSTOMER_CODE');

// get current subscription
$subscription = $customer->getCustomerSubscription();

// is this customer's account active?
$customerIsActive = $customer->getCustomerIsActive();

// get the customer's current subscribed pricing plan
$plan = $customer->getCustomerPlan();

// get the customer's current/pending invoice
$invoice = $customer->getCustomerInvoice();

// See Cheddar_Response for more convenience methods

client.get_customer(:code => 'MY_CUSTOMER_CODE')

Get the customer data from the product with productCode=MY_PRODUCT_CODE for the customer with code=MY_CUSTOMER_CODE (or by id or invoiceNumber).

/customers/get/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

/customers/get/productCode/MY_PRODUCT_CODE/invoiceNumber/1

/customers/get/productCode/MY_PRODUCT_CODE/id/CG_CUSTOMER_ID

Create a New Customer

Create a customer with a credit card

curl -d "code=MY_CUSTOMER_CODE&firstName=Example" \
-d "lastName=Customer&email=example_customer@example.com" \
-d "subscription[planCode]=FREE" \
-d "subscription[ccFirstName]=Example" \
-d "subscription[ccLastName]=Customer" \
-d "subscription[ccNumber]=4111111111111111" \
-d "subscription[ccExpiration]=04/2017" \
-u "<username>:<API key>" \
https://getcheddar.com/xml/customers/new/productCode/MY_PRODUCT_CODE

$data = array(
    'code'      => 'MY_CUSTOMER_CODE',
    'firstName' => 'Example',
    'lastName'  => 'Customer',
    'email'     => 'example_customer@example.com',
    'subscription' => array(
        'planCode'      => 'FREE',
        'ccFirstName'   => 'Example',
        'ccLastName'    => 'Customer',
        'ccNumber'      => '4111111111111111',
        'ccExpiration'  => '04/2017',
    )
);
$customer = $client->newCustomer($data);

client.new_customer(
  :code      => 'MY_CUSTOMER_CODE',
  :firstName => 'Example',
  :lastName  => 'Customer',
  :email     => 'example_customer@example.com',
  :subscription => {
    :planCode     => 'FREE',
    :ccFirstName  => 'Example',
    :ccLastName   => 'Customer',
    :ccNumber     => '4111111111111111',
    :ccExpiration => '04/2017'
  }
)

Create a customer without payment

curl -d "code=MY_CUSTOMER_CODE&firstName=Example" \
-d "lastName=Customer&email=example_customer@example.com" \
-d "subscription[planCode]=FREE" \
-u "<username>:<API key>" \
https://getcheddar.com/xml/customers/new/productCode/MY_PRODUCT_CODE

$data = array(
    'code'      => 'MY_CUSTOMER_CODE',
    'firstName' => 'Example',
    'lastName'  => 'Customer',
    'email'     => 'example_customer@example.com',
    'subscription' => array(
        'planCode'      => 'FREE'
    )
);
$customer = $client->newCustomer($data);

client.new_customer(
  :code      => 'MY_CUSTOMER_CODE',
  :firstName => 'Example',
  :lastName  => 'Customer',
  :email     => 'example_customer@example.com',
  :subscription => {
    :planCode     => 'FREE'
  }
)

Create a new customer in the product with productCode=MY_PRODUCT_CODE and subscribe the customer to a pricing plan.

/customers/new/productCode/MY_PRODUCT_CODE

Name	Description
`code`	Required Your code for this customer. Limited to 255 characters.
`gatewayToken`	Conditional The gateway reference code. Limited to 255 characters.
`firstName`	Required Limited to 40 characters
`lastName`	Required Limited to 40 characters
`email`	Required Valid email address
`company`	Limited to 60 characters
`taxRate`	The rate for this customer if different than the configured default (e.g, 0.123)
`isTaxExempt`	1 or 0
`taxNumber`	Customer tax number if applicable. Limited to 32 characters
`notes`	Limited to 255 characters
`firstContactDatetime`	Date or datetime in ISO 8601 format.(e.g., 2011-08-01 or 2011-08-01T15:30:00+00:00). See the KB Article
`referer`	A valid URL referer. Limited to 255 characters. See the KB Article
`campaignTerm`	The "term" or "keyword" phrase that lead a potential customer to your site. Google Adwords equivalent: "utm_term". See the KB Article
`campaignName`	The name of the marketing campaign. Google Adwords equivalent: "utm_campaign". See the KB Article
`campaignSource`	The source of the lead. Google Adwords equivalent: "utm_source". See the KB Article
`campaignMedium`	The medium used to find your site. Google Adwords equivalent: "utm_medium". See the KB Article
`campaignContent`	The content you wish to track. Google Adwords equivalent: "utm_content". See the KB Article
`metaData[<user-defined>]`	See the KB Article about customer metadata
`subscription[planCode]`	Required Your code for the subscribed pricing plan
`subscription[couponCode]`	Coupon code for the promotion you'd like to apply to the subscription
`subscription[initialBillDate]`	Date or datetime in ISO 8601 format. (e.g., 2011-08-01 or 2011-08-01T15:30:00+00:00). Date on which you would like the customers first invoice to be billable. This option overrides the pricing plan default. Must either be today's date (run invoice immediately) or a future date.
`subscription[method]`	"cc" (default) or "paypal"
`subscription[ccNumber]`	Conditional (See Notes) Numbers only -- a valid credit/debit card number
`subscription[ccExpiration]`	Conditional (See Notes) MM/YYYY - the expiration date for the credit card
`subscription[ccCardCode]`	Conditional. If plan is free, not required. If your preference is to require the `cardCode`, required. Not required when method is paypal. 3-4 digits - The Card Verification Value (CCV).
`subscription[gatewayToken]`	Conditional (See Notes) The gateway reference code for the payment method. Provide this in lieu of `ccNumber` when pre-tokenized payment methods are available.
`subscription[ccType]`	Conditional visa, mc, disc, amex, diners, jcb, unk. If you specify a `subscription[gatewayToken]`, this is required.
`subscription[ccLastFour]`	Conditional Numbers only -- last four digits of credit/debit card number. If you specify a `subscription[gatewayToken]`, this is required.
`subscription[ccFirstName]`	Conditional (See Notes) Limited to 40 characters
`subscription[ccLastName]`	Conditional (See Notes) Limited to 40 characters
`subscription[ccCompany]`	Limited to 60 characters
`subscription[ccCountry]`	Limited to 60 characters. Many payment processors require that the ISO 2 char codes are used.
`subscription[ccAddress]`	Limited to 60 characters
`subscription[ccCity]`	Limited to 40 characters
`subscription[ccState]`	Limited to 40 characters. 2 character state/province codes are suggested when country is US/Canada.
`subscription[ccZip]`	Limited to 20 characters
`subscription[returnUrl]`	Conditional. Required when method is PayPal. Must be a valid URL. Only used when method is paypal. This is the location where subscriber is returned from paypal after accepting a preapproval.
`subscription[cancelUrl]`	Conditional. Required when method is PayPal. Must be a valid URL. Only used when method is paypal. This is the location where subscriber is returned from paypal after declining a preapproval.
`charges[<user-defined>][chargeCode]`	Not Required (See Notes) Your code for this charge. Limited to 36 characters.
`charges[<user-defined>][quantity]`	Not Required (See Notes) Positive integer quantity
`charges[<user-defined>][eachAmount]`	Not Required (See Notes) Positive or negative integer or float with two digit decimal precision. A positive number will create a charge (debit). A negative number will create a credit.
`charges[<user-defined>][description]`	Description for this charge/credit
`items[<user-defined>][itemCode]`	Not Required (See Notes) Your code for this tracked item. Limited to 36 characters.
`items[<user-defined>][quantity]`	Not Required (See Notes) The positive amount accurate to up to 4 decimal places that you wish to set the current usage to for this item. Can be zero.
`remoteAddress`	Not Required (See Below) Client IPv4 address

If the plan is free, only code, firstName, lastName, email and subscription[planCode] are required. If the plan is a paid plan, credit card information is only required if you have configured Cheddar to require it. It can be optional only if the first invoice on a pricing plan is delayed. If a subscription on a paid plan does not have a payment method when it comes time to bill, the subscription will be auto-cancelled. See the the email templates KB Article regarding free trials and the Bill Reminder email.

When using $0.00 verification transactions (e.g., Authorize.Net CIM validationMode=liveMode) for credit card pre-verifications, subscription[ccAddress] and subscription[ccZip] are required.

If pre-tokenized payment methods are available, you may create a new customer with a payment method by providing a subscription[gatewayToken], subscription[ccType], and subscription[ccLastFour] values instead of subscription[ccNumber] and subscription[ccCardCode]. This feature is compatible with only some back-end payment processors. In some cases, only the subscription[gatewayToken] is required as the additional data is subsequently requested from the upstream gateway. In that case, params passed in the request will override/update the the upstream gateway.

Charges are not required but when including charges, chargeCode, quantity and eachAmount are required for each charge.

Items are not required but when including items, itemCode and quantity are required for each item.

Check out this article for more information about using the API with PayPal .

Import Customers

Import customers to the product with productCode=MY_PRODUCT_CODE. Existing paying (or non-paying) customers in another billing system may be imported while maintaining payment methods if the payment processor is compatible. Please contact support for more information about whether or not importing is possible in your situation.

/customers/import/productCode/MY_PRODUCT_CODE

Name	Description
`code`	Required Your code for this customer. Limited to 255 characters.
`gatewayToken`	Conditional The gateway reference code. Limited to 255 characters.
`firstName`	Required Limited to 40 characters
`lastName`	Required Limited to 40 characters
`email`	Required Valid email address
`company`	Limited to 60 characters
`taxRate`	The rate for this customer if different than the configured default (e.g, 0.123)
`isTaxExempt`	1 or 0
`taxNumber`	Customer tax number if applicable. Limited to 32 characters
`notes`	Limited to 255 characters
`firstContactDatetime`	Date or datetime in ISO 8601 format. (e.g., 2011-08-01 or 2011-08-01T15:30:00+00:00). See the KB Article
`referer`	A valid URL referer. Limited to 255 characters. See the KB Article
`campaignTerm`	The "term" or "keyword" phrase that lead a potential customer to your site. Google Adwords equivalent: "utm_term". See the KB Article
`campaignName`	The name of the marketing campaign. Google Adwords equivalent: "utm_campaign". See the KB Article
`campaignSource`	The source of the lead. Google Adwords equivalent: "utm_source". See the KB Article
`campaignMedium`	The medium used to find your site. Google Adwords equivalent: "utm_medium". See the KB Article
`campaignContent`	The content you wish to track. Google Adwords equivalent: "utm_content". See the KB Article
`metaData[<user-defined>]`	See the KB Article about customer metadata
`subscription[planCode]`	Required Your code for the subscribed pricing plan
`subscription[initialBillDate]`	Date or datetime in ISO 8601 format. (e.g., 2011-08-01 or 2011-08-01T15:30:00+00:00). Date on which you would like the customers first invoice to be billable. This option overrides the pricing plan default. Must either be today's date (run invoice immediately) or a future date. If empty, the initial invoice will not be scheduled and a subsequent subscription edit with `changeBillDate` param is required to schedule the invoice.
`subscription[method]`	Conditional Payment method ('cc' or 'paypal'). Required if specifying a payment method. If empty, payment method will be ignored.
`subscription[gatewayToken]`	Conditional The gateway reference code for the payment method. Required if your settings require it and/or if the customer currently has a payment method that you would like to use to continue to bill this customer.
`subscription[ccType]`	Conditional visa, mc, disc, amex, diners, jcb, unk. If you specify a `subscription[gatewayToken]` and `subscription[method]=cc`, this is required.
`subscription[ccLastFour]`	Conditional Numbers only -- last four digits of credit/debit card number. If you specify a `subscription[gatewayToken]` and `subscription[method]=cc`, this is required.
`subscription[ccExpiration]`	Conditional MM/YYYY - the expiration date for the credit/debit card. If you specify a `subscription[gatewayToken]` and `subscription[method]=cc`, this is required.
`subscription[ccFirstName]`	Conditional Limited to 40 characters. If you specify a `subscription[gatewayToken]`, this is required.
`subscription[ccLastName]`	Conditional Limited to 40 characters. If you specify a `subscription[gatewayToken]`, this is required.
`subscription[ccEmail]`	Conditional A valid email address. If you specify a subscription[gatewayToken] and and `subscription[method]=paypal`, this is required and should be the email address of the PayPal account.
`subscription[ccCompany]`	Limited to 60 characters
`subscription[ccCountry]`	Limited to 60 characters. Many payment processors require that the ISO 2 char codes are used.
`subscription[ccAddress]`	Limited to 60 characters
`subscription[ccCity]`	Limited to 40 characters
`subscription[ccState]`	Limited to 40 characters. 2 character state/province codes are suggested when country is US/Canada.
`subscription[ccZip]`	Limited to 20 characters
`charges[<user-defined>][chargeCode]`	Not Required (See Notes) Your code for this charge. Limited to 36 characters.
`charges[<user-defined>][quantity]`	Not Required (See Notes) Positive integer quantity
`charges[<user-defined>][eachAmount]`	Not Required (See Notes) Positive or negative integer or float with two digit decimal precision. A positive number will create a charge (debit). A negative number will create a credit.
`charges[<user-defined>][description]`	Description for this charge/credit
`items[<user-defined>][itemCode]`	Not Required (See Notes) Your code for this tracked item. Limited to 36 characters.
`items[<user-defined>][quantity]`	Not Required (See Notes) The positive amount accurate to up to 4 decimal places that you wish to set the current usage to for this item. Can be zero.

Only direct credit card payment processors are compatible with this import when importing customers with a payment method. Future implementations may include support for additional payment processor types.

Gateway token values are not validated against the upstream gateway. In other words, request data is validated for format only and not for accuracy or existence of the corresponding payment method reference at the upstream payment processor.

Up to 100 customers may be imported in one call. Customer data must be in a nested list.

Any customer may be imported with or without a payment method. If payment method import is desired, the last four digits of the card number, the expiration date and the card type are required (card type may be "unk" if not known).

subscription[initialBillDate] is not required. If specified, the first transaction will occur on the initialBillDate. If empty, the intitial invoice will not be scheduled and a subsequent subscription edit (with `changeBillDate`) is required to schedule the initial invoice.

Charges are not required but when including charges, chargeCode, quantity and eachAmount are required for each charge.

Items are not required but when including items, itemCode and quantity are required for each item.

Check out this article for more information about using the import functionality .

Delete a Customer

Delete an existing customer in the product with productCode=MY_PRODUCT_CODE

/customers/delete/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

Delete All Customers

Delete all existing customers in the product with productCode=MY_PRODUCT_CODE

/customers/delete-all/confirm/[current unix timestamp]/productCode/MY_PRODUCT_CODE

Update a Customer and Subscription

Update a Customer and Subscription

curl -d "firstName=New&lastName=Info&email=new_info@example.com" \
-d "subscription[planCode]=NEW_PLAN_CODE" \
-u "<username>:<API key>" \
https://getcheddar.com/xml/customers/edit/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

$data = array(
    'firstName' => 'New',
    'lastName'  => 'Info',
    'email'     => 'new_info@example.com',
    'subscription' => array(
        'planCode' => 'NEW_PLAN_CODE'
    )
);
$customer = $client->editCustomer('MY_CUSTOMER_CODE', null, $data);

client.edit_customer(
  {:code      => 'MY_CUSTOMER_CODE'},
  {
    :firstName => 'New',
    :lastName  => 'Info',
    :email     => 'new_info@example.com',
    :subscription => {
      :planCode     => 'NEW_PLAN_CODE'
    }
  }
)

Change Next Bill Date

curl -d "changeBillDate=2015-12-09" \
-u "<username>:<API key>" \
https://getcheddar.com/xml/customers/edit-subscription/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

$data = array('changeBillDate' => '2015-12-09T09:36:37-05:00');
$customer = $client->editSubscription('MY_CUSTOMER_CODE', null, $data);

client.edit_subscription(
  {:code      => 'MY_CUSTOMER_CODE'},
  {:changeBillDate     => '2015-12-09T09:36:37-05:00'}
)

Update an existing customer's information in the product with productCode=MY_PRODUCT_CODE and modify the subscription information

/customers/edit/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

Name	Description
`gatewayToken`	The gateway reference code. Limited to 255 characters.
`firstName`	Limited to 20 characters.
`lastName`	Limited to 20 characters.
`email`	Valid email address
`company`	Limited to 60 characters
`notes`	Limited to 255 characters
`taxRate`	The rate for this customer if different than the configured default (e.g, 0.123)
`isTaxExempt`	1 or 0
`taxNumber`	Customer tax number if applicable. Limited to 32 characters
`firstContactDatetime`	Date or datetime in ISO 8601 format. (e.g., 2011-08-01 or 2011-08-01T15:30:00+00:00). See the KB Article
`referer`	A valid URL referer. Limited to 255 characters. See the KB Article
`campaignTerm`	The "term" or "keyword" phrase that lead a potential customer to your site. Google Adwords equivalent: "utm_term". See the KB Article
`campaignName`	The name of the marketing campaign. Google Adwords equivalent: "utm_campaign". See the KB Article
`campaignSource`	The source of the lead. Google Adwords equivalent: "utm_source". See the KB Article
`campaignMedium`	The medium used to find your site. Google Adwords equivalent: "utm_medium". See the KB Article
`campaignContent`	The content you wish to track. Google Adwords equivalent: "utm_content". See the KB Article
`metaData[<user-defined>]`	See the KB Article about customer metadata
`subscription[method]`	"cc" (default) or "paypal"
`subscription[planCode]`	Your code for the subscribed pricing plan
`subscription[couponCode]`	Coupon code for the promotion you'd like to apply to the subscription
`subscription[ccNumber]`	Not Required (See Notes) Numbers only -- a valid credit/debit card number
`subscription[ccExpiration]`	Not Required (See Notes) MM/YYYY - the expiration date for the credit card
`subscription[ccCardCode]`	Conditional. If plan is free, no. If your preference is to require the cardCode, yes. 3-4 digits - The Card Verification Value (CCV).
`subscription[gatewayToken]`	Conditional (See Notes) The gateway reference code for the payment method. Provide this in lieu of `ccNumber` when pre-tokenized payment methods are available.
`subscription[ccType]`	Conditional visa, mc, disc, amex, diners, jcb, unk. If you specify a `subscription[gatewayToken]`, this is required.
`subscription[ccLastFour]`	Conditional Numbers only -- last four digits of credit/debit card number. If you specify a `subscription[gatewayToken]`, this is required.
`subscription[ccFirstName]`	Not Required (See Notes) Limited to 20 characters
`subscription[ccLastName]`	Not Required (See Notes) Limited to 20 characters
`subscription[ccCompany]`	Limited to 50 characters
`subscription[ccCountry]`	Limited to 60 characters. Many payment processors require that the ISO 2 char codes are used.
`subscription[ccAddress]`	Limited to 60 characters
`subscription[ccCity]`	Limited to 40 characters
`subscription[ccState]`	Suggested when country is US/Canada.
`subscription[ccZip]`	Conditional. If plan is free, no. If your preference is to require the zip, yes.
`subscription[returnUrl]`	Conditional. Required when method is paypal. Must be a valid URL. Only used when method is paypal. This is the location where subscriber is returned from paypal after accepting a preapproval.
`subscription[cancelUrl]`	Conditional. Required when method is paypal. Must be a valid URL. Only used when method is paypal. This is the location where subscriber is returned from paypal after declining a preapproval.
`subscription[changeBillDate]`	Date or datetime in ISO 8601 format. (e.g., 2011-08-01 or 2011-08-01T15:30:00+00:00). You may also use the word 'now' as shorthand for the current datetime.
`remoteAddress`	Not Required (See Below) Client IPv4 address

If the customer does not already have a subscription with a valid credit card, all credit card information is required. If the plan code corresponds to a "free" plan, no Credit Card data is required. If the customer already has a subscription with a credit card, no credit card information data is required. In this instance, any subset of credit card data may be provided.

If the plan is a paid plan, credit card information is only required if you have configured Cheddar to require it. It can be optional only if the next invoice is delayed. If a subscription on a paid plan does not have a credit card when it comes time to bill, the subscription will be auto-cancelled. See the email templates KB Article regarding free trials and the Bill Reminder email.

Changing the next bill date using subscription[changeBillDate] effects the billing cycle. Subsequent bill dates will be on the new cycle. In other words, for a monthly plan that typically bills on the 3rd of every month, if the next bill date is changed to the 10th, the subscription will now bill every month on the 10th. If the date is equal to 'now' or is less than or equal to the current date and time, the current invoice will be executed in real-time.

Check out this article for more information about using the API with PayPal .

Update a Customer Only

Update a Customer

curl -d "firstName=New&lastName=Name" \
-u "<username>:<API key>" \
https://getcheddar.com/xml/customers/edit/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

$data = array(
    'firstName' => 'New',
    'lastName'  => 'Info',
    'email'     => 'new_info@example.com'
);
$customer = $client->editCustomerOnly('MY_CUSTOMER_CODE', null, $data);

client.edit_customer_only(
  {:code       => 'MY_CUSTOMER_CODE'},
  {
    :firstName => 'New',
    :lastName  => 'Info',
    :email     => 'new_info@example.com',
    :company   => '',
    :notes     => ''
  }
)

Update an existing customer's information in the product with productCode=MY_PRODUCT_CODE

/customers/edit-customer/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

Name	Description
`firstName`	Limited to 20 characters.
`lastName`	Limited to 20 characters.
`email`	Valid email address
`company`	Limited to 60 characters
`notes`	Limited to 255 characters
`taxRate`	The rate for this customer if different than the configured default (e.g, 0.123)
`isTaxExempt`	1 or 0
`taxNumber`	Customer tax number if applicable. Limited to 32 characters
`firstContactDatetime`	Date or datetime in ISO 8601 format. (e.g., 2011-08-01 or 2011-08-01T15:30:00+00:00). See the KB Article
`referer`	A valid URL referer. Limited to 255 characters. See the KB Article
`campaignTerm`	The "term" or "keyword" phrase that lead a potential customer to your site. Google Adwords equivalent: "utm_term". See the KB Article
`campaignName`	The name of the marketing campaign. Google Adwords equivalent: "utm_campaign". See the KB Article
`campaignSource`	The source of the lead. Google Adwords equivalent: "utm_source". See the KB Article
`campaignMedium`	The medium used to find your site. Google Adwords equivalent: "utm_medium". See the KB Article
`campaignContent`	The content you wish to track. Google Adwords equivalent: "utm_content". See the KB Article
`metaData[<user-defined>]`	See the KB Article about customer metadata
`remoteAddress`	Not Required (See Below) Client IPv4 address

Subscriptions

Update a Subscription Only

Update a Customer's Subscription

curl -d "planCode=NEW_PLAN_CODE" \
-u "<username>:<API key>" \
https://getcheddar.com/xml/customers/edit-subscription/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

$data = array('planCode' => 'NEW_PLAN_CODE');
$customer = $client->editSubscription('MY_CUSTOMER_CODE', null, $data);

client.edit_subscription(
  {:code      => 'MY_CUSTOMER_CODE'},
  {:planCode     => 'NEW_PLAN_CODE'}
)

Update an existing customer's subscription information in the product with productCode=MY_PRODUCT_CODE

/customers/edit-subscription/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

Name	Description
`method`	"cc" (default) or "paypal"
`planCode`	Your code for the subscribed plan
`couponCode`	Coupon code you'd like to apply to the subscription
`ccNumber`	Not Required (See Notes) Numbers only -- a valid credit/debit card number
`ccExpiration`	Not Required (See Notes) MM/YYYY - the expiration date for the credit card
`ccCardCode`	Not Required (See Notes) 3-4 digits - The Card Verification Value (CCV).
`gatewayToken`	Conditional (See Notes) The gateway reference code for the payment method. Provide this in lieu of `ccNumber` when pre-tokenized payment methods are available.
`ccType`	Conditional visa, mc, disc, amex, diners, jcb, unk. If you specify a `gatewayToken`, this is required.
`ccLastFour`	Conditional Numbers only -- last four digits of credit/debit card number. If you specify a `subscription[gatewayToken]`, this is required.
`ccFirstName`	Not Required (See Notes) Limited to 20 characters
`ccLastName`	Not Required (See Notes) Limited to 20 characters
`ccCompany`	Limited to 50 characters
`ccCountry`	Limited to 60 characters. Many payment processors require that the ISO 2 char codes are used.
`ccAddress`	Limited to 60 characters
`ccCity`	Limited to 40 characters
`ccState`	Limited to 40 characters. 2 character state/province codes are suggested when country is US/Canada.
`ccZip`	Not Required (See Notes) Limited to 20 characters
`returnUrl`	Conditional. Required when method is paypal. Must be a valid URL. Only used when method is paypal. This is the location where subscriber is returned from paypal after accepting a preapproval.
`cancelUrl`	Conditional. Required when method is paypal. Must be a valid URL. Only used when method is paypal. This is the location where subscriber is returned from paypal after declining a preapproval.
`changeBillDate`	Date or datetime in ISO 8601 format. (e.g., 2011-08-01 or 2011-08-01T15:30:00+00:00). You may also use the word 'now' as shorthand for the current datetime.
`remoteAddress`	Not Required (See Below) Client IPv4 address

If the customer does not already have a subscription with a valid credit card, all credit card information is required. If the plan code corresponds to a "free" plan, no credit card data is required. If the customer already has a subscription with a credit card, no credit card information data is required. In this instance, any subset of credit card data may be provided. Your preferences still apply for ccCardCode and ccZip.

If pre-tokenized payment methods are available, you may create a new customer with a payment method by providing a gatewayToken, ccType, and ccLastFour values instead of ccNumber and ccCardCode. This feature is compatible with only some back-end payment processors. In some cases, only the subscription[gatewayToken] is required as the additional data is subsequently requested from the upstream gateway. In that case, params passed in the request will override/update the the upstream gateway.

Check out this article for more information about using the API with PayPal .

Cancel a Customer's Subscription

Cancel an existing customer's subscription in the product with productCode=MY_PRODUCT_CODE

/customers/cancel/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

Tracked Items

Use the tracked item endpoints to set, increment, or decrement the quantity of and item for an individual subscription.

Learn more about using Tracked Items in the Knowledge Base

Note: Updates of item quantities on canceled subscriptions are only possible under a few circumstances:

The cancellation is the special paypal-wait state and the PayPal preapproval request period is still valid (up to 3 hours)
The canceled subscription has a pending invoice with a billingDatetime in the future
The quantity update request is for the outstanding invoice. The request includes the invoicePeriod parameter and it is set to outstanding

Add Item Quantity

Add Item Quantity

curl -u "<username>:<API key>" \
https://getcheddar.com/xml/customers/add-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE

$data = array(
    'itemCode' => 'MY_ITEM_CODE'
);

$quantity = $client->addItemQuantity('MY_CUSTOMER_CODE', null, $data);

client.add_item_quantity(
    {
        :code => 'MY_CUSTOMER_CODE',
        :item_code => 'MY_ITEM_CODE'
    }
)

Increment a customer's current usage of a single item in the product with productCode=MY_PRODUCT_CODE

/customers/add-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE

Name	Description
`quantity`	The positive amount accurate to up to 4 decimal places (if other that 1.0000) that you wish to add to the current usage for this item.
`remoteAddress`	Not Required (See Below) Client IPv4 address

quantity is only required if you wish to add more than one to the current usage amount.

Remove Item Quantity

Remove Item Quantity

curl -u "<username>:<API key>" \
https://getcheddar.com/xml/customers/remove-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE

$data = array(
    'itemCode' => 'MY_ITEM_CODE'
);

$quantity = $client->removeItemQuantity('MY_CUSTOMER_CODE', null, $data);

client.remove_item_quantity(
    {
        :code => 'MY_CUSTOMER_CODE',
        :item_code => 'MY_ITEM_CODE'
    }
)

Decrement a customer's current usage of a single item in the product with productCode=MY_PRODUCT_CODE

/customers/remove-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE

Name	Description
`quantity`	The positive amount accurate to up to 4 decimal places (if other that 1.0000) that you wish to remove from the customer's current quantity for this item.
`remoteAddress`	Not Required (see below) Client IPv4 address

quantity is only required if you wish to subtract more than 1 from the current usage amount.

Set Item Quantity

Set Item Quantity

curl -d "quantity=1.0000" \
-u "<username>:<API key>" \
https://getcheddar.com/xml/customers/set-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE

$data = array(
    'itemCode' => 'MY_ITEM_CODE',
    'quantity' => 1.0000
);

$quantity = $client->setItemQuantity('MY_CUSTOMER_CODE', null, $data);

client.set_item_quantity(
    {
        :code => 'MY_CUSTOMER_CODE',
        :item_code => 'MY_ITEM_CODE'
    },
    {
        :charge_code => 'CHARGE_CODE',
        :quantity => 1.0000,
        :eachAmount => '1'
    }
)

Set a customer's current usage of a single item in the product with productCode=MY_PRODUCT_CODE

/customers/set-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE

Name	Description
`quantity`	Yes
`invoicePeriod`	The billing period - 'current' (the default) or 'outstanding'. See below.
`remoteAddress`	Not Required (see below) Client IPv4 address

Invoice Interactions

Add a Custom Charge/Credit

Add a Custom Charge

curl -d "chargeCode=CHARGE_CODE" \
-d "quantity=3" \
-d "eachAmount=2.50" \
-u "<username>:<API key>" \
https://getcheddar.com/xml/customers/add-charge/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

$data = array(
    'chargeCode' => 'CHARGE_CODE',
    'quantity' => 3,
    'eachAmount' => 2.50,
    'description' => 'Example charge'
);
$customer = $client->addCharge('MY_CUSTOMER_CODE', null, $data);

client.add_charge(
    {:code => 'MY_CUSTOMER_CODE'},
    {
        :chargeCode => 'CHARGE_CODE',
        :quantity => 3,
        :eachAmount => 2.50,
        :description => 'Example charge'
    }
)

Add a Custom Credit

curl -d "chargeCode=CREDIT_CODE" \
-d "quantity=2" \
-d "eachAmount=-8.00" \
-u "<username>:<API key>" \
https://getcheddar.com/xml/customers/add-charge/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

$data = array(
    'chargeCode' => 'CHARGE_CODE',
    'quantity' => 3,
    'eachAmount' => 2.50,
    'description' => 'Example charge'
);
$customer = $client->addCharge('MY_CUSTOMER_CODE', null, $data);

client.add_charge(
    {:code => 'MY_CUSTOMER_CODE'},
    {
        :chargeCode => 'CHARGE_CODE',
        :quantity => 2,
        :eachAmount => -8.00, // set negative value for a credit
        :description => 'Example credit'
    }
)

Add an arbitrary charge or credit to the customer's current invoice in the product with productCode=MY_PRODUCT_CODE

/customers/add-charge/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

Name	Description
`chargeCode`	Required Your code for this charge. Limited to 36 characters.
`quantity`	Required Positive integer quantity
`eachAmount`	Required Positive or negative integer or float with two digit decimal precision. A positive number will create a charge (debit). A negative number will create a credit.
`description`	Description for this charge/credit
`invoicePeriod`	The billing period - 'current' (the default) or 'outstanding'. See below.
`remoteAddress`	Not Required (see below) Client IPv4 address

Delete a Custom Charge/Credit

Delete a Custom Charge/Credit

curl -d "chargeId=CHARGE_ID" \
-u "<username>:<API key>" \
https://chedddargetter.com/xml/customers/delete-charge/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

$data = array(
    'chargeId' => 'CHARGE_ID'
);
$customer = $client->deleteCharge('MY_CUSTOMER_CODE', null, $data);

client.delete_charge(
    {:code => 'MY_CUSTOMER_CODE'},
    {
        :chargeId => 'CHARGE_ID'
    }
)

Remove a charge or credit from the customer's current invoice in the product with productCode=MY_PRODUCT_CODE

/customers/delete-charge/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

Name	Description
`chargeId`	Required Cheddar's ID for the charge/credit
`invoicePeriod`	The billing period - 'current' (the default) or 'outstanding'. See below.
`remoteAddress`	Not Required (see below) Client IPv4 address

Create a One-Time Invoice

Create a parallel one-time invoice and execute the transaction immediately using the customer's current payment method in the product with productCode=MY_PRODUCT_CODE

/invoices/new/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

Name	Description
`charges[<user-defined>][chargeCode]`	Required Your code for this charge. Limited to 36 characters.
`charges[<user-defined>][quantity]`	Required Positive integer quantity
`charges[<user-defined>][eachAmount]`	Required Positive or negative integer or float with two digit decimal precision. A positive number will create a charge (debit). A negative number will create a credit.
`charges[<user-defined>][description]`	Description for this charge/credit
`remoteAddress`	Not Required (see below) Client IPv4 address

Run an Outstanding Invoice

Execute an outstanding invoice in the product with productCode=MY_PRODUCT_CODE

/customers/run-outstanding/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE

Name	Description
`ccCardCode`	Not Required 3-4 digits - The Card Verification Value (CCV).
`remoteAddress`	Not Required (see below) Client IPv4 address

Issue a Refund

Refund a transaction on a billed invoice in the product with productCode=MY_PRODUCT_CODE

/invoices/refund/productCode/MY_PRODUCT_CODE

Name	Description
`number` or `id`	Required Either Cheddar's ID for the invoice or the Cheddar-generated invoice number
`amount`	Required An amount less than or equal to the refundable amount. See notes.
`remoteAddress`	Not Required (see below) Client IPv4 address

Issue a Void

Void a transaction on a billed invoice in the product with productCode=MY_PRODUCT_CODE

/invoices/void/productCode/MY_PRODUCT_CODE

Name	Description
`number` or `id`	Required Either Cheddar's ID for the invoice or the Cheddar-generated invoice number
`remoteAddress`	Not Required (see below) lient IPv4 address

Issue a Void or Refund

Defer to Cheddar to decide if a void or a refund is executed against the invoice in the product with productCode=MY_PRODUCT_CODE

/invoices/void-or-refund/productCode/MY_PRODUCT_CODE

Name	Description
`number` or `id`	Required Either Cheddar's ID for the invoice or the Cheddar-generated invoice number
`remoteAddress`	Not Required (see below) Client IPv4 address

Send or Resend an Invoice email

Send (or resend) email notification for the invoice in the product with productCode=MY_PRODUCT_CODE

/invoices/send-email/productCode/MY_PRODUCT_CODE

Name	Description
`number` or `id`	Required Either Cheddar's ID for the invoice or the Cheddar-generated invoice number
`remoteAddress`	Not Required (see below) Client IPv4 address

Promotions

Get all Promotions

Get all promotion data from the product with productCode=MY_PRODUCT_CODE

/promotions/get/productCode/MY_PRODUCT_CODE

Get a Single Promotions

Get the promotion data from the product with productCode=MY_PRODUCT_CODE for the promotion with coupon code=MY_COUPON_CODE

/promotions/get/productCode/MY_PRODUCT_CODE/code/MY_COUPON_CODE

Current vs. Outstanding Invoice

Many API calls interact with a customer's subscription invoice. The "current" subscription invoice is the one that is currently "open". In other words, it is scheduled to bill in the future. You can add charges, credits, and item quantities to a subscription invoice. In almost every case, you'll want to interact with the "current" subscription invoice. This is the default for all relevant API calls. In rare cases, you might want to adjust the "outstanding" subscription invoice.

An outstanding invoice is one that was scheduled to bill in the past but has not yet been paid. This could be a scheduled invoice that was attempted but declined (the subscriber is in the dunning process) or simply one that's scheduled in the past but Cheddar's recurring engine hasn't picked it up for execution yet. If a subscription is canceled for non-payment, it almost certainly has an outstanding invoice.

Some API methods have a parameter named invoicePeriod. In the case when you want to interact with the outstanding invoice, set the value for this parameter to "outstanding".

Response Codes

HTTP Status Codes

The Cheddar API returns appropriate HTTP status codes for every request.

Code	Meaning
`200 OK`	Success!
`400 Bad Request`	The request was invalid. An accompanying error message will explain why.
`404 Not Found`	The URI requested is invalid or the resource requested, such as a user, does not exist.
`412 Precondition Failed`	The request contains POST data that is in an invalid format or required parameters are missing.
`422 Unprocessable Entity`	The gateway doesn't like the payment data. In other words, the gateway failed to process the request.
`500 Internal Server Error`	Something is broken. Please post in the support forum so the Cheddar team can investigate.
`502 Bad Gateway`	Communication with the payment gateway failed. Try again later.

Error Messages

When the Cheddar API returns error messages, it does so in XML format. For example, an error from an XML method might look like this:

<error id="1234" code="404" auxCode="">Customer not found</error>

Errors are logged and exposed to you in the admin GUI: https://getcheddar.com/admin/activity/errors

More information about errors is available in this KB article

Fraud Protection, Rate Limiting

All API requests should include the client IP address if possible. If not provided, the IP of the machine making the request will be used. This value is used for rate limiting, fraud protection, etc. To prevent the same fraudster from attempting to signup for your service over and over and over again with different credit card numbers, you'll need to provide the IP address with the request.

Webhooks, Reverse API, Callbacks

Yup, Cheddar supports custom webhooks as well as some pre-defined third party hooks. The hook system is fault tolerant with automatic retries and includes a management console and some other niceties at no extra charge (ooh, burn!). Yeah, we're pretty proud of it.

More information about webhooks

API Reference

Introduction

How Does It Work?

Ok, That's Nice But How Do I Use It?

Sample Integration

Open Source Wrappers

Ruby

PHP

Python

Node.js

Java

C#

ColdFusion

Support

API Knowledge Base

General Knowledge Base

Public and Private Discussion

Request/Response Format

Authentication

Request

Response

Plans Response Example

Customers Response Example

Error Response Example

Request Dictionary

Pricing Plans

Get All Pricing Plans

Get a Single Pricing Plan

Customers

Get All Customers

Get a Single Customer

Create a New Customer

Import Customers

Delete a Customer

Delete All Customers

Update a Customer and Subscription

Update a Customer Only

Subscriptions

Update a Subscription Only

Cancel a Customer's Subscription

Tracked Items

Add Item Quantity

Remove Item Quantity

Set Item Quantity

Invoice Interactions

Add a Custom Charge/Credit

Delete a Custom Charge/Credit

Create a One-Time Invoice

Run an Outstanding Invoice

Issue a Refund

Issue a Void

Issue a Void or Refund

Send or Resend an Invoice email

Promotions

Get all Promotions

Get a Single Promotions

Current vs. Outstanding Invoice

Response Codes

HTTP Status Codes

Error Messages

Fraud Protection, Rate Limiting

Webhooks, Reverse API, Callbacks