Introduction

A product represents the item being sold to a customer. It should contain all the necessary information about what the customer is purchasing including the price and product details.

Breeze supports both one-time purchases (using REGULAR products) and recurring billing (using SUBSCRIPTION products). For a full guide on recurring billing, see Subscription Quick Start.

Create a Product

There are 2 types of products you can create,

A Regular product used for one-time purchases in a payment page.
A Subscription product used for making recurring purchases.

1a. Creating a Regular Product

Create a regular product by sending a request with the most basic parameters. See 📄 API Reference — Create a product.

curl -X POST 'https://api.breeze.cash/v2/products' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "displayName": "Example Regular Product",
    "description": "More details about this product",
    "image": "https://example.com/test.jpg",
    "clientProductId": "<(optional)your-unique-product-id>",
    "type": "REGULAR",
    "amount": 100,
    "currency": "USD"
  }'

A successful response should look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "prd_123abc456",
    "displayName": "Example Regular Product",
    "type": "REGULAR",
    "status": "ACTIVE",
    "merchantId": "mch_123abc456",
    "defaultPriceId": "prc_123abc456",
    "livemode": true,
    "createdAt": 1776108219235,
    "updatedAt": 1776108219236
  }
}

Note: amount, currency, description, image, and clientProductId are accepted in the request but are not returned in the response. Store these in your own system if you need to reference them later.

Note: For REGULAR products, amount and currency are required — omitting either returns a validation error, despite being marked as optional in the API Reference. Both string ("100") and numeric (100) formats are accepted at product creation, but numeric is recommended for consistency. The minimum amount of 100 (minor units) is enforced only when the product is used in a payment page, not at creation time.

REGULAR products are immediately ACTIVE after creation. SUBSCRIPTION products start as PENDING and require a separate activation step — see Activating a Subscription Product below.

1b. Creating a Subscription Product

Create a subscription product by sending a request with the most basic parameters.

curl -X POST 'https://api.breeze.cash/v2/products' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "displayName": "Example Subscription Product",
    "description": "More details about this product",
    "image": "https://example.com/test.jpg",
    "type": "SUBSCRIPTION",
    "clientProductId": "<your-unique-product-id>"
  }'

A successful response should look like:

{
  "status": "SUCCEEDED",
  "data": {
    "name": "Example Subscription Product",
    "description": "More details about this product",
    "image": "https://example.com/test.jpg",
    "clientProductId": "<your-unique-product-id>",
    "status": "PENDING",
    "type": "SUBSCRIPTION",
    "id": "prd_234abc567",
    ...
  }
}

1c. Activating a Subscription Product

After creating a SUBSCRIPTION product, it starts in PENDING status. You must activate it before it can be used in a subscription. Call the activate endpoint with the product ID from the creation response:

curl -X POST 'https://api.breeze.cash/v2/products/prd_234abc567/activate' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json'

A successful response will return the product with "status": "ACTIVE".

GET Products

Request

curl -X GET 'https://api.breeze.cash/v2/products' \
-u "YOUR_API_KEY:" \
--header 'Content-Type: application/json' \

Response

{
    "status": "SUCCEEDED",
    "data": [
        {
            "clientProductId": "testId",
            "_lock": {
                "locked": false
            },
            "image": "https://example.com/product.jpg",
            "type": "REGULAR",
            "livemode": false,
            "description": "test",
            "merchantId": "mch_123abc456",
            "status": "ACTIVE",
            "id": "prd_123abc456",
            "createdAt": 1767778980568,
            "displayName": "Test Display",
            "defaultPriceId": "prc_123abc456",
            "updatedAt": 1767778980604,
            "prices": [
                {
                    "type": "ONE_TIME",
                    "createdAt": 1767778980604,
                    "id": "prc_234abc567",
                    "currency": "USD",
                    "_lock": {
                        "locked": false
                    },
                    "livemode": false,
                    "status": "ACTIVE",
                    "amountStr": "10000",
                    "productId": "prd_123abc456"
                }
            ]
        }
		]

2. Creating a Subscription Product Price

Create a price for a subscription product. See 📄 API Reference — Create a product price.

curl -X POST 'https://api.breeze.cash/v2/products/prd_234abc567/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 should look like:

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

Note: The hour option for the interval field within billingCycleConfig is only supported in non-live mode environments (livemode = false) and cannot be used in live mode.

Creating a Payment Page with an existing Regular Product

With your product created, create a payment page for this product by passing a list of product IDs into the request.

curl -X POST 'https://api.breeze.cash/v1/payment_pages' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "lineItems": [
      {
        "product": "prd_123abc456",
        "quantity": 1
      }
    ],
    "billingEmail": "[email protected]",
    "clientReferenceId": "order-001",
    "successReturnUrl": "https://your-domain.com/order-complete",
    "failReturnUrl": "https://your-domain.com/order-aborted",
    "customer": {
      "referenceId": "<your-unique-user-id>"
    }
  }'

Continue reading here: https://docs.breeze.cash/docs/quick-start#/

Creating a Subscription with an existing Product

You can also create a subscription by passing the product and price into the request.

Note: A customer must exist before creating a subscription. See Customer Overview for details.

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": "cust_123xyz"
   }
 }'

Continue reading here: https://docs.breeze.cash/docs/quick-start-subscription#/

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