Using Subscriptions in Auction Studio

This guide will walk you through through setting up plans and subscriptions. In this example, we are an accounting service that invoices our customers for $799 monthly.

Before You Start

To successfully complete the tutorial, you need to do the following:

  • Sign up for a Auction Studio account and your Test Key will be loaded into the samples below. When you're ready to invoice and receive real money, remember to switch to your Live API key.
  • Edit your account to enable different payment methods. Fill out the appropriate fields to allow ACH, Wire, Credit Card and Check payments.
  • Complete our Getting Started Guide. It will help you through issuing your first invoice.

Select your preferred language for the tutorial:

Preface: Plans vs. Subscriptions

It's best to think about plans as you normally when looking at a pricing page for a service. They define the amount and frequency that amount is charged. A subscription is simply the connection of a plan to a specific customer. Subscriptions generate transactions for a specific customer for the amount and on the interval specified in the plan. Here are some of the relevant attributes of each:



We'll name the plan 'monthly-799'


Helps you understand what the plan is.


As always, amount is in cents, so this would be 79900


day, week, month or year


The number of intervals between each subscription billing. For example, interval=month and interval_count=3 bills every 3 months.



The Paid ID of the plan (i.e. pl_12345asdf).


The Paid ID of the customer (i.e. cus_12345asdf).


The date the subscription starts on (defaults to start immediately).


The date the subscription is to end.

Step 1: Create a Plan

First we will need to create a plan. In our fictional accounting business, let's say we charge customers $799 per month. Probably stating the obvious, that means we need a Auction Studio plan representing $799 on a monthly interval.

Create Plan

curl \
  -u  {YOUR API KEY}: \
  -d name=monthly-799 \
  -d 'description=Our premium plan for customers in 2015.' \
  -d amount=79900 \
  -d interval=month \
  -d interval_count=1

Create Plan Response

  "object": "plan", 
  "id": "pl_skBQYX4jmEE6VsTcRNkPg", 
  "created_at": 1425264804, 
  "description": "Our premium plan for customers in 2015.", 
  "name": "montly-799", 
  "interval": "month", 
  "interval_count": 1,
  "amount": 79900

Step 2: Subscribe a customer to the plan

Now that we have a plan, we can begin create subscriptions. Let's assume that we already have a customer with a Paid ID of cus_DLjf9aDKE9ueDncz. If you need help creating a customer, check out the Getting Started Guide.

We will use the simplest case of not setting starts_on or ends_on meaning the subscription will start immediately and run indefinitely (until cancelled).

Create Subscription

curl \
  -u  {YOUR API KEY}: \
  -d customer=cus_DLjf9aDKE9ueDncz \
  -d plan=pl_skBQYX4jmEE6VsTcRNkPg

Create Subscription Response

  "object": "subscription", 
  "id": "sub_iPmHnZbknJ5RYxQ2nMInw", 
  "created_at": 1425264818, 
  "starts_on": 1425970800, 
  "plan": {
    "object": "plan", 
    "id": "pl_skBQYX4jmEE6VsTcRNkPg", 
    "created_at": 1425264804, 
    "description": "Our premium plan for customers in 2015.", 
    "name": "montly-799", 
    "interval": "month", 
    "interval_count": 1,
    "amount": 79900
  "customer": "cus_DLjf9aDKE9ueDncz", 
  "started_at": 1426020560, 
  "ended_at": null,
  "cancelled_at": null

Step 3: That's it!

Actually, that's all you need to do. Pretty simple, right? The subscription will run exactly once when it is created and each interval thereafter until ends_on (if it is set) or it is cancelled.

Plans and Subscriptions are a simple yet powerful part of Auction Studio. You can think of Subscriptions like little workers that generate transactions. They offer you the ability to completely automate your billing.

Bonus: Using Subscriptions and Transactions

Since Subscriptions simply generate transactions, you can mix the two to create the penny-perfect solution. Think of a business that charges a platform fee each month and then charges for usage on top. In Auction Studio, you could create a subscription and then just create transactions as your normally would in the Getting Started Guide.

w00t! You are officially a pro at Subcriptions. See next how to detect deliquent customers and restrict access to your product.