Subscriptions

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:

Plan

name

We'll name the plan 'monthly-799'

description

Helps you understand what the plan is.

amount

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

interval

day, week, month or year

interval_count

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

Subscription

plan

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

customer

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

starts_on

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

ends_on

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 https://api.paidlabs.com/v0/plans \
  -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 https://api.paidlabs.com/v0/plans \
  -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.