Breeze.cash Customers API

openapi: 3.2.0
info:
  title: Breeze Customers API
  version: 1.0.0
  description: Breeze payment processing API
  contact:
    email: support@breeze.cash
    url: https://docs.breeze.cash
servers:
- url: https://api.breeze.cash
  description: Breeze API
- url: https://secure.breeze.cash
  description: Breeze Direct Payment API (production)
- url: https://secure-sandbox.breeze.cash
  description: Breeze Direct Payment API (sandbox)
security:
- basicAuth: []
tags:
- name: Customers
paths:
  /v1/customers:
    post:
      operationId: createCustomer
      tags:
      - Customers
      summary: Create a customer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: The created customer
                properties:
                  status:
                    type: string
                    enum:
                    - SUCCEEDED
                  data:
                    $ref: '#/components/schemas/CreateCustomerResponse'
                required:
                - status
                - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Creates a new customer for the authenticated merchant.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
    get:
      operationId: getCustomerByQuery
      tags:
      - Customers
      summary: Get a customer by query
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: The matching customer
                properties:
                  status:
                    type: string
                    enum:
                    - SUCCEEDED
                  data:
                    $ref: '#/components/schemas/GetCustomerByQueryResponse'
                required:
                - status
                - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Retrieves a customer by reference ID or email.
      parameters:
      - name: referenceId
        in: query
        required: false
        schema:
          type: string
          maxLength: 255
      - name: email
        in: query
        required: false
        schema:
          type: string
          format: email
          maxLength: 255
  /v1/customers/{id}:
    get:
      operationId: getCustomerById
      tags:
      - Customers
      summary: Get a customer by ID
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: The customer
                properties:
                  status:
                    type: string
                    enum:
                    - SUCCEEDED
                  data:
                    $ref: '#/components/schemas/GetCustomerByIdResponse'
                required:
                - status
                - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Customer ID
    post:
      operationId: updateCustomer
      tags:
      - Customers
      summary: Update a customer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: The updated customer
                properties:
                  status:
                    type: string
                    enum:
                    - SUCCEEDED
                  data:
                    $ref: '#/components/schemas/UpdateCustomerResponse'
                required:
                - status
                - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Customer ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
  /v1/customers/{id}/offboard:
    post:
      operationId: offboardCustomer
      tags:
      - Customers
      summary: Offboard a customer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: The offboarded customer ID
                properties:
                  status:
                    type: string
                    enum:
                    - SUCCEEDED
                  data:
                    $ref: '#/components/schemas/OffboardCustomerResponse'
                required:
                - status
                - data
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      description: Restricts the payment and payout methods available to a customer.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Customer ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OffboardCustomerRequest'
components:
  schemas:
    GetCustomerByQueryResponse:
      $schema: http://json-schema.org/draft-07/schema#
      type: object
      properties:
        id:
          type: string
        referenceId:
          type: string
        email:
          type: string
        merchantId:
          type: string
        livemode:
          type: boolean
        signupAt:
          type: number
        supportedPaymentMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        supportedPayoutMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        firstName:
          type: string
        middleName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
        phoneNumber:
          type: string
        address:
          type: object
          properties:
            line1:
              type: string
            line2:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              type: string
        merchantTrustSignal:
          type: object
          properties:
            playerId:
              type: string
            trustStatus:
              type: string
              enum:
              - GOOD
              - BAD
            hoursPlayed:
              type: number
            playerLevel:
              type: number
          required:
          - playerId
      required:
      - id
      - referenceId
      - merchantId
      - livemode
      - signupAt
      definitions: {}
    OffboardCustomerResponse:
      type: object
      properties:
        id:
          type: string
          description: Customer ID
    OffboardCustomerRequest:
      description: Payment method restrictions
      type: object
      properties:
        enabledPaymentMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        enabledPayoutMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
      additionalProperties: false
    CreateCustomerResponse:
      $schema: http://json-schema.org/draft-07/schema#
      type: object
      properties:
        id:
          type: string
        referenceId:
          type: string
        email:
          type: string
        merchantId:
          type: string
        livemode:
          type: boolean
        signupAt:
          type: number
        supportedPaymentMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        supportedPayoutMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        firstName:
          type: string
        middleName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
        phoneNumber:
          type: string
        address:
          type: object
          properties:
            line1:
              type: string
            line2:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              type: string
        merchantTrustSignal:
          type: object
          properties:
            playerId:
              type: string
            trustStatus:
              type: string
              enum:
              - GOOD
              - BAD
            hoursPlayed:
              type: number
            playerLevel:
              type: number
          required:
          - playerId
      required:
      - id
      - referenceId
      - merchantId
      - livemode
      - signupAt
      definitions: {}
    UpdateCustomerRequest:
      description: 'Fields to update. Note two non-merge behaviors: (1) the name fields (`firstName`, `middleName`, `lastName`) are replaced as a group — if you send any one of them, the others you omit are cleared; (2) `address` is replaced wholesale, not deep-merged — omitted address sub-fields are cleared. Send the complete name set and full address you want to retain.'
      type: object
      properties:
        address:
          type: object
          properties:
            line1:
              type: string
              maxLength: 255
            line2:
              type: string
              maxLength: 255
            city:
              type: string
              maxLength: 100
            country:
              type: string
              maxLength: 2
            state:
              type: string
              maxLength: 100
            postalCode:
              type: string
              anyOf:
              - type: string
                pattern: ^\d{5}(-\d{4})?$
              - type: string
                maxLength: 100
          additionalProperties: false
        email:
          type: string
          format: email
          maxLength: 255
        phoneNumber:
          type: string
          maxLength: 20
        firstName:
          type: string
          maxLength: 100
        middleName:
          type: string
          maxLength: 100
        lastName:
          type: string
          maxLength: 100
        dateOfBirth:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          maxLength: 10
        supportedPaymentMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        merchantTrustSignal:
          type: object
          description: Gameplay-derived trust signal for the customer. Stored on the customer record and used in risk evaluation.
          properties:
            playerId:
              type: string
              description: Your identifier for the player this signal refers to.
              maxLength: 255
            hoursPlayed:
              type:
              - integer
              - 'null'
              description: Total hours the player has played. Non-negative integer. Send `null` to clear a previously stored value; omit to keep the stored value.
              minimum: 0
            playerLevel:
              type:
              - integer
              - 'null'
              description: The player's current level. Non-negative integer. Send `null` to clear a previously stored value; omit to keep the stored value.
              minimum: 0
            trustStatus:
              type:
              - string
              - 'null'
              description: Your trust verdict for the player. Send `null` to clear a previously stored status; omit to keep the stored value.
              enum:
              - GOOD
              - BAD
              - null
          required:
          - playerId
          additionalProperties: false
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - FAILED
        errorCode:
          type: string
        errorMessage:
          type: string
      required:
      - status
      - errorCode
      - errorMessage
    GetCustomerByIdResponse:
      $schema: http://json-schema.org/draft-07/schema#
      type: object
      properties:
        id:
          type: string
        referenceId:
          type: string
        email:
          type: string
        merchantId:
          type: string
        livemode:
          type: boolean
        signupAt:
          type: number
        supportedPaymentMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        supportedPayoutMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        firstName:
          type: string
        middleName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
        phoneNumber:
          type: string
        address:
          type: object
          properties:
            line1:
              type: string
            line2:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              type: string
        merchantTrustSignal:
          type: object
          properties:
            playerId:
              type: string
            trustStatus:
              type: string
              enum:
              - GOOD
              - BAD
            hoursPlayed:
              type: number
            playerLevel:
              type: number
          required:
          - playerId
      required:
      - id
      - referenceId
      - merchantId
      - livemode
      - signupAt
      definitions: {}
    CreateCustomerRequest:
      description: Customer details
      type: object
      properties:
        referenceId:
          type: string
          maxLength: 255
        email:
          type: string
          format: email
          maxLength: 255
        signupAt:
          type: integer
          minimum: 0
        firstName:
          type: string
          maxLength: 100
        middleName:
          type: string
          maxLength: 100
        lastName:
          type: string
          maxLength: 100
        dateOfBirth:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          maxLength: 10
        supportedPaymentMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        address:
          type: object
          properties:
            line1:
              type: string
              maxLength: 255
            line2:
              type: string
              maxLength: 255
            city:
              type: string
              maxLength: 100
            country:
              type: string
              maxLength: 2
            state:
              type: string
              maxLength: 100
            postalCode:
              type: string
              anyOf:
              - type: string
                pattern: ^\d{5}(-\d{4})?$
              - type: string
                maxLength: 100
          additionalProperties: false
        phoneNumber:
          type: string
          maxLength: 20
        merchantTrustSignal:
          type: object
          description: Gameplay-derived trust signal for the customer. Stored on the customer record and used in risk evaluation.
          properties:
            playerId:
              type: string
              description: Your identifier for the player this signal refers to.
              maxLength: 255
            hoursPlayed:
              type:
              - integer
              - 'null'
              description: Total hours the player has played. Non-negative integer. Send `null` to clear a previously stored value; omit to keep the stored value.
              minimum: 0
            playerLevel:
              type:
              - integer
              - 'null'
              description: The player's current level. Non-negative integer. Send `null` to clear a previously stored value; omit to keep the stored value.
              minimum: 0
            trustStatus:
              type:
              - string
              - 'null'
              description: Your trust verdict for the player. Send `null` to clear a previously stored status; omit to keep the stored value.
              enum:
              - GOOD
              - BAD
              - null
          required:
          - playerId
          additionalProperties: false
      required:
      - referenceId
      - signupAt
      additionalProperties: false
    UpdateCustomerResponse:
      $schema: http://json-schema.org/draft-07/schema#
      type: object
      properties:
        id:
          type: string
        referenceId:
          type: string
        email:
          type: string
        merchantId:
          type: string
        livemode:
          type: boolean
        signupAt:
          type: number
        supportedPaymentMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        supportedPayoutMethods:
          type: array
          items:
            type: string
            enum:
            - FIAT
            - CRYPTO
        firstName:
          type: string
        middleName:
          type: string
        lastName:
          type: string
        dateOfBirth:
          type: string
        phoneNumber:
          type: string
        address:
          type: object
          properties:
            line1:
              type: string
            line2:
              type: string
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              type: string
        merchantTrustSignal:
          type: object
          properties:
            playerId:
              type: string
            trustStatus:
              type: string
              enum:
              - GOOD
              - BAD
            hoursPlayed:
              type: number
            playerLevel:
              type: number
          required:
          - playerId
      required:
      - id
      - referenceId
      - merchantId
      - livemode
      - signupAt
      definitions: {}
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: API key as username, empty password
x-provenance:
  method: searched
  source: https://docs.breeze.com/reference
  harvested: '2026-10-28'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.breeze.com/reference/cancelofframprequest.md
  - https://docs.breeze.com/reference/cancelpayoutpage.md
  - https://docs.breeze.com/reference/cancelsubscription.md
  - https://docs.breeze.com/reference/createcustomer.md
  - https://docs.breeze.com/reference/creategatewaypayment.md
  - https://docs.breeze.com/reference/createheadlesspayout.md
  - https://docs.breeze.com/reference/createliquidationaddress.md
  - https://docs.breeze.com/reference/createofframprequest.md
  - https://docs.breeze.com/reference/createpaymentpage.md
  - https://docs.breeze.com/reference/createpayoutpage.md
  - https://docs.breeze.com/reference/createproduct.md
  - https://docs.breeze.com/reference/createproductprice.md
  - https://docs.breeze.com/reference/createsubscription.md
  - https://docs.breeze.com/reference/deletegatewaycustomerpaymentmethod.md
  - https://docs.breeze.com/reference/downloadstatement.md
  - https://docs.breeze.com/reference/expirepaymentpage.md
  - https://docs.breeze.com/reference/getallpaymentattempts.md
  - https://docs.breeze.com/reference/getcustomerbyid.md
  - https://docs.breeze.com/reference/getcustomerbyquery.md
  - https://docs.breeze.com/reference/getfraudreport.md
  - https://docs.breeze.com/reference/getgatewaypayment.md
  - https://docs.breeze.com/reference/getheadlesskycbycustomerreferenceid.md
  - https://docs.breeze.com/reference/getheadlesskycbyid.md
  - https://docs.breeze.com/reference/getinvoice.md
  - https://docs.breeze.com/reference/getliquidationaddress.md
  - https://docs.breeze.com/reference/getliquidationaddresstransaction.md
  - https://docs.breeze.com/reference/getmerchanttaxrate.md
  - https://docs.breeze.com/reference/getofframprequest.md
  - https://docs.breeze.com/reference/getpaymentpage.md
  - https://docs.breeze.com/reference/getpayoutpage.md
  - https://docs.breeze.com/reference/getpayoutpagehistory.md
  - https://docs.breeze.com/reference/getproduct.md
  - https://docs.breeze.com/reference/getrefund.md
  - https://docs.breeze.com/reference/getriskstatus.md
  - https://docs.breeze.com/reference/getsubscription.md
  - https://docs.breeze.com/reference/getsubscriptionbyclientreferenceid.md
  - https://docs.breeze.com/reference/initiateheadlesskyctier3.md
  - https://docs.breeze.com/reference/initiaterefund.md
  - https://docs.breeze.com/reference/listdisputes.md
  - https://docs.breeze.com/reference/listfraudreports.md
  - https://docs.breeze.com/reference/listgatewaycustomerpaymentmethods.md
  - https://docs.breeze.com/reference/listliquidationaddresses.md
  - https://docs.breeze.com/reference/listliquidationaddresstransactions.md
  - https://docs.breeze.com/reference/listpaymentpages.md
  - https://docs.breeze.com/reference/listproducts.md
  - https://docs.breeze.com/reference/liststatements.md
  - https://docs.breeze.com/reference/listsubscriptions.md
  - https://docs.breeze.com/reference/offboardcustomer.md
  - https://docs.breeze.com/reference/releaseofframprequest.md
  - https://docs.breeze.com/reference/releasepayoutpage.md
  - https://docs.breeze.com/reference/resumegatewaypaymentauthentication.md
  - https://docs.breeze.com/reference/sandboxconfirmpayoutpage.md
  - https://docs.breeze.com/reference/simulatesandboxdispute.md
  - https://docs.breeze.com/reference/submitheadlesskycproofofaddresswithupload.md
  - https://docs.breeze.com/reference/submitheadlesskycproofofaddresswithurl.md
  - https://docs.breeze.com/reference/submitheadlesskycwithimageupload.md
  - https://docs.breeze.com/reference/submitheadlesskycwithimageurl.md
  - https://docs.breeze.com/reference/updatecustomer.md
  merge:
    pages: 58
    deduped: 458
    conflicts_kept_first: 0