Find a customer

curl --request GET \
  --url "$BASE_URL/v1/customers/find?q=803606" \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "id": "3d8ec956-de2a-4d43-9c1e-74475b153362",
  "data": {
    "fullname": "Jane Doe",
    "phone": "+905551234567",
    "email": "jane@example.com"
  },
  "collectables": {
    "point_MMSR5": { "label": "Points", "value": 1000, "total": 2760 }
  },
  "consents": { "marketing": true },
  "barcode": "803606",
  "cards": [
    {
      "id": "41dd8263-288e-4b55-bf2e-6a82995a0441",
      "name": "Point Card",
      "barcode": "803606",
      "status": 1,
      "options": {
        "spend": {
          "pointstoconvert": 1,
          "convertto": 1,
          "collectwhilespending": false,
          "collectfromdiscountedamount": false,
          "ratio": 1
        }
      }
    }
  ],
  "opaqueId": null,
  "status": 1,
  "createdAt": "2026-04-21T12:19:19.037Z",
  "coupons": [
    {
      "id": "906550fd-dcf5-4aed-a80e-03e8939fc2b4",
      "coupon": { "name": "Free Coffee Coupon" },
      "code": "431825",
      "type": "product",
      "discountAmount": 100,
      "isPercent": true,
      "products": {
        "quantity": 1,
        "productIds": ["4221450", "4221453", "4221456"]
      },
      "issuedAt": "2026-04-21T12:19:19.037Z",
      "expiresAt": "2026-09-09T12:14:08.511Z",
      "status": "active"
    },
    {
      "id": "eb2373b1-8a01-41b7-a8f9-48d462ede4e0",
      "coupon": { "name": "10% Discount Coupon" },
      "code": "667500",
      "type": "discount",
      "discountAmount": 10,
      "isPercent": true,
      "maxDiscountAmount": 25,
      "issuedAt": "2026-04-27T12:14:20.513Z",
      "status": "active"
    }
  ]
}

{
  "statuscode": 400,
  "errorcode": 400,
  "message": "_customer_not_found",
  "description": "",
  "timestamp": 1754040000000,
  "path": "/v1/customers/find?q=803606",
  "method": "GET"
}

GET /v1/customers/find resolves a customer of your organization using a single search term. Use it to identify the customer who is checking out, and to load their cards and coupons before running a transaction.

GET $BASE_URL/v1/customers/find?q=<term>

The q term is matched in three ways:

Phone

Case-insensitive substring match on data.phone.

Exact match on data.email.

Barcode

Exact match. Only attempted when q is purely numeric.

The first matching customer is returned, with loyalty balances (collectables), wallet cards (cards), and active coupons (coupons).

Request headers

string

required

Your active Bearer token: Bearer <accessToken>.

Query parameters

string

required

Search term: phone, email, or card barcode.

Response fields (200 OK)

string

Unique identifier of the customer. Use it on the coupon and transaction endpoints.

object

Customer profile fields (fullname, phone, email, …). The set of keys depends on the organization’s customer form configuration.

object

Loyalty balances, keyed by collectable key.

Show collectable entry fields

string

Optional human-readable label.

number

Current spendable balance.

number

Lifetime collected total.

array

The customer’s wallet cards. A single entry for a barcode search; possibly several for email/phone.

Show card fields

string

Customerpass id. Send it as card on other endpoints.

string

Card name.

string

Card barcode.

number

Status code of the card.

object

Campaign configuration of the card. Present only when the card has a point campaign; omitted otherwise.

Show options fields

object

Point-spend configuration of the card’s point campaign. For tiered point campaigns the values reflect the customer’s current tier.

Show spend fields

number

Money value of a single point, precomputed as convertto / pointstoconvert. Multiply the points to spend by ratio to get the discount amount. E.g. ratio: 0.1 means 1 point is worth 0.10 in currency.

number

How many points convert into convertto currency units.

number

Currency amount that pointstoconvert points convert into.

boolean

Whether the customer keeps collecting points on the portion of the basket paid with points.

boolean

Whether points are collected over the discounted amount instead of the gross amount.

array

The customer’s active coupons. Same shape as items in GET /v1/customers/:id/coupons.

Show coupon fields

string

Coupon instance id. Use it as :couponId on redeem, or as reward on transactions.

object

Coupon summary: name.

string

Coupon code, when one is assigned. Optional.

string

Coupon type, e.g. discount or product. Optional.

number

Discount value. Interpreted as a percentage when isPercent is true. For product coupons this is 100 with isPercent: true (the product is free). Optional.

boolean

Whether discountAmount is a percentage. Optional.

number

Cap for percentage discounts. Optional.

boolean

Whether product modifiers are included in the discount. Optional.

object

Which products the coupon applies to. Present on product-scoped coupons.

Show products fields

number

How many items the coupon covers.

string[]

Product opaque ids the coupon applies to.

object

Where the coupon was issued (branch, user). Optional.

string

When the coupon was issued (ISO 8601). Optional.

string

Expiry time (ISO 8601). Optional.

string

Coupon status, e.g. active.

object

Free-form metadata attached to the customer. Optional.

object

Customer consent flags. Optional.

string | null

Customer-level barcode, when one is assigned.

string | null

External identifier from your own system, if assigned.

number

Status code of the customer record.

string

ISO 8601 creation timestamp. Omitted when not available.

string

Identifier of the actor that created the customer record. Omitted when not available.

string

ISO 8601 timestamp of the most recent update. Omitted when not available.

curl --request GET \
  --url "$BASE_URL/v1/customers/find?q=803606" \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "id": "3d8ec956-de2a-4d43-9c1e-74475b153362",
  "data": {
    "fullname": "Jane Doe",
    "phone": "+905551234567",
    "email": "jane@example.com"
  },
  "collectables": {
    "point_MMSR5": { "label": "Points", "value": 1000, "total": 2760 }
  },
  "consents": { "marketing": true },
  "barcode": "803606",
  "cards": [
    {
      "id": "41dd8263-288e-4b55-bf2e-6a82995a0441",
      "name": "Point Card",
      "barcode": "803606",
      "status": 1,
      "options": {
        "spend": {
          "pointstoconvert": 1,
          "convertto": 1,
          "collectwhilespending": false,
          "collectfromdiscountedamount": false,
          "ratio": 1
        }
      }
    }
  ],
  "opaqueId": null,
  "status": 1,
  "createdAt": "2026-04-21T12:19:19.037Z",
  "coupons": [
    {
      "id": "906550fd-dcf5-4aed-a80e-03e8939fc2b4",
      "coupon": { "name": "Free Coffee Coupon" },
      "code": "431825",
      "type": "product",
      "discountAmount": 100,
      "isPercent": true,
      "products": {
        "quantity": 1,
        "productIds": ["4221450", "4221453", "4221456"]
      },
      "issuedAt": "2026-04-21T12:19:19.037Z",
      "expiresAt": "2026-09-09T12:14:08.511Z",
      "status": "active"
    },
    {
      "id": "eb2373b1-8a01-41b7-a8f9-48d462ede4e0",
      "coupon": { "name": "10% Discount Coupon" },
      "code": "667500",
      "type": "discount",
      "discountAmount": 10,
      "isPercent": true,
      "maxDiscountAmount": 25,
      "issuedAt": "2026-04-27T12:14:20.513Z",
      "status": "active"
    }
  ]
}

{
  "statuscode": 400,
  "errorcode": 400,
  "message": "_customer_not_found",
  "description": "",
  "timestamp": 1754040000000,
  "path": "/v1/customers/find?q=803606",
  "method": "GET"
}

Save the returned id (customer id) and the cards[].id (customerpass id). You will need both on the coupon and transaction endpoints.

Last modified on August 6, 2026

⌘I

Getting started

Endpoints

Reference

Request headers

Query parameters

Response fields (200 OK)

​Request headers

​Query parameters

​Response fields (200 OK)

Request headers

Query parameters

Response fields (200 OK)