Subscriptions

Using Subscriptions in Paid


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 Paid 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 Paid 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 Paid. 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 Paid, 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.