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.

Before Going Live 🚀

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

1. Product & Price Setup
   • Share your product and price configuration with the Breeze team for initial setup.
   • You may share with us about the information using this csv template
     • Sample given is for a monthly recurring plan
     • billing_cycle_frequency: day, week, month or year
   • Once we have set it up, we will return you the details in this format
     • this file will include the Breeze's product_id and price_id that you can use for creating a Subscription
   • Note: Self-serve product creation is coming soon!
2. Grace Period
   • Share your grace period configuration with Breeze
   • The default grace period is set to 60 days
3. Webhook Endpoint
   • Ensure your webhook server is ready to receive SUBSCRIPTION_STATUS_UPDATEDevents

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:

curl -X POST 'https://api.breeze.cash/merchant/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": { // this feature is COMING SOON!
     "duration": 7,
     "durationType": "day"
   },
   "customer": {
      "id": "cust_123xyz"
   }
 }'

• customer.id is the id you get when creating your Breeze customer in step 1
• 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(this feature is COMING SOON 🚀, let us know if you would like to be informed once this is live!)

A successful response will look like this:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "subs_abc123xyz",
    "url": "https://invoice.breeze.cash/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

Once the first payment succeeds, the subscription becomes ACTIVE. If a trial is set, billing resumes after the trial ends.

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"
}

🔧 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/merchant/v1/subscriptions/:id/cancel' \
 -u "YOUR_API_KEY:" \
 --header 'Content-Type: application/json'

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. (See How)
• Go Live: After thorough testing, switch to production credentials to process real-world subscription