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.
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:
Python
Smartfile has taken over maintenance of Sharpy. Thanks, @theSeanOC for the original lib!
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.
C#
Johnny Arguelles of CollabCoders made his extension of John Siladie’s wrapper available on NuGet.
Take a look at Nathan Arnolds's fork of John Siladie's initial release.
ColdFusion
Will has posted his ColdFusion offering at RIAForge.
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 Cheddarpassword
: 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 |
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. |
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 |
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 |
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 tooutstanding
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 |
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 |
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.