NAV Navbar

API Reference

cUrl php ruby

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.

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:

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.

More information about webhooks