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 NameDescriptionTypeRequired
customerThe customer identifier.StringRequired
price_planThe price_plan identifier.StringRequired
price_plan_tagThe tag to identify the price_plan version. Defaults to null (i.e., latest version will be used).StringOptional
effective_atWhen the subscription is to be effective as of. Defaults to null (i.e., immediately effective).DatetimeOptional
discount_overrideOverrides the discount object on the price plan, or creates a new one if one doesn't exist.[Discount]Optional
align_to_calendarWhether the subscription's billing cycles should be aligned to the calendarBooleanOptional

See the Subscriptions API for more details