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


Did this page help you?