Examples

Creating a Tiered SaaS Subscription with Payment.

Spectabill is in testing
We’re currently rolling out Spectabill in test mode and preparing for production soon. Stay tuned for updates.Schedule Demo to see it in action.

Let's gear up, great people! We are going to set up a monthly SaaS product, register a new customer, create their subscription, and initiate a payment checkout session—ideal for software companies offering monthly subscription plans with immediate payment collection.

You'll need to obtain your client secret and ID from the dashboard.

Step 1: Get Your Access Token

Request:

  curl --request POST \
    --url https://api.spectabill.com/spectabill-auth/realms/sandbox/protocol/openid-connect/token  \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data grant_type=client_credentials \
    --data client_id=<client_id> \
    --data client_secret=<client_secret>

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJUc1U0ZUMtU19BQURSVXRXRl9YLVZlU0xMMDNJRzBMaEtvZXhqUjFuQzNNIn0...",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI4MmRjYmY2Ni04MzY4LTQzNDQtYTJiNC0yODk1NDBhNmRhNGMifQ...",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "99e050ac-0cc6-40a5-9dbb-dfe19657addb",
  "scope": "email profile"
}

Step 2: Create a Product

Request:

curl --location 'https://api.spectabill.com/v1/api/billing/products' \
--header 'Content-Type: application/json' \
--header 'x-kc-token: eyJhbGciOiJSUz ...' \
--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
                    }
                ]
            }
        ]
    }
}'

Response:

{
  "data": {
    "id": "48ee7ff6-dc73-48b5-9775-76a43e9dbf06",
    "date_created": "2025-03-06T05:39:16.124Z",
    "name": "Awesome Saas1",
    "description": "This is first product for Awesome SaaS",
    "status": "draft",
    "user_updated": null,
    "date_updated": null,
    "user_created": "caa870ba-2752-4e64-92e5-18dc7122afda",
    "prices": null,
    "image": null,
    "subscription_blueprint": "1e255f39-f124-4c1c-a111-19e9371f5e17",
    "selected_currencies": ["1"],
    "features": []
  }
}

Step 3: Register a Customer

Request:

curl --location 'https://api.spectabill.com/v1/api/billing/customers' \
--header 'Content-Type: application/json' \
--header 'x-kc-token: eyJhbGciOiJSUzI1N ...' \
--header 'x-idempotency-id: 3478279-762234-6365' \
--data-raw '{
    "identifier":"$seth",
    "first_name":"Stephen",
    "last_name":"Seth",
    "email":"stephen.seth@mailinator.com"
}'

Response:

{
  "data": {
    "id": "ee509335-8b43-4d59-ad02-95f5b1fbd51e",
    "status": "active",
    "user_created": "caa870ba-2752-4e64-92e5-18dc7122afda",
    "date_updated": null,
    "user_updated": null,
    "date_created": "2025-03-06T05:42:53.525Z",
    "first_name": "Stephen",
    "last_name": "Seth",
    "address_line_1": null,
    "address_line_2": null,
    "email": "stephen.seth@mailinator.com",
    "identifier": "$seth",
    "phone": null
  }
}

Step 4: Create a Subscription

Request:

curl --location 'https://api.spectabill.com/v1/api/billing/subscriptions' \
--header 'Content-Type: application/json' \
--header 'x-kc-token: eyJhbGciOiJSUzI1 ...' \
--header 'x-idempotency-id: 0c15353d-5bce-4115-8043-9f867665cae6' \
--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

}'

Response:

{
  "data": {
    "id": "347aaf81-40bf-4ff3-9902-0ea5d40b4f21",
    "user_created": "caa870ba-2752-4e64-92e5-18dc7122afda",
    "date_created": "2025-03-06T05:46:12.576Z",
    "status": "active",
    "date_updated": null,
    "user_updated": null,
    "product": "48ee7ff6-dc73-48b5-9775-76a43e9dbf06",
    "customer": "ee509335-8b43-4d59-ad02-95f5b1fbd51e",
    "cycle_end_date": null,
    "cycle_start_date": null,
    "next_billing_date": null,
    "auto_renew": false,
    "discount_coupon": null,
    "trial_end_date": null,
    "selected_billing_cycle": "months-1",
    "selected_currency": "KES"
  }
}

Step 5: Initiate a Checkout Session

Request:

curl --location 'https://api.spectabill.com/v1/api/billing/checkout_sessions' \
--header 'Content-Type: application/json' \
--header 'x-idempotency-id: 39a7ecf0-f8fc-4e56-acb2-e05c09bc7255' \
--header 'x-kc-token: eyJhbGciOiJSUzI1N ...' \
--data '{
    "customer": "ee509335-8b43-4d59-ad02-95f5b1fbd51e",
    "product": "48ee7ff6-dc73-48b5-9775-76a43e9dbf06",
    "expires_at": "2025-03-06T08:55:45.000Z",
    "action": "new_subscription",
    "selected_currency": 1,
    "selected_billing_cycle": "months-1"
}'

Response:

{
  "data": {
    "id": "91e99e68-1482-4331-ade6-103367f9c4ac",
    "status": "open",
    "date_created": "2025-03-06T05:49:42.635Z",
    "user_updated": null,
    "date_updated": null,
    "user_created": "caa870ba-2752-4e64-92e5-18dc7122afda",
    "customer": "ee509335-8b43-4d59-ad02-95f5b1fbd51e",
    "product": "48ee7ff6-dc73-48b5-9775-76a43e9dbf06",
    "expires_at": "2025-03-06T08:55:45.000Z",
    "upgrade_to": null,
    "action": "new_subscription",
    "completed_at": null,
    "downgrade_to": null,
    "selected_billing_cycle": "months-1",
    "selected_currency": 1,
    "trial_end_date": null
  }
}
Explore the complete Billing API Reference.

Spectabill Checkouts

Evertything you need to know about checkouts on Spectabill

Idempotent Requests

Spectabill API supports idempotency for safely retrying requests without unintended side effects.