Get started with plans & subscriptions

Subscriptions are the best way to get recurring revenue from your customers. ProcessOut automatically handles the subscription lifecycles and does all the maths for you with upgrades, downgrades and coupons.


Payment modal

Before getting started, keep in mind that it’s also possible to use the payment modal ↗ to handle subscriptions. Create a subscription using the API, or a plan directly on your Dashboard, and use the subscription ID sub_* in the modal. The customer will be able to chose among your available payment options, and pay directly in the modal.

Create a plan

The first step to start using subscriptions on ProcessOut is to create a plan that your subscriptions will be based on. You can have as many plan as you want, and they’re a great way to track your sales related to your subscriptions in your dashboard. Plans could be the different servers a hosting company would sell for instance, or the different available thresholds for a SaaS service.

Let’s get you started by creating a plan on your Dashboard › Subscriptions › Plans › and create a new plan. You can assign the interval for your plan, which will be the number of days between each iteration of the subscription (such as 30 days for a monthly subscription), as well as a trial period if you want to offer your customers with a way to test your service. A plan is typically composed of a unique ID that you will define, a name, and an amount and currency.

It’s also possible to create a Plan using the API:

curl -X POST https://api.processout.com/plans \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8 \
    -d id="silver-plan" \
    -d name="Silver plan" \
    -d amount="10.00" \
    -d currency=USD \
    -d interval=1m
var ProcessOut = require("processout");
var client = new ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8");

client.newPlan().create({
    id:       "silver-plan",
    name:     "Silver plan",
    amount:   "10.00",
    interval: "1m"
}).then(function(plan) {
    //

}, function(err) {
    // An error occured

});
import processout
client = processout.ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

plan = client.new_plan().create({
    "id":       "silver-plan",
    "name":     "Silver plan",
    "amount":   "10.00",
    "currency": "USD",
    "interval": "1m"
})
require "processout"
client = ProcessOut::Client.new(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

plan = client.plan.create(
    id:       "silver-plan",
    name:     "Silver plan",
    amount:   "10.00",
    currency: "USD",
    interval: "1m"
)
<?php
$client = new \ProcessOut\ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8");

$plan = $client->newPlan()->create(array(
    "id"       => "silver-plan",
    "name"     => "Silver plan",
    "amount"   => "10.00",
    "currency" => "USD",
    "interval" => "1m"
));
import "gopkg.in/processout.v4"
client := processout.New(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

plan, err := client.NewPlan().Create(&processout.PlanCreateParameters{
    Plan: &processout.Plan{
        ID:       processout.String("silver-plan"),
        Name:     processout.String("Silver plan"),
        Amount:   processout.String("10.00"),
        Currency: processout.String("USD"),
        Interval: processout.String("1m"),
    },
})

Create a subscription for your customer

Once you have created the plans you want, let’s also create a customer object on ProcessOut for each of your internal customers. ProcessOut customers are used to link your customers with ProcessOut, and can be used to easily track your sales in your Dashboard. Let’s create a new Customer:

curl -X POST https://api.processout.com/customers \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8 \
    -d first_name=John \
    -d last_name=Smith
var ProcessOut = require("processout");
var client = new ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8");

client.newCustomer().create({
    first_name: "John",
    last_name:  "Smith"
}).then(function(customer) {
    //

}, function(err) {
    // An error occured

});
import processout
client = processout.ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

customer = client.new_customer().create({
    "first_name": "John",
    "last_name":  "Smith"
})
require "processout"
client = ProcessOut::Client.new(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

customer = client.customer.create(
    first_name: "John",
    last_name:  "Smith"
)
<?php
$client = new \ProcessOut\ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8");

$customer = $client->newCustomer()->create(array(
    "first_name": "John",
    "last_name":  "Smith"
));
import "gopkg.in/processout.v4"
client := processout.New(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

cust, err := client.NewCustomer().Create(&processout.CustomerCreateParameters{
    Customer: &processout.Customer{
        FirstName: processout.String("John"),
        LastName:  processout.String("Smith"),
    },
})

Please note that while we’re keeping the above example as simple as possible, it is possible to store a lot more information about your customer, which can be later searched on your dashboard ↗ as well. Find all the available customer attributes in the API references ↗.

Now that we have created a customer, you should store its ID in your application or database and link it to the customer for which you created it. We can now create a subscription for this customer from a plan you previously created. In this example, we’ll create a subscription using a dummy plan with an ID silver-plan. This ID can be anything you used when creating your plans.

curl -X POST https://api.processout.com/subscriptions \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8 \
    -d customer_id=cust_uYW5WVnjHe91qnsUA1sHOxEjdAySvg0P \
    -d plan_id="silver-plan" \
    -d source=card_Tpu6ZOCDu1tnDKp0kTnPOcVDMUbW7dTU
var ProcessOut = require("processout");
var client = new ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8");

// We can activate the subscription using a source, such as a card
// token previously generated using ProcessOut.js
client.newSubscription().create({
    customer_id: "cust_uYW5WVnjHe91qnsUA1sHOxEjdAySvg0P",
    plan_id:     "silver-plan",
    source:      "card_Tpu6ZOCDu1tnDKp0kTnPOcVDMUbW7dTU"
}).then(function(subscription) {
    // The customer was successfully subscribed to
    // the subscription

}, function(err) {
    // An error occured
});
import processout
client = processout.ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

# We can activate the subscription using a source, such as a card
# token previously generated using ProcessOut.js
subscription = client.new_subscription().create({
    "customer_id": "cust_uYW5WVnjHe91qnsUA1sHOxEjdAySvg0P",
    "plan_id":     "silver-plan",
    "source":      "card_Tpu6ZOCDu1tnDKp0kTnPOcVDMUbW7dTU"
})

# The customer is now successfully subscribed to the subscription
require "processout"
client = ProcessOut::Client.new(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

# We can activate the subscription using a source, such as a card
# token previously generated using ProcessOut.js
subscription = client.subscription.create(
    customer_id: "cust_uYW5WVnjHe91qnsUA1sHOxEjdAySvg0P",
    plan_id:     "silver-plan",
    source:      "card_Tpu6ZOCDu1tnDKp0kTnPOcVDMUbW7dTU"
)

# The customer is now successfully subscribed to the subscription
<?php
$client = new \ProcessOut\ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8");

// We can activate the subscription using a source, such as a card
// token previously generated using ProcessOut.js
$subscription = $client->newSubscription()->create(array(
    "customer_id" => "cust_uYW5WVnjHe91qnsUA1sHOxEjdAySvg0P",
    "plan_id"     => "silver-plan",
    "source"      => "card_Tpu6ZOCDu1tnDKp0kTnPOcVDMUbW7dTU"
));

// The customer is now successfully subscribed to the subscription
import "gopkg.in/processout.v4"
client := processout.New(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_jqSPvwq3AG5MlYAgqxlwwgOcAC3Zy7d8")

// We can activate the subscription using a source, such as a card
// token previously generated using ProcessOut.js
sub, err := client.NewSubscription().Create(&processout.SubscriptionCreateParameters{
    Subscription: &processout.Subscription{
        CustomerID: processout.String("cust_uYW5WVnjHe91qnsUA1sHOxEjdAySvg0P"),
        PlanID:     processout.String("silver-plan"),
    },
    Source: "card_Tpu6ZOCDu1tnDKp0kTnPOcVDMUbW7dTU",
})

// The customer is now successfully subscribed to the subscription

Staying up to date

Congrats! Your customer is now successfully subscribed to a subscription, and you will automatically be paid at each iteration of the subscription.

However, now that the subscription is fully set up you might want to handle events & webhooks ↗ so you know when a customer cancels its subscription, or when a payment goes through or fails to be paid. You might also be interested in: setting up trials ↗, upgrades & downgrades ↗, cancelling a subscription ↗, and discounts & coupons ↗.