Guides
Start typing to search…

Customer Overview

Why create a customer?

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

  • save and retrieve customer information
  • track customer historical payment
  • query the supported payment method category for a given customer
  • ... (more features to come)

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:

  • referenceId is a required field, and it should be the unique user identifier in your system
  • email is a required 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.
  • supportedPaymentMethodsis an optional and immutable field, indicating the payment methods this customer can use. Once set, this field cannot be updated.
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
    "supportedPaymentMethods": ["FIAT"]
  }'

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]",
    "supportedPaymentMethods": ["FIAT"],
    ...
  }
}

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 '{
    "products": [
      {
        "name": "$10 Game Bundle",
        "currency": "USD",
        "amount": 1000,
        "images": ["https://storage.googleapis.com/breeze-sample-assets/icons/coin.png"],
        "quantity": 1
      }
    ],
    "billingEmail": "[email protected]",
    "clientReferenceId": "order-<your-unique-id>",
    "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 information, you can send a GET request with

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

With /v1/customer/customer_id

The supportedPaymentMethods field indicates the supported payment method categories for this customer, e.g. FIAT means that only fiat related payment methods are supported for this customer. supportedPaymentMethodsis an optional field and if it is unset it means all payment methods are supported.

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]",
    "supportedPaymentMethods": ["FIAT"],
    ...
  }
}

With /v1/customer?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/customer?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.

These are the fields that we support updates for:

  • Address
curl --location --request POST 'https://api.breeze.cash/v1/customers/cus_172e1e324a25e95a?livemode=false' \
--header 'Authorization: Basic <your token>' \
--header 'x-beamo-merchant: <your merchant id>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "address": {
    "line1": "<updated value>",
    "line2": "<updated value>",
    "city": "<updated value>",
    "state": "<updated value>",
    "postalCode": "<updated value>",
    "country": "<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": {
    ...
  }
}

Updated 16 days ago