Creating Subscriptions | Spectabill Docs

What is a Subscription?

In Spectabill, a subscription represents the billing relationship between a customer and one of your products. Subscriptions determine when and how a customer is billed based on the product's blueprint configuration.

Creating Your First Subscription

You can create subscriptions in Spectabill using either the user interface (UI) or the API.

Using the User Interface

Step 1: Access Subscription Management

Navigate to Billing → Subscriptions → + Create Subscription to begin creating a new subscription.

Step 2: Select Customer and Product

Choose an existing customer or create a new one
Select the product they'll be subscribing to

Creating a product

Creating and managing customers.

Step 3: Configure Subscription Settings

Define the subscription parameters:

Currency: Select from available currencies supported by the product
Billing Cycle: Choose between available cycles (e.g., monthly, yearly)
Trial Period: Set a trial end date if applicable
Auto-Renewal: Determine if the subscription will renew automatically

Configure Subscription Settings

The available billing cycles are determined by the product's subscription blueprint. You can only select from cycles that have been configured for the product.

Step 3: Configure Subscription Settings

Define the subscription parameters:

Currency: Select from available currencies supported by the product
Billing Cycle: Choose between available cycles (e.g., monthly, yearly)
Trial Period: Set a trial end date if applicable
Auto-Renewal: Determine if the subscription will renew automatically

Configure Subscription Settings

The available billing cycles are determined by the product's subscription blueprint. You can only select from cycles that have been configured for the product.

Step 4: Set Up Invoice Generation

Configure the invoice settings for the subscription:

Auto-create Invoice: Automatically generate invoices when payments are due
Auto-charge Customers: Automatically charge the customer's payment method when invoices are created
Email Invoices: Automatically send invoices to customers via email when generated

These settings determine how the billing process will be handled throughout the subscription lifecycle.

Using the API

The API mirrors the UI steps, allowing you to programmatically create the same subscription.

curl --location 'https://api.spectabill.com/v1/api/billing/subscriptions' \
--header 'Content-Type: application/json' \
--header 'x-kc-token: eyJhbGciOiJSUzI ...' \
--header 'x-idempotency-id: 26cce251-46c0-45ce-9cbb-b14120d40bf5' \
--data '{
    "customer":"ee509335-8b43-4d59-ad02-95f5b1fbd51e",
    "product":"48ee7ff6-dc73-48b5-9775-76a43e9dbf06",
    "selected_currency":"KES",
    "selected_billing_cycle":"months-1",
    "trial_end_date":null,
    "auto_renew":false

}'

Subscription Parameters: The API request body directly corresponds to UI settings:

- `"customer"`: The ID of the customer being subscribed
- `"product"`: The ID of the product being subscribed to
- `"selected_currency"`: The currency for billing (must be supported by the product)
- `"selected_billing_cycle"`: The billing interval, formatted as "{cycle}-{frequency}"
  - Example: "months-1" for monthly billing or "years-1" for yearly billing
  - This must match one of the billing cycles defined in the product's subscription blueprint
- `"trial_end_date"`: Optional date when trial period ends (null for no trial)
- `"auto_renew"`: Whether the subscription should automatically renew

Managing Existing Subscriptions

Please note that you can only change the status, trial end date, and auto-renewal settings of an existing subscription

Next Steps

Now that you understand how to create and manage subscriptions, learn how to process invoices and payments to complete your billing cycle.

See Full API reference for subscriptions here.

Managing Customers

Learn how to create, manage, and invoice customers in your Spectabill account.

Creating an Invoice

Learn how to create and manage invoices in your Spectabill account.

Creating a Subscription