1. How Does it Work?
   1. How Long Does This Take?
   2. What is a Developer product account?
2. Configuring your product in the Cheddar UI
   1. Grab some Cheddar codes
3. Making some calls
   1. Adding a new customer
      1. Fake credit card numbers for testing
   2. Sending usage data
   3. Updating a customer record
   4. Retrieving customer data for validation
   5. Error handling
   6. Simple Integration Complete
4. Full customization
5. Going live

1. How does it work?

Integrating with Cheddar via the API unlocks all the power of the Cheddar platform. With an API integration, you can send usage data to Cheddar in real-time from your application, allowing you to bill your customers with maximum flexibility. You can also customize billing frequency, change subscription and payment information, issue custom charges/credits, and just about anything else you can think of, without logging into the Cheddar UI.

Your application already knows when someone signs up, signs in, or uses one of your services. Sprinkle in a few API calls to Cheddar, and you've got all the power to fully customize your recurring billing --without your app needing to know anything about your pricing plan logic.

Here’s the basic idea:

• A new customer signs up to for your awesome product (yay!). Send a customers/new API call to Cheddar to create a record for them and subscribe them to a pricing plan.

• If you're billing for usage, send Cheddar updates when the customer uses an item or feature you're tracking with the customers/add-item-quantity call.

• At the end of the customer's billing period, Cheddar will compile the their subscription and usage information, determine how much to charge based on your pricing plan configuration, and generate an invoice.

• Cheddar will then transact the invoice with the payment processor you've selected and report the result.

• If the transaction is declined, Cheddar will automatically retry the transaction based on your dunning settings.

• If you have customer communications enabled, Cheddar will automatically send email notifications to customers when a payment is made or if their payment is declined.

• Rinse and repeat! Cheddar will bill the customer on the same recurring schedule until you modify the bill date or tell us that they've changed their subscription.

Ready to get started? This guide will show you all the basics of an API integration with Cheddar.

1.1 How long does this take?

It will take about a day to implement the simple integration outlined in this guide:

• Signing up customers

• Sending usage data

• Updating customer records and canceling customers

• Retrieving all of a customer's subscription information

1.2 What is a Developer product account?

To see Cheddar in action, sign up for a Developer product account here.

This is your development sandbox. All of Cheddar's features are available to play with, and all responses, transactions, and errors will be simulated. No need to enter any payment information when signing up for a dev account --you only pay when you're ready to process live transactions.

2. Configuring your product in the Cheddar UI

There are a few things you'll need to configure in the Cheddar UI before you can start sending or retrieving data via the API.

If you haven't already, make sure you've completed all the steps in the Quick Start Guide before you start building your integration:

1. Sign up for a developer account

2. Create a test product

3. Make a test pricing plan or two

4. Set up some tracked items to track and bill for usage (optional, but super useful for flexible billing!)

5. Set up a payment processor

Don’t worry about getting the details of your setup right the first time. You can always go back and change these settings later, or leave this account in dev mode and start fresh with a new product when you’re ready to go live.

2.1 Grab some Cheddar codes

When your app updates Cheddar about activity in your platform via the API, it'll provide special data fields called codes in the URL. These codes identify customers, pricing plans, and just about everything else in Cheddar, specifying what records to update and what changes to make.

To follow along with this guide, log into your Dashboard and grab:

• The product code for your test account

• Your pricing plan codes

• The codes of any tracked items you'd like to use

You'll also need your Cheddar username (the email associated with your Cheddar user account) and your API key.

3. Making some calls

You've got a Developer account with some test plans and all the necessary Cheddar codes. Now let's add some test customers and see how it works!

We'll be using cURL for all these examples, but there are some open-source wrappers available in several different languages here. These wrappers are developed and maintained by our customers, and they contain all the basic building blocks of an integration with Cheddar. We can't promise they contain all of Cheddar's latest features --that's up to the maintainers-- but they're a great place to start! :)

TLS

To comply with current PCI standards, Cheddar only supports connections using TLS 1.2 or higher. As those standards change, so will our requirements. We’ll let you know if that happens, though!

3.1 Adding a new customer:

Use this call to tell Cheddar that a new customer has signed up for your product. Cheddar will create a record for them in your Cheddar product account and pass their payment information along to your gateway provider.

curl -u MY_CHEDDAR_USERNAME:MY_API_KEY\
 -H 'Content-Type: application/json'\
 -d '{"code":"MILTON_WADDAMS",
"firstName":"Milton",
"lastName":"Waddams",
"email":"milt@initech.com",
"subscription" : {
  "planCode":"PREMIUM",
  "ccFirstName":"Milton",
  "ccLastName":"Waddams",
  "ccNumber":"4111111111111111",
  "ccExpiration":"10/2020",
  "ccCardCode":"123"}
}'\
 -X POST https://getcheddar.com/xml/customers/new/productCode/MY_PRODUCT_CODE

If the planCode corresponds to a plan that bills on signup, then Cheddar will also run the transaction at your gateway.

To create a customer on a free plan, you don't need their payment information:

curl -u MY_CHEDDAR_USERNAME:MY_API_KEY\
 -H 'Content-Type: application/json'\
 -d '{"code":"BILL_LUMBERG",
"firstName":"Bill",
"lastName":"Lumberg",
"email":"bill@initech.com",
"subscription" :
{ "planCode" : "FREE" }}'\
 -X POST https://getcheddar.com/xml/customers/new/productCode/MY_PRODUCT_CODE

The full documentation on creating customers via the API is here.

3.1.1 Fake credit card numbers for testing

Since everything in a Dev product is simulated, you may use any credit card number for development purposes in Cheddar. Really, you can use any number as long as it starts with a few numbers that fit the scheme for the different card types and it passes the Luhn Algorithm format test. Below is a list of some examples that we like to use:

• 370000000000002 American Express
• 6011000000000012 Discover
• 5424000000000015 MasterCard
• 4111111111111111 Visa <===== Our favorite! It's so easy to remember.

You could also get a large set of numbers from here.

When passing a CVV number you may pass any number you choose. These numbers are only evaluated for format and requirement when your product account is in dev mode.

3.2 Sending usage data

Your app already knows when someone uses one of your items or services. All you have to do now is add a customers/add-item-quantity call that tells Cheddar every time that happens, and you’ve got an incredibly flexible tool for tracking, billing, or a little bit of both.

When you configure a tracked item in your Cheddar dashboard, you’re setting up a counter that your app increments throughout the billing period. At billing time, Cheddar will take the total value of that counter at that time, apply whatever rules you have configured for that item on your customer’s pricing plan, and then generate and transact your customers’ invoice.

Your app doesn't have to know how much you charge for your items, or even what plan your customer is on. All you need is your product code, your customer’s code, and the item code. So even if the pricing rules for that item change, the call will stay the same.

For example, this call increments Milton's usage data for the item with code MY_ITEM_CODE:

curl -u MY_CHEDDAR_USERNAME:MY_API_KEY\
 -X POST https://getcheddar.com/xml/customers/add-item-quantity/productCode/MY_PRODUCT_CODE/code/MILTON_WADDAMS/itemCode/MY_ITEM_CODE

You can learn all about tracked items in our pricing plan basics knowledge base article.

3.3 Updating a customer record

Send updates about your customer's subscription or billing information anytime during the billing period using the customers/edit call. Use this call when a customer wants to change their credit card number, update their contact information, or change pricing plans.

For example, let's say Bill decided to upgrade his subscription from the FREE plan to the PREMIUM plan. This is the call we'd use to pass along his payment information and change his subscription:

curl -u MY_CHEDDAR_USERNAME:MY_API_KEY\
 -H 'Content-Type: application/json'\
 -d '{
"subscription" : {
  "planCode":"PREMIUM",
  "ccFirstName":"Bill",
  "ccLastName":"Lumberg",
  "ccNumber":"6011000000000012",
  "ccExpiration":"10/2023",
  "ccCardCode":"123"}
}'\
 -X POST https://getcheddar.com/xml/customers/edit/productCode/MY_PRODUCT_CODE/code/BILL_LUMBERG

To cancel his subscription entirely, use the customers/cancel call:

curl -u MY_CHEDDAR_USERNAME:MY_API_KEY\
 -X POST https://getcheddar.com/xml/customers/cancel/productCode/MY_PRODUCT_CODE/code/BILL_LUMBERG

Read more about how to update customers and their subscriptions in our API docs.

3.4 Retrieving customer data for validation

Use the customers/get API call to retrieve all the data Cheddar has stored about a customer. This includes their current plan, invoice history, and usage data. Here's how we would retrieve all the data Cheddar has on Milton:

curl -u MY_CHEDDAR_USERNAME:MY_API_KEY\
 -X POST https://getcheddar.com/xml/customers/get/productCode/MY_PRODUCT_CODE/code/MILTON_WADDAMS

You can use this as part of your validation process --when a customer signs in or accesses one of your services, your integration can parse the response to this call to make sure they have an active subscription, see what what plan they're on, or check what quantity of an item they've used.

See a complete response example here, and complete documentation about retrieving customer data here.

3.5 Error handling

Errors happen. We've got complete documentation on the errors you might see, as well as tips on building fault tolerance into your application, in our error handling guide.

Get status updates

Cheddar is up and running 99.9% of the time, but if we need to do some maintenance or something unexpected happens that affects our performance, we’ll be sure to let you know via our status page.

3.6 Simple Integration Complete

That's it! You now have the ability to:

• Sign up customers

• Send usage data to Cheddar

• Update customer subscription information

• Retrieve customer data

This should cover the basics for the most common pricing models. If this is all you need, great! You’re ready to take your account live and start billing your customers.

4. Full customization

We’ve touched the beginning of what Cheddar can do, but you can customize Cheddar as much as you need using our webhooks and API calls. For example:

• Want to integrate with other applications in your tech stack? Use Cheddar’s Zapier integration to route data from Cheddar to other platforms for accounting, customer management, and more.

• Need to issue one-time invoices? Charge a customer immediately with no auto-recursion using the invoices/new call

• Coupon codes for discounts? We've got promotions, too.

• Custom billing frequency? Change a customer's bill date using the subscription[changeBillDate] param in a customers/edit call.

See complete documentation of all our API calls here, as well as our guide on using our webhooks.

Have something specific you'd like to try, but aren't sure how to set it up? Get in touch with our support team here. We're happy to help!

5. Going live

When you've finished your testing and you're ready to start processing payments, visit this step of the Quick Setup to go live!

If you'd like to keep your Developer product around for testing, create a separate Cheddar product here, and upgrade one of them to start processing transactions. Just be sure your integration uses the codes from your live product when it's time to start processing payments, and you're good to go!

Questions? Our support team is here to help!