Creating a Product

This guide walks you through creating and managing the services or offerings you want to charge your customers for.

Understanding Products

What is a Product?

In Spectabill, a product represents a specific service or offering that you provide to your customers. Products are the building blocks for subscriptions, and one-time purchases billing models.

Product Life Cycle

Products in Spectabill can exist in three distinct states:

• Draft: Products under development and not visible to customers
• Published: Products available for subscription or purchase
• Archived: Retired products no longer available for new customers

Creating Your First Product

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

Using the User Interface

Step 1: Access Product Management

Navigate to Billing → Products → New to begin creating your offering.

Step 2: Define Product Details

Complete the following essential information:

• Name: Choose a clear, descriptive name (appears on invoices)
• Description: Explain what the product provides
• Status: Set the initial state (e.g., draft).

Step 3: Customize Billing Specifications

Fine-tune how your product will be billed. In this step, you’ll configure:

• Billing Type: Choose between flat-rate (recurring subscription) or one-time.
• Currencies: Select the currencies your product supports (e.g., KES)
• Pricing and Billing Cycles:: Define the cost and recurrence interval (e.g., monthly or yearly billing).

Using the API

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

            curl --request POST \
              --url https://api.spectabill.com/v1/api/billing/products \
              --header 'Accept: application/json' \
              --header 'Content-Type: application/json' \
              --header 'x-idempotency-id: <randomuuid>' \
              --header 'x-kc-token: <access_token>' \
              --data '{
              "status": "draft",
              "name": "Awesome Saas1",
              "description": "This is first product for Awesome SaaS",
              "selected_currencies": [
                "1"
              ],
              "subscription_blueprint": {
                "billing_type": "flat-rate",
                "billing_cycles": [
                  {
                    "cycle": "months",
                    "frequency": 1,
                    "prices": [
                      {
                        "currency": 1,
                        "amount": 1
                      }
                    ]
                  },
                  {
                    "cycle": "years",
                    "frequency": 1,
                    "prices": [
                      {
                        "currency": 1,
                        "amount": 1
                      }
                    ]
                  }
                ]
              }
            }'

- `"billing_type": "flat-rate"`: Mirrors the UI choice of Flat-rate for a recurring subscription.
- `"billing_cycles"`: An array defining recurrence options, directly reflecting the UI's billing cycle settings:
  - Monthly Option:
    - `"cycle": "months"`: Unit of time.
    - `"frequency": 1`: Repeats every 1 month.
    - `"prices": [{"currency": 1, "amount": 1000}]`: KES 1000
  - Yearly Option:
    - `"cycle": "years"`: Unit of time (matches UI's "Yearly").
    - `"frequency": 1`: Repeats every 1 year.
    - `"prices": [{"currency": 1, "amount": 10000}]`: KES 10000.

Using the API for One-Time Products

The API also supports creating one-time products that don't involve subscriptions, perfect for single purchases, downloadable content, etc.

curl --request POST \
  --url https://api.spectabill.com/v1/api/billing/products \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-idempotency-id: <randomuuid>' \
  --header 'x-kc-token: <access_token>' \
  --data '{
  "status": "draft",
  "name": "Pro Design Package",
  "description": "Complete set of premium design templates and assets",
  "selected_currencies": [
    "1"
  ],
  "prices": [
    {
      "currency": 1,
      "amount": 1999
    }
  ]
}'

- For one-time products, pricing is defined directly in the root-level `"prices"` array
- The `"subscription_blueprint"` field is null since this is not a recurring product
- Each price object directly specifies:
  - `"currency": 1`: The currency ID (e.g., 1 for KES)
  - `"amount": 1999`: The product price (KES 1,999 in this example)
- No billing cycles are specified since payment occurs just once

Product Types

Spectabill supports various product types to accommodate different business models:

Subscription Products

Recurring products billed at regular intervals (monthly, quarterly, annually).

One-Time Products

Single-purchase items without a recurring component.

Product Naming Conventions

Effective product naming is crucial for clarity in your billing ecosystem:

• Use descriptive names that clearly indicate what the customer is purchasing
• Ensure names are concise but informative
• Avoid special characters that may cause display issues
• Maintain consistency across your product catalog
• Remember that product names appear on invoices and customer interfaces

// Examples of good product names
"Professional Plan - Monthly"
"Enterprise Storage Add-on"
"API Access - 1000 Requests"

Managing Existing Products

You can modify most product attributes after creation. However, changes to pricing and billing intervals require careful consideration as they may affect existing subscriptions.

Updating Product Status

Products in Spectabill can have one of the following statuses:

• Published – Active and available for new subscriptions.
• Archived – No longer available for new subscriptions but retains existing ones.
• Draft (default) – Unpublished and editable before going live.

You can update a product's status through the UI or API:

• On the UI – Navigate to the product and change the status.
• Via API – Use the Update Product endpoint to programmatically update the status.

Archiving Products

Rather than deleting products, Spectabill uses archiving to:

• Maintain billing history integrity
• Prevent new subscriptions while honoring existing ones
• Preserve data for reporting and analytics

Contact our support team if you need guidance on structuring your product catalog.