Breeze's Subscription product empowers merchants to offer seamless, recurring billing experiences—designed for both flexibility and automation. With a single integration, merchants can set up free trials, manage recurring charges, and respond to billing events without the overhead of building complex subscription infrastructure.

Breeze handles the entire subscription lifecycle—from customer creation and payment collection to webhook notifications. Once a customer is onboarded, our system automates recurring logic, sends proactive communication (like receipts and reminders), and provides real-time updates on subscription status changes.

As a Merchant of Record (MoR), Breeze handles compliance, risk, KYC (Know Your Customer), and tax collection—so your team doesn’t need to manage any of the operational or regulatory overhead.

How It Works

sequenceDiagram                                                                                                                                                                                                  
      participant M as Your Backend                                                                                                                                                                                
      participant B as Breeze
      actor C as Customer                                                                                                                                                                                          
   
      M->>B: POST /subscriptions                                                                                                                                                                                   
                  
      B-->>M: Payment Page URL                                                                                                                                                                                     
   
      M->>C: Redirect to Payment Page URL                                                                                                                                                                          
                  
      C->>B: Enter card details & submit                                                                                                                                                                           
   
      B->>M: POST webhook<br/>INVOICE_STATUS_UPDATED (PENDING)                                                                                                                                                     
                  
      B-->>C: Redirect to Success Return URL                                                                                                                                                                       
   
      B->>M: POST webhook<br/>INVOICE_STATUS_UPDATED (PAID)                                                                                                                                                        
                  
      B->>C: Email: Payment receipt                                                                                                                                                                                
                  
      B->>M: POST webhook<br/>SUBSCRIPTION_STATUS_UPDATED (ACTIVE)                                                                                                                                                 
   
      B->>C: Email: Subscription active                                                                                                                                                                            
                  
      loop Every billing cycle                                                                                                                                                                                     
          B->>B: Create new Invoice
                                                                                                                                                                                                                   
          B->>M: POST webhook<br/>INVOICE_STATUS_UPDATED (PENDING)                                                                                                                                                 
   
          B->>C: Email: Upcoming charge reminder (7 days before)                                                                                                                                                   
                  
          B->>B: Charge saved card                                                                                                                                                                                 
   
          B->>M: POST webhook<br/>INVOICE_STATUS_UPDATED (PAID)                                                                                                                                                    
      end 

Prerequisites

Before creating a subscription, complete the following steps if you haven't already:

1. Create a Customer

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

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "cus_123abc456",
    "referenceId": "<your-unique-user-id>",
    "email": "[email protected]"
  }
}

Save the data.id from this response (e.g. cus_123abc456) — you'll pass it as "customer": { "id": "cus_123abc456" } in the subscription creation request. See Customer Overview for full details.

2. Create a Subscription Product

curl -X POST 'https://api.breeze.cash/v2/products' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "displayName": "Monthly Plan",
    "type": "SUBSCRIPTION"
  }'

3. Add a Recurring Price to the Product

curl -X POST 'https://api.breeze.cash/v2/products/prd_abc123xyz/price' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "currency": "USD",
    "amount": 1000,
    "type": "RECURRING",
    "billingCycleConfig": {
      "interval": "month",
      "frequency": 1
    }
  }'

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "prc_345abc678",
    "type": "RECURRING",
    "currency": "USD",
    "amountStr": "1000",
    "productId": "prd_abc123xyz",
    "billingCycleConfig": {
      "interval": "month",
      "frequency": 1
    }
  }
}

Save the data.id from this response (e.g. prc_345abc678) — you'll pass it as "priceId": "prc_345abc678" in the subscription creation request. See Products for full details.

1. Create a Subscription Request

• Call Breeze’s subscription API with key parameters:
  • productId, priceId, and optional trial duration
  • customer.id
• Receive a url in the response—this is the hosted payment page where the customer can complete their first payment.

2. Redirect the User

• Send your customer to the provided checkout url.
• Breeze handles the initial payment and sends email confirmations and receipts.
• Once payment is successful, the subscription becomes ACTIVE.
  • (Optional) Billing cycle start:
    • For scheduled subscriptions, it begins at the scheduled start time.
    • If a free trial is configured, it begins after the trial ends.

3. Receive Webhooks

• Breeze sends webhook events to your backend to keep you in sync:
  • SUBSCRIPTION_STATUS_UPDATED
  • INVOICE_STATUS_UPDATED

Use these to update your internal system or notify users.

Key Takeaways:

• Breeze offers a hosted subscription flow: from free trials to recurring payments.
• Merchants integrate once and get webhook-driven updates on all key events.
• Subscription state transitions (e.g. active → grace_period → canceled) are managed and exposed via APIs and webhooks.
• No need to build your own billing engine, grace period enforcement, or retry logic.

Subscription Lifecycle – Main Flow

flowchart TD

    %% 主流程（纵向）
    START((Start)) -->|POST /subscriptions| INCOMPLETE
    INCOMPLETE -->|first payment success| ACTIVE
    ACTIVE -->|payment failed| GRACE_PERIOD
    GRACE_PERIOD -->|grace period expired| SUSPENDED

    %% 左侧：异常/失败路径
    INCOMPLETE -->|first invoice expired| INCOMPLETE_EXPIRED

    %% 恢复路径（右侧回流）
    GRACE_PERIOD -->|payment recovered| ACTIVE

    %% 取消路径（统一汇总）
    INCOMPLETE -->|canceled| CANCELED
    ACTIVE -->|canceled| CANCELED
    GRACE_PERIOD -->|canceled| CANCELED

    %% 统一结束
    SUSPENDED --> END((End))
    INCOMPLETE_EXPIRED --> END
    CANCELED --> END

Subscription Status Descriptions