log into your cheddargetter account

my password is missing!?!?!

Enter your email address below and we'll send you instructions for creating a new password.

signup

The CheddarGetter API

The CheddarGetter API enables you to leverage the full power of CheddarGetter 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 CheddarGetter

The CheddarGetter API

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 convenient 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 CheddarGetter API. We've created a KB Article on the subject based on our own PHP wrapper. Check it out.

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.

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.

Java

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

Michiel from VideoView joined the party with this Maven project.

C#
ColdFusion

Will has posted his ColdFusion offering at RIAForge.

Support

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

API Knowledge Base

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

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

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

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

Response:

Example response: plans.xml
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 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.
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)

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

/customers/import/productCode/MY_PRODUCT_CODE
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.
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 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 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
Update a Customer Only

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

Subscriptions

Update a Subscription Only

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

Add Item Quantity

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 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
Remove Item Quantity

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 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
Set Item Quantity

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

Invoice Interactions

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

/customers/add-charge/productCode/MY_PRODUCT_CODE/code/MY_CUSTOMER_CODE
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
Delete a Custom Charge/Credit

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 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
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 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
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 Required Description
ccCardCode No 3-4 digits - The Card Verification Value (CCV).
remoteAddress No (see below) Client IP 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 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
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 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
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

/invoices/void-or-refund/productCode/MY_PRODUCT_CODE
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
Send 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 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

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 Promotion

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

Response Codes

HTTP Status Codes

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

  • 200 OKSuccess!
  • 400 Bad RequestThe request was invalid. An accompanying error message will explain why.
  • 404 Not FoundThe URI requested is invalid or the resource requested, such as a user, does not exist.
  • 412 Precondition FailedThe request contains POST data that is in an invalid format or required parameters are missing.
  • 422 Unprocessable EntityThe gateway doesn't like the payment data. In other words, the gateway failed to process the request.
  • 500 Internal Server ErrorSomething is broken. Please post in the support forum so the CheddarGetter team can investigate.
  • 502 Bad GatewayCommunication with the payment gateway failed. Try again later.

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: https://cheddargetter.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, 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