CheddarGetter

Developers

The CheddarGetter API

The CheddarGetter API enables you to integrate the full power of CheddarGetter directly into your custom application. You can use our API with most any computer language to leverage the data stored by CheddarGetter.

[Back To Top]

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.

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

You're more than welcome to write some code from scratch that speaks HTTP and XML but there are some very convenient open source wrappers available for you to use. They make integrating quite easy. All you have to do is decide how you'd like things to work on your side.

While developing CheddarGetter, we made every attempt to make integrating with the CheddarGetter API as easy as possible. After all, we integrate applications with CheddarGetter all the time. One of the major conveniences we've introduced into the CheddarGetter API is the "custom code". All of the data items in CheddarGetter have a unique identifier that CheddarGetter uses internally to uniquely identify records but there's also this custom code. This is another unique identifier for your use for anything you like. The custom code is unique within your account and CheddarGetter makes sure of that.

You might be asking yourself, "How does this custom code make my life easier?" Well, that's pretty simple. The custom code eliminiates the need for you to maintain another unique identifier in your system just to integrate with CheddarGetter. You can use the custom code to store your own unique identifier for a data item. Usually this might just be for your customer record. So, when you create a customer record, you'd give your customer id to CheddarGetter. Then, whenever you want to get customer data from CheddarGetter, you can reference it with your own unique identifier. Neat, huh? We thought so, too.

There are lots of other custom codes in the system, too. For example, there's a custom code for each pricing plan. So, if you were to integrate your CheddarGetter account with an accounting package, you could use the identifier for a charge in your accounting package as the custom code for a charge in CheddarGetter.

[Back To Top]

Sample Integration Roadmap

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

[Back To Top]

Open Source Wrappers

The CheddarGetter 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 CheddarGetter 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. An appropriately named gem, "Mousetrap", from l4rk at Hashrocket. Follow @hashrocket.
PHP
The PHP CheddarGetter Client is a wrapper for the CheddarGetter API provided and supported by the CheddarGetter team. There's a nice Quick Start Guide. This ZF-compatible library is provided as an open source repository via GitHub here:
Spicer Matthews of Cloudmanic Labs has ported the stock PHP wrapper as a CodeIgniter library. Follow @Cloudmanic.
Dan Harper of Radweb Ltd added a FuelPHP port. Follow @danharper7 and @radweb.
LogSafe added a Symfony2 bundle built on the official PHP wrapper.
Python
In keeping with the tradition of cleverly named libraries, Sean O'Connor has produced Sharpy. This wrapper is on a simple BSD license and has 100% test coverage. Follow @theSeanOC. PyCheddar, a Django compatible library written by Jason and Luke at FeedMagnet. Follow @FeedMagnet.
Node.js
Kevin of Invisions Technical Arts has posted his Node.js offering on GitHub. Follow @respectTheCode.
Java
David of Rustici Software has posted his Java offering on GitHub. Michiel from VideoView joined the party with this Maven project.
C#
John at Confer released his library for all those .Net devs out there. Follow Confer.
ColdFusion
Will has posted his ColdFusion offering at RIAForge.

[Back To Top]

Support

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

API FAQs

Visit the official CheddarGetter API FAQ available at http://support.cheddargetter.com/faqs/api-8. Most answers are found within this API documentation or within the CheddarGetter API FAQs.

Knowledge Base

We publish all known issues in our Knowledge Base because developers leveraging the CheddarGetter API best excercise the code and identify potential errors. If you have a problem please search the Knowledge Base http://support.cheddargetter.com to find 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 haven't found what you're looking for in the FAQs or the KB, start a new public discussion. If your question contains sensitive information, feel free to mark the discussion as private.

[Back To Top]

Authentication

Authentication is achieved via HTTP Basic Authentication.

  • username: Email address of an authorized user of CheddarGetter
  • 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.

[Back To Top]

Request/Response Format

Request

The standard URL format is:
  • https://cheddargetter.com/xml/<PATH>/productCode/<your_product_code>[/PARAMS]
For example:
  • https://cheddargetter.com/xml/customers/get/productCode/MY_PRODUCT_CODE
  • gets all customer data for the product with productCode=MY_PRODUCT_CODE
and
  • https://cheddargetter.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.

Plans Response Example

Customers Response Example

Error Response Example

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

[Back To Top]

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.

[Back To Top]

Get All Pricing Plans

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

Path
/plans/get/productCode/MY_PRODUCT_CODE
Response
Example response: plans.xml

[Back To Request Dictionary]

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

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

[Back To Request Dictionary]

Get All Customers

Get all customer data from the product with productCode=MY_PRODUCT_CODE

Path
/customers/get/productCode/MY_PRODUCT_CODE
POST Parameters (filter result)
Name Required Description
subscriptionStatus No "activeOnly" or "canceledOnly"
planCode[] No Your pricing plan code. This is an array and may be provided multiple times to filter by multiple plans.
createdAfterDate No YYYY-MM-DD
createdBeforeDate No YYYY-MM-DD
canceledAfterDate No YYYY-MM-DD
canceledBeforeDate No YYYY-MM-DD
transactedAfterDate No YYYY-MM-DD
transactedBeforeDate No YYYY-MM-DD
orderBy No "name" (default), "company", "plan", "billingDatetime" or "createdDatetime"
orderByDirection No "asc" (default) or "desc"
search No Text search customer name, company, email address and last four digits of credit card.
Notes
As in all date and time related operations, the timezone used is the timezone set for the authenticated user. Dates are inclusive. e.g. assuming timezone for the authenticated user is set to UTC, 2010-07-04 <= X <= 2010-08-04 is interpreted as 2010-07-04T00:00:00+00:00 <= X <= 2010-08-04T23:59:59+00:00.

[Back To Request Dictionary]

Get a Single Customer

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

Path
/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

[Back To Request Dictionary]

Create a New Customer

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

Path
/customers/new/productCode/MY_PRODUCT_CODE
POST Parameters
Name Required Description
code Yes Your code for this customer. Limited to 255 characters.
firstName Yes Limited to 40 characters
lastName Yes Limited to 40 characters
email Yes Valid email address
company No Limited to 60 characters
isVatExempt No 1 or 0
vatNumber No If the customer is geographically eligible to be taxed and is exempt, provide the exemption number if applicable. Limited to 32 characters
notes No Limited to 255 characters
firstContactDatetime No 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 No A valid URL referer. Limited to 255 characters. See the KB Article.
campaignTerm No The "term" or "keyword" phrase that lead a potential customer to your site. Google Adwords equivalent: "utm_term". See the KB Article.
campaignName No The name of the marketing campaign. Google Adwords equivalent: "utm_campaign". See the KB Article.
campaignSource No The source of the lead. Google Adwords equivalent: "utm_source". See the KB Article.
campaignMedium No The medium used to find your site. Google Adwords equivalent: "utm_medium". See the KB Article.
campaignContent No The content you wish to track. Google Adwords equivalent: "utm_content". See the KB Article.
metaData[<user-defined>] No See the KB article about customer metadata
subscription[planCode] Yes Your code for the subscribed pricing plan
subscription[couponCode] No Coupon code for the promotion you'd like to apply to the subscription
subscription[initialBillDate] No 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] No "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, no. If your preference is to require the cardCode, yes. Not required when method is paypal. 3-4 digits - The Card Verification Value (CCV).
subscription[ccFirstName] Conditional (see notes) Limited to 40 characters
subscription[ccLastName] Conditional (see notes) Limited to 40 characters
subscription[ccCompany] No Limited to 60 characters
subscription[ccCountry] No Limited to 60 characters. Many billing solutions require that the ISO 2 char codes are used.
subscription[ccAddress] No Limited to 60 characters
subscription[ccCity] No Limited to 40 characters
subscription[ccState] No Limited to 40 characters. 2 character state/province codes are suggested when country is US/Canada.
subscription[ccZip] No 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] No (see notes) Your code for this charge. Limited to 36 characters.
charges[<user-defined>][quantity] No (see notes) Positive integer quantity
charges[<user-defined>][eachAmount] No (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] No Description for this charge/credit
items[<user-defined>][itemCode] No (see notes) Your code for this tracked item. Limited to 36 characters.
items[<user-defined>][quantity] No (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 No (see below) Client IP address
Notes
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 CheddarGetter 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.

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.

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

[Back To Request Dictionary]

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 billing solution is compatible. Please contact support for more information about whether or not importing is possible in your situation.

Path
/customers/import/productCode/MY_PRODUCT_CODE
POST Parameters
Name Required Description
code Yes Your code for this customer. Limited to 255 characters.
gatewayToken Conditional The gateway reference code. Limited to 255 characters.
firstName Yes Limited to 40 characters
lastName Yes Limited to 40 characters
email Yes Valid email address
company No Limited to 60 characters
isVatExempt No 1 or 0
vatNumber No If the customer is geographically eligible to be taxed and is exempt, provide the exemption number if applicable. Limited to 32 characters
notes No Limited to 255 characters
firstContactDatetime No 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 No A valid URL referer. Limited to 255 characters. See the KB Article.
campaignTerm No The "term" or "keyword" phrase that lead a potential customer to your site. Google Adwords equivalent: "utm_term". See the KB Article.
campaignName No The name of the marketing campaign. Google Adwords equivalent: "utm_campaign". See the KB Article.
campaignSource No The source of the lead. Google Adwords equivalent: "utm_source". See the KB Article.
campaignMedium No The medium used to find your site. Google Adwords equivalent: "utm_medium". See the KB Article.
campaignContent No The content you wish to track. Google Adwords equivalent: "utm_content". See the KB Article.
metaData[<user-defined>] No See the KB article about customer metadata
subscription[planCode] Yes Your code for the subscribed pricing plan
subscription[couponCode] No Coupon code for the promotion you'd like to apply to the subscription
subscription[gatewayToken] Conditional Gateway reference code for this payment method
subscription[initialBillDate] Yes 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[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[ccExpiration] Conditional MM/YYYY - the expiration date for the credit/debit card. If you specify a subscription[gatewayToken], 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[ccCompany] No Limited to 60 characters
subscription[ccCountry] No Limited to 60 characters. Many billing solutions require that the ISO 2 char codes are used.
subscription[ccAddress] No Limited to 60 characters
subscription[ccCity] No Limited to 40 characters
subscription[ccState] No Limited to 40 characters. 2 character state/province codes are suggested when country is US/Canada.
subscription[ccZip] No Limited to 20 characters
charges[<user-defined>][chargeCode] No (see notes) Your code for this charge. Limited to 36 characters.
charges[<user-defined>][quantity] No (see notes) Positive integer quantity
charges[<user-defined>][eachAmount] No (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] No Description for this charge/credit
items[<user-defined>][itemCode] No (see notes) Your code for this tracked item. Limited to 36 characters.
items[<user-defined>][quantity] No (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.
Notes
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 required. The first transaction will occur on the initialBillDate.

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.

Checkout this article for more information about using the import functionality.

[Back To Request Dictionary]

Update a Customer and Subscription

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

Path
/customers/edit/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
POST Parameters
Name Required Description
firstName No Limited to 20 characters
lastName No Limited to 20 chaaracters
email No Valid email address
company No Limited to 60 characters
notes No Limited to 255 characters
isVatExempt No 1 or 0
vatNumber No If the customer lives in a VAT eligible country and is exempt, provide the exemption number. Limited to 32 characters
firstContactDatetime No 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 No A valid URL referer. Limited to 255 characters. See the KB Article.
campaignTerm No The "term" or "keyword" phrase that lead a potential customer to your site. Google Adwords equivalent: "utm_term". See the KB Article.
campaignName No The name of the marketing campaign. Google Adwords equivalent: "utm_campaign". See the KB Article.
campaignSource No The source of the lead. Google Adwords equivalent: "utm_source". See the KB Article.
campaignMedium No The medium used to find your site. Google Adwords equivalent: "utm_medium". See the KB Article.
campaignContent No The content you wish to track. Google Adwords equivalent: "utm_content". See the KB Article.
metaData[<user-defined>] No See the KB article about customer metadata
subscription[method] No "cc" (default) or "paypal"
subscription[planCode] No Your code for the subscribed pricing plan
subscription[couponCode] No Coupon code for the promotion you'd like to apply to the subscription
subscription[ccNumber] No (see notes) Numbers only -- a valid credit/debit card number
subscription[ccExpiration] No (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[ccFirstName] No (see notes) Limited to 20 characters
subscription[ccLastName] No (see notes) Limited to 20 characters
subscription[ccCompany] No Limited to 50 characters
subscription[ccCountry] No Limited to 60 characters. Many billing solutions require that the ISO 2 char codes are used.
subscription[ccAddress] No Limited to 60 characters
subscription[ccCity] No Limited to 40 characters
subscription[ccState] No Limited to 40 characters. 2 character state/province codes are suggested when country is US/Canada.
subscription[ccZip] Conditional. If plan is free, no. If your preference is to require the zip, yes. 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.
subscription[changeBillDate] No 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 No (see below) Client IP address
Notes
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 CheddarGetter 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.

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

[Back To Request Dictionary]

Update a Customer Only

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

Path
/customers/edit-customer/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
POST Parameters
Name Required Description
firstName No Limited to 20 characters
lastName No Limited to 20 chaaracters
email No Valid email address
company No Limited to 60 chaaracters
notes No Limited to 255 chaaracters
metaData[<user-defined>] No See the KB article about customer metadata
remoteAddress No (see below) Client IP address

[Back To Request Dictionary]

Update a Subscription Only

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

Path
/customers/edit-subscription/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
POST Parameters
Name Required Description
method No "cc" (default) or "paypal"
planCode No Your code for the subscribed pricing plan
couponCode No Coupon code for the promotion you'd like to apply to the subscription
ccNumber No (see notes) Numbers only -- a valid credit/debit card number
ccExpiration No (see notes) MM/YYYY - the expiration date for the credit card
ccCardCode No (see notes) 3-4 digits - The Card Verification Value (CCV).
ccFirstName No (see notes) Limited to 20 characters
ccLastName No (see notes) Limited to 20 characters
ccCompany No Limited to 50 characters
ccCountry No Limited to 60 characters. Many billing solutions require that the ISO 2 char codes are used.
ccAddress No Limited to 60 characters
ccCity No Limited to 40 characters
ccState No Limited to 40 characters. 2 character state/province codes are suggested when country is US/Canada.
ccZip No (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 No 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 No (see below) Client IP address
Notes
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 the plan is a paid plan, credit card information is only required if you have configured CheddarGetter 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.

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

[Back To Request Dictionary]

Delete a Customer

Delete an existing customer in the product with productCode=MY_PRODUCT_CODE

Path
/customers/delete/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
Notes
WARNING: This will delete the customer and all related data in CheddarGetter and will delete the customer data at the gateway if a gateway is configured.

[Back To Request Dictionary]

Delete All Customers

Delete all existing customers in the product with productCode=MY_PRODUCT_CODE

Path
/customers/delete-all/confirm/[current unix timestamp]/productCode/MY_PRODUCT_CODE
Notes
WARNING: This will delete all customers and all related data in CheddarGetter.
This method is disabled in production accounts.

[Back To Request Dictionary]

Cancel a Customer's Subscription

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

Path
/customers/cancel/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
Notes
The customer's current subscription will be canceled at the moment this call is made. If you would like to reactivate a customer's subscription, you may do so by updating the subscription with full credit card data.

[Back To Request Dictionary]

Add Item Quantity

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

Path
/customers/add-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE
POST Parameters
Name Required Description
quantity No 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 No (see below) Client IP address
Notes
quantity is only required if you wish to add more than one to the current usage amount.

[Back To Request Dictionary]

Remove Item Quantity

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

Path
/customers/remove-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE
POST Parameters
Name Required Description
quantity No The positive amount accurate to up to 4 decimal places (if other that 1.0000) that you wish to subtract from the current usage for this item.
remoteAddress No (see below) Client IP address
Notes
quantity is only required if you wish to subtract more than one from the current usage amount.

[Back To Request Dictionary]

Set Item Quantity

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

Path
/customers/set-item-quantity/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE/itemCode/MY_ITEM_CODE
POST Parameters
Name Required Description
quantity Yes The positive amount accurate to up to 4 decimal places (if other that 1.0000) that you wish to set the current usage to for this item. Can be zero.
invoicePeriod No The billing period - 'current' (the default) or 'outstanding'. See below.
remoteAddress No (see below) Client IP address

[Back To Request Dictionary]

Add a Custom Charge/Credit

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

Path
/customers/add-charge/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
POST Parameters
Name Required Description
chargeCode Yes Your code for this charge. Limited to 36 characters.
quantity Yes Positive integer quantity
eachAmount Yes 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 No Description for this charge/credit
invoicePeriod No The billing period - 'current' (the default) or 'outstanding'. See below.
remoteAddress No (see below) Client IP address

[Back To Request Dictionary]

Delete a Custom Charge/Credit

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

Path
/customers/delete-charge/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
POST Parameters
Name Required Description
chargeId Yes CheddarGetter's ID for the charge/credit
invoicePeriod No The billing period - 'current' (the default) or 'outstanding'. See below.
remoteAddress No (see below) Client IP address

[Back To Request Dictionary]

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

Path
/invoices/new/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
POST Parameters
Name Required Description
charges[<user-defined>][chargeCode] Yes Your code for this charge. Limited to 36 characters.
charges[<user-defined>][quantity] Yes Positive integer quantity
charges[<user-defined>][eachAmount] Yes 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] No Description for this charge/credit
remoteAddress No (see below) Client IP address
Notes
At least one charge is required. Multiple charges may be submitted.

[Back To Request Dictionary]

Run an Outstanding Invoice

Execute an outstanding invoice in the product with productCode=MY_PRODUCT_CODE

Path
/customers/run-outstanding/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
POST Parameters
Name Required Description
ccCardCode No 3-4 digits - The Card Verification Value (CCV).
remoteAddress No (see below) Client IP address
Notes
The customer must have an outstanding invoice. This method can be useful for manually retrying the transaction on an outstanding invoice. An invoice may be outstanding if all prior attempts to transact the invoice were unsucessful or if the invoice has not yet been attempted as with the Subscription Billable Event.

This method can be used to reactivate a canceled subscription. If the retry succeeds on a canceled subscription, the subscription is reactivated. You can also add credits to the invoice to offset charges, making the invoice amount <= 0. In this case, executing that outstanding invoice will succeed for a zero amount and reactivate the subscription.

[Back To Request Dictionary]

Issue a Refund

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

Path
/invoices/refund/productCode/MY_PRODUCT_CODE
POST Parameters
Name Required Description
number or id Yes Either CheddarGetter's ID for the invoice or the CheddarGetter-generated invoice number
amount Yes An amount less than or equal to the refundable amount. See notes.
remoteAddress No (see below) Client IP address
Notes
Many billing solutions allow for partial refunds. If your billing solution allows partial refunds, the amount may be less than the amount of the original transaction. If the transaction had been previously refunded and you wish to issue another refund, the amount must be less than or equal to the original amount minus any previously issued partial refund amounts.

Some billing solutions allow for refunds prior to transaction settlement. If your billing solution does not allow refunds prior to settlement, you must execute a void of the full transaction or wait until after settlement occurs to issue a refund.

[Back To Request Dictionary]

Issue a Void

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

Path
/invoices/void/productCode/MY_PRODUCT_CODE
POST Parameters
Name Required Description
number or id Yes Either CheddarGetter's ID for the invoice or the CheddarGetter-generated invoice number
remoteAddress No (see below) Client IP address
Notes
Many billing solutions allow for voids. If your billing solution allows voids, a void can only be executed prior to transaction settlement.

[Back To Request Dictionary]

Issue a Void or a Refund

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

Path
/invoices/void-or-refund/productCode/MY_PRODUCT_CODE
POST Parameters
Name Required Description
number or id Yes Either CheddarGetter's ID for the invoice or the CheddarGetter-generated invoice number
remoteAddress No (see below) Client IP address
Notes
Many billing solutions do not allow for voids. Voids are only possible for a short period of time after the transaction is executed. In short, determining whether to execute a void or a refund is a moving target. Fortunately, CheddarGetter has already figured that out. Using this call makes voids and refunds simple. A drawback of using this method is that partial refunds are not possible.

[Back To Request Dictionary]

Send an Invoice Email

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

Path
/invoices/send-email/productCode/MY_PRODUCT_CODE
POST Parameters
Name Required Description
number or id Yes Either CheddarGetter's ID for the invoice or the CheddarGetter-generated invoice number
remoteAddress No (see below) Client IP address
Notes
Email notifications must be enabled in your account. Check your settings here.

Emails are automatically sent but if you'd like to resend one, just use this method. The most recent relevant email will be sent for the invoice. For example, if the most recent transaction was declined, the decline email is sent. If that most recent transaction was approved, the payment receipt email is sent.

[Back To Request Dictionary]

Get All Promotions

Get all promotion data from the product with productCode=MY_PRODUCT_CODE

Path
/promotions/get/productCode/MY_PRODUCT_CODE

[Back To Request Dictionary]

Get a Single Promotion

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

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

[Back To Request Dictionary]

[Back To Top]

Current vs. Outstanding Invoice Period

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 CheddarGetter'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".

[Back To Top]

Response Codes

HTTP Status Codes

The CheddarGetter API returns appropriate HTTP status codes for every request.
200 OK: Success!
400 Bad Request: The request was invalid. An accompanying error message will explain why.
401 Not Authorized: Authentication credentials were missing or incorrect or you are not authorized to use the requested resource.
404 Not Found: The URI requested is invalid or the resource requested, such as a user, does not exists.
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 CheddarGetter team can investigate.
502 Bad Gateway: Communication with the payment gateway failed. Try again later.

[Back To Top]

Error Messages

When the CheddarGetter 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: http://cheddargetter.com/admin/activity/errors

More information about errors is available in this KB article

[Back To Top]

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.

[Back To Top]

Webhooks, Reverse API, Callbacks

Yup, CheddarGetter 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

[Back To Top]