Guides

Products

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,

  1. A Regular product used for one-time purchases in a payment page.
  2. 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",
    "unitAmount": 10000,
    "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: unitAmount, currency, description, image, and clientProductId are accepted in the request but are not echoed in the create response (which returns the product envelope). Store them in your own system, or call Get a product to read the price back.

Amount fields: Set the price with unitAmount — a positive integer in minor units (cents). For example, with currency: "USD", unitAmount: 10000 = USD 100.00. The older amount field (a number in major units) is deprecated; it still works, but it is mutually exclusive with unitAmount, so send only one. In responses, each price carries both unitAmount (minor units) and the deprecated amountStr (the same value as a major-units string) — prefer unitAmount.

Note: For REGULAR products, a price (unitAmount, or the deprecated amount) and currency are required — omitting them returns a validation error, despite being marked optional in the API Reference. The minimum price of 100 minor units (e.g. USD 1.00) is enforced only when the product is used in a payment page, not at creation time.

REGULAR and SUBSCRIPTION products are both ACTIVE immediately after creation — there is no separate activation step. (A legacy POST /v2/products/{productId}/activate endpoint remains for backward compatibility but is a no-op for products that are already active, and is not part of the current API.)

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": "ACTIVE",
    "type": "SUBSCRIPTION",
    "id": "prd_234abc567",
    ...
  }
}

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",
                    "unitAmount": 10000,
                    "amountStr": "100",
                    "productId": "prd_123abc456"
                }
            ]
        }
		]

Edit a Product

To change a product's presentation details after creation, send a PATCH request with only the fields you want to update. See 📄 API Reference — Update a product.

Editable fields are displayName, description, image, and defaultPriceId. A product's type, its prices' amount/currency, status, and clientProductId are immutable after creation — to change pricing, create a new price and point defaultPriceId at it.

curl -X PATCH 'https://api.breeze.cash/v2/products/prd_123abc456' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "displayName": "Updated Product Name",
    "description": "Updated description",
    "defaultPriceId": "prc_234abc567"
  }'

A successful response returns the updated product:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "prd_123abc456",
    "displayName": "Updated Product Name",
    "description": "Updated description",
    "defaultPriceId": "prc_234abc567",
    "type": "REGULAR",
    "status": "ACTIVE",
    "merchantId": "mch_123abc456",
    "livemode": true,
    "createdAt": 1776108219235,
    "updatedAt": 1776201928374
  }
}

Note: At least one field must be provided — an empty body is rejected. When setting defaultPriceId, the price must belong to this product and must not be deleted.

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",
    "unitAmount": 1000,
    "type": "RECURRING",
    "billingCycleConfig": {
      "interval": "month",
      "frequency": 1
    }
  }'

A successful response should look like:

{
  "status": "SUCCEEDED",
  "data": {
    "currency": "USD",
    "unitAmount": 1000,
    "amountStr": "10",
    "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.


Updated 10 days ago

Did this page help you?