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.
To successfully complete the tutorial, you need to do the following:
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.
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.
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{
"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
}
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).
curl https://api.paidlabs.com/v0/plans \
-u {YOUR API KEY}: \
-d customer=cus_DLjf9aDKE9ueDncz \
-d plan=pl_skBQYX4jmEE6VsTcRNkPg{
"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
}
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.
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.