Subscriptions
Seamlessly create and enable subscriptions the moment a customer signs up.
General Usage: Programmatic
Subscribing customers to Price Plans
Subscriptions represent the assignment of customers to price plans. Subscriptions may be assigned at customer creation (by including the price plan) or added separately at a later time.
Calendar Billing Cycles
A subscription's billing cycles will align to the subscription start date by default. For example, a customer that is subscribed to a monthly price plan starting on January 15 will receive an invoice for Jan 15 - Feb 15, then Feb 15 - March 15 and so on. However you may want to align the cycles to the calendar: the first invoice should cover Jan 15 - Feb 1, then each subsequent cycle will begin at the start of the month and end at the start of the next month. This behavior is enabled by setting align_to_calendar
to true
when creating or updating a subscription.
Calendar billing cycles are supported for monthly, quarterly, and annual price plans.
Example
import octane
octane.api_key = "<YOUR_API_KEY>"
# Create subscription at customer creation time
octane.Customer.create(
name="customer_1",
# ...
# Subscribes a customer to this price plan - effective immediately
price_plan_name="price_plan_name"
)
# Create subscription after the customer already exists,
# overriding the discount to $10.
octane.Customer.create_subscription(
"customer_1",
price_plan_name="price_plan_name",
effective_at="2021-06-01T00:00:00",
discount_override={
"discount_type": "FLAT",
"amount": 10
}
)
import Octane from "octane-node";
const octane = new Octane("<YOUR_API_KEY>");
// Create subscription at customer creation time
octane.customers.create({
name: "customer_1",
// ...
// Subscribes a customer to this price plan - effective immediately
pricePlan: "price_plan_name",
))
.then(_ => {
// Create subscription after the customer already exists,
// overriding the discount to $10.
octane.customers.createSubscription("customer_1", {
pricePlanName: "price_plan_name",
effectiveAt: new Date("2021-06-01T00:00:00"),
discountOverride: {
discountType: "FLAT",
amount: 10
});
});
package main
import (
"time"
"github.com/getoctane/octane-go"
)
func main() {
client := octane.NewClient("<YOUR_API_KEY>")
createArgs := octane.CreateCustomerArgs{
Name: "customer_1",
// ...
// Subscribes a customer to this price plan - effective immediately
PricePlanName: "price_plan_name",
}
_, _, err := client.Customers.Create(createArgs)
if err != nil {
panic(err)
}
// Build a time.Time object from raw date string
effectiveAtStr := "2021-06-01T00:00:00"
effectiveAtObj, err := time.Parse("2006-01-02T15:04:05", effectiveAtStr)
if err != nil {
panic(err)
}
// Create subscription after the customer already exists,
// overriding the discount to $10.
subArgs := octane.CreateSubscriptionArgs{
PricePlanName: "price_plan_name",
EffectiveAt: effectiveAtObj,
DiscountOverride: &octane.DiscountInputArgs{
DiscountType: "FLAT",
Amount: 10,
},
}
_, _, err = client.Customers.CreateSubscription("customer_1", subArgs)
if err != nil {
panic(err)
}
}
Subscription Definition
UTC Timezone
All date and time inputs are assumed as UTC-formatted.
Field Name | Description | Type | Required |
---|---|---|---|
customer | The customer identifier. | String | Required |
price_plan | The price_plan identifier. | String | Required |
price_plan_tag | The tag to identify the price_plan version. Defaults to null (i.e., latest version will be used). | String | Optional |
effective_at | When the subscription is to be effective as of. Defaults to null (i.e., immediately effective). | Datetime | Optional |
discount_override | Overrides the discount object on the price plan, or creates a new one if one doesn't exist. | [Discount] | Optional |
align_to_calendar | Whether the subscription's billing cycles should be aligned to the calendar | Boolean | Optional |
See the Subscriptions API for more details
Updated about 1 year ago