Breeze's Subscription product lets you offer recurring payments, free trials, and subscription entitlements with minimal integration. This guide will help you set up and test a subscription flow end-to-end—from creation to webhook handling.

Conceptually:

Scheduled Subscriptions are used when the subscription is set to begin at a future date, and the customer is not yet entitled to the service until that date.
Free Trials are used when the subscription is immediately started, granting the customer access to the service during the trial period, but no charges are made until the trial ends.

To bill introductory or stepped pricing before the standard price takes over, see Pricing Phases.

Before Going Live 🚀

You can start testing subscriptions in sandbox immediately — this checklist is for production launch readiness, not a prerequisite for sandbox.

Before launching your subscription flow in production, make sure the following is complete:

Product & Price Setup
- Create a Customer (If you haven't)
  - Call Breeze API to create a customer entry
- Create a Subscription Product and Assign a Price (If you haven't)
  - Call Breeze API to create a product entry
  - Call Breeze API to create a price entry
Grace Period
- Share your grace period configuration with Breeze
- The default grace period is set to 60 days
Webhook Endpoint
- Ensure your webhook server is ready to receive SUBSCRIPTION_STATUS_UPDATED events

Integration Flow

1. Create a Customer (If you haven't)

Send a POST request to the Breeze API with the most basic parameters. For quick testing, you can use a command-line tool like cURL:

curl -X POST 'https://api.breeze.cash/v1/customers' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "referenceId": "<your-unique-user-id>",
    "email": "[email protected]",
    "signupAt": 1710000000000 // 2024-03-08T12:00:00.000Z, UTC+0 timestamp in milliseconds
  }'

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "cus_123abc456", // The customer ID generated by Breeze
    "referenceId": "<your-unique-user-id>",
    "email": "[email protected]",
    "signupAt": 1710000000000,
    ...
  }
}

2. Create a Subscription Request

Send a POST request to Breeze’s subscription API with the required parameters. You can quickly test this using a command-line tool like curl. See 📄 API Reference — Create a subscription.

curl -X POST 'https://api.breeze.cash/v1/subscriptions' \
 -u "YOUR_API_KEY:" \
 --header 'Content-Type: application/json' \
 --data-raw '{
   "clientReferenceId": "your-unique-subscription-reference-id",
   "productId": "prd_abc123xyz",
   "priceId": "prc_abc123xyz",
   "customer": {
      "id": "cus_123xyz"
   },
   "successReturnUrl": "<optional:the-redirect-url-after-the-1st-payment-is-done>",
   "failReturnUrl": "<optional:the-redirect-url-if-there-is-failure-in-the-payment>"
 }'

curl -X POST 'https://api.breeze.cash/v1/subscriptions' \
 -u "YOUR_API_KEY:" \
 --header 'Content-Type: application/json' \
 --data-raw '{
   "clientReferenceId": "your-unique-subscription-reference-id",
   "productId": "prd_abc123xyz",
   "priceId": "prc_abc123xyz",
   "trial": { 
     "duration": 7,
     "durationType": "day"
   },
   "customer": {
      "id": "cus_123xyz"
   }
 }'

curl -X POST 'https://api.breeze.cash/v1/subscriptions' \
 -u "YOUR_API_KEY:" \
 --header 'Content-Type: application/json' \
 --data-raw '{
   "clientReferenceId": "your-unique-subscription-reference-id",
   "productId": "prd_abc123xyz",
   "priceId": "prc_abc123xyz",
   "startAt": 1759950506000,
   "customer": {
      "id": "cus_123xyz"
   }
 }'

curl -X POST 'https://api.breeze.cash/v1/subscriptions' \
 -u "YOUR_API_KEY:" \
 --header 'Content-Type: application/json' \
 --data-raw '{
   "clientReferenceId": "your-unique-subscription-reference-id",
   "productId": "prd_abc123xyz",
   "priceId": "prc_abc123xyz",
   "trial": { 
     "duration": 7,
     "durationType": "day"
   },
   "startAt": 1759950506000,
   "customer": {
      "id": "cus_123xyz"
   }
 }'

customer is a required field. customer.id is the id you get when creating your Breeze customer in step 1
productId and priceId must reference a SUBSCRIPTION product with a RECURRING price. REGULAR products and ONE_TIME prices are not supported for subscriptions.
clientReferenceId : this will be used as the idempotency id to make sure there is no duplicate creation of Subscription
trial.durationType: hour,day, week, month, or year
startAt: the UTC timestamp (in milliseconds) when billing is scheduled to begin. It must be at least 24 hours in the future.

Billing Behavior:

For free trial subscriptions:
- A $0 invoice is generated with a billing period matching the trial duration.
- The first real charge occurs after the trial ends.
For scheduled subscriptions:
- An invoice with identical start and end timestamps (startAt) is created to mark verification.
- Actual billing starts on the specified date.
For combined scheduled + trial subscriptions:
- Billing starts after the trial duration elapses following the scheduled start.

A successful response will look like this:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "subs_abc123xyz",
    "url": "https://api.breeze.cash/v1/invoices/client/invc_abc123xyz"
  }
}

data.id: Unique identifier for the subscription.
data.url: Hosted payment page for the customer to complete the first payment.

3. Redirect the User

After receiving the data.url, redirect your customer to the Breeze-hosted page. Breeze will:

Collect card details securely
Initiate the first payment (or start the trial if configured)
Send confirmation and receipts via email

4. Handle Webhooks

Breeze will notify your backend of changes via webhook events. Example webhook payload:

{
  "type": "SUBSCRIPTION_STATUS_UPDATED",
  "data": {
    "id": "subs_abc123xyz",
    "status": "ACTIVE",
    "clientReferenceId": "your-unique-subs-id",
    ...
  },
  "signature": "webhook_signature"
}

{
  "type": "INVOICE_STATUS_UPDATED",
  "data": {
    "id": "invc_abc123xyz",
    "status": "PAID",
		"subscriptionId": "subs_abc123xyz",
    "clientReferenceId": "your-unique-subs-id",
		"billingPeriod": {
      "start": 1758703144521, 
      "end": 1763887106025
		},
    ...
  },
  "signature": "webhook_signature"
}

🔧 Set up a POST endpoint (e.g., /webhook) to process these events and keep your system in sync.

5. Cancel Subscription


curl -X POST 'https://api.breeze.cash/v1/subscriptions/:id/cancel' \
 -u "YOUR_API_KEY:" \
 --header 'Content-Type: application/json'

6. Get Subscription

curl 'https://api.breeze.cash/v1/subscriptions/sub_abc123xyz' \
 -u "<YOUR_API_KEY>:" \
 --header 'Content-Type: application/json' \

curl 'https://api.breeze.cash/v1/subscriptions/?limit=5&offset=0' \
 -u "<YOUR_API_KEY>:" \
 --header 'Content-Type: application/json' \

Sample Response

{
    "status": "SUCCEEDED",
    "data": {
        "id": "subs_1b252358e0ed0b61",
        "clientReferenceId": "ref-id",
        "status": "CANCELED",
        "priceId": "prc_19092bf033b0292d",
        "productId": "prd_73062347e36944fe",
        "customerId": "cus_9147c9be8f25092c",
        "amountStr": "3.01",
        "currency": "USD",
        "billingCycleConfig": {
            "interval": "hour",
            "frequency": 1
        },
        "merchantId": "mch_cd239603802d7b4e",
        "livemode": false,
        "defaultPaymentMethodId": "card_a6a9ffd09d085ada",
        "defaultPaymentMethodType": "CARD",
        "billingCycleAnchor": 1761215553301,
        "canceledAt": 1761702869623,
        "lastSuccessfulPaymentId": "py_c686c5fa1f66de6e",
        "lastSuccessfulInvoiceId": "invc_404f2a7ed01d2232",
        "firstSuccessfulPaymentId": "py_cb8413d10f6ce144",
        "fallbackBillingEmail": "[email protected]"
    }
}

{
    "status": "SUCCEEDED",
    "data": [
        {
            "id": "subs_6e3e046369d0d475",
            "clientReferenceId": "ref-id",
            "status": "CANCELED",
            "priceId": "prc_19092bf033b0292d",
            "productId": "prd_73062347e36944fe",
            "customerId": "cus_9147c9be8f25092c",
            "amountStr": "3.01",
            "currency": "USD",
            "billingCycleConfig": {
                "interval": "hour",
                "frequency": 1
            },
            "merchantId": "mch_cd239603802d7b4e",
            "livemode": false,
            "defaultPaymentMethodId": "card_df86d6c567bebc67",
            "defaultPaymentMethodType": "CARD",
            "billingCycleAnchor": 1761222789969,
            "canceledAt": 1761222833269,
            "lastSuccessfulPaymentId": "py_1e76276486a61867",
            "lastSuccessfulInvoiceId": "invc_100d5770eea566b7",
            "firstSuccessfulPaymentId": "py_1e76276486a61867",
            "fallbackBillingEmail": "[email protected]"
        }
    ],
    "hasMore": true
}

📺 Demo Video

You may find the demo video here
For Sandbox test cards, you may use the cards here

Next Steps

Secure Your Webhook: Validate webhook signatures to ensure they come from Breeze.
Go Live: After thorough testing, switch to production credentials to process real-world subscription

Error codes — For a complete list of errors returned by the subscription endpoints, see the Error Reference.

Webhooks — For payload examples and event sequences fired during subscription billing (SUBSCRIPTION_STATUS_UPDATED, INVOICE_STATUS_UPDATED), see the Webhook Event Reference.

Quick Start (Subscription)