Customer Overview

When is a customer required?

Why Create a Customer?

Breeze enables merchants to sync their customers to us. With the customer endpoint, merchants can

• Save and retrieve customer's information
• Track customer historical payment
• Query the supported payment method category for a given customer

Creating a Customer

A customer can be created by directly sending a POST request to the Breeze API.

POST /v1/customers

To create a customer, Send a POST request to the Breeze API. See 📄 API Reference — Create a customer for the full schema.

• referenceId is a required field, and it should be the unique user identifier in your system
• email is an optional field
• signupAt is a required field, indicating when the customer signed up at your service. Passing this data to us helps with better risk management.
• supportedPaymentMethods is an optional and immutable field indicating which payment method categories this customer can use (e.g. FIAT, CRYPTO). Once set, this field cannot be updated. If unset, all payment methods are supported.

⚠️

email + referenceId are a composite key

Breeze identifies customers by the combination of referenceId and email. Both values must be consistent every time you reference the same customer — mixing them causes lookup failures.

Common mistakes to avoid:

• Passing the same referenceId with different emails across calls
• Passing the same email with different referenceId values across calls

Multiple accounts under the same email: If your users can have more than one account sharing an email address, do not pass email at all. Use referenceId only — passing different referenceId values under the same email will fail on Breeze's side. Contact your Breeze integration engineer if you are unsure which approach fits your user model.

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]",
    "firstName": "John",
    "middleName": "K",
    "lastName": "Doe",
    "dateOfBirth": "1990-01-01",
    "address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    },
    "phoneNumber": "+14155552671",
    "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]"
    ...
  }
}

Using /v1/payment_pages with an existing customer

When creating a payment page, supply with either the customer.id or customer.referenceId to link the payment page to a customer.

curl -X POST 'https://api.breeze.cash/v1/payment_pages' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "lineItems": [
      {
        "name": "$10 Game Bundle",
        "currency": "USD",
        "amount": 1000,
        "image": "https://storage.googleapis.com/breeze-sample-assets/icons/coin.png",
        "quantity": 1
      }
    ],
    "billingEmail": "[email protected]",
    "clientReferenceId": "order-001",
    "customer": {
      "referenceId": "<your-unique-user-id>"
    },
    "successReturnUrl": "https://your-domain.com/order-complete",
    "failReturnUrl": "https://your-domain.com/order-aborted"
  }'

A successful response will look like:

{
  "status": "SUCCEEDED",
  "data": {
    "id": "page_abc123xyz",
    "url": "https://pay.breeze.cash/page_abc123xyz/pcs_xxx",
    "customer": {
      "id": "cus_123abc456", // The customer ID generated by Breeze
      "referenceId": "<your-unique-user-id>",
      "email": "[email protected]"
    },
    "status": "UNPAID",
    ...
  }
}

Getting a Customer

To retrieve a customer's information, you can send a GET request with any of the following:

1. the customer_id
2. the referenceId as the query parameter
3. the email as the query parameter

With /v1/customers/customer_id

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

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

With /v1/customers?referenceId={referenceId}

curl -X GET 'https://api.breeze.cash/v1/customers?referenceId=ref_123456789' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \

With /v1/customers?email={email}

curl -X GET 'https://api.breeze.cash/v1/[email protected]' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \

Updating a Customer

Customer data can be updated by sending a POST request to Breeze APIs. See 📄 API Reference — Update a customer.

livemode=false in the URL targets the sandbox environment. Omit this parameter (or set it to true) when making requests in production.

These are the fields that we support updates for:

• Address
• Email
• Phone number

curl --location --request POST 'https://api.breeze.cash/v1/customers/cus_172e1e324a25e95a?livemode=false' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "email": "<updated value>",
    "address": {
      "line1": "<updated value>",
      "line2": "<updated value>",
      "city": "<updated value>",
      "state": "<updated value>",
      "postalCode": "<updated value>",
      "country": "<updated value>"
    },
		"phoneNumber": "<updated value>"
  }'

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]",
    "address": {
    ...
  }
}

Offboard Customer Payment Method

If a customer is considered risky, they can be offboarded from certain payment methods. See 📄 API Reference — Offboard customer.

How enabledPaymentMethods works: This field is a whitelist — pass the method you want the customer to keep. For example, passing ["CRYPTO"] removes FIAT access and leaves the customer with crypto only. Calls are cumulative: if you subsequently call with ["FIAT"], it filters against the already-reduced set ([CRYPTO]), leaving the customer with no enabled methods at all. This cannot be reversed via the API — contact the Breeze team to restore a customer's payment methods.

curl --location --request POST 'https://api.breeze.cash/v1/customers/cus_172e1e324a25e95a/offboard?livemode=false' \
  -u "YOUR_API_KEY:" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "enabledPaymentMethods": ["CRYPTO"],
    "enabledPayoutMethods": ["CRYPTO"]
  }'

A successful response will look like

{
    "status": "SUCCEEDED",
    "data": {
        "id": "cus_d4c18927369cf9e3"
    }
}

The response confirms the customer ID. To verify which payment methods are currently enabled, retrieve the customer via GET /v1/customers/:id.

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