Find a customer

curl --request GET \
  --url "$BASE_URL/v1/customers/find?q=5551234567" \
  --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 },
    "stamp_K3M9A": { "label": "Stamps", "value": 4, "total": 12 }
  },
  "consents": { "marketing": true },
  "tags": [
    { "id": "f31c7e2a-...", "name": "VIP", "color": "#f5a623" }
  ],
  "categories": [],
  "barcode": "803606",
  "cards": [
    {
      "id": "41dd8263-288e-4b55-bf2e-6a82995a0441",
      "name": "Point Card",
      "barcode": "803606",
      "status": 1,
      "campaignIds": ["14c5a0ed-537e-400c-8463-e72bf277f600"],
      "collectables": {
        "point_MMSR5": { "label": "Points", "value": 1000, "total": 2760 }
      },
      "options": {
        "spend": {
          "pointstoconvert": 1,
          "convertto": 1,
          "collectwhilespending": false,
          "collectfromdiscountedamount": false,
          "ratio": 1
        },
        "collect": {
          "method": "percent",
          "percent": { "ratio": 5 }
        },
        "tier": {
          "level": 2,
          "track": "totalAmount",
          "trackValue": 3200,
          "nextLevel": 3,
          "nextThreshold": 5000,
          "remaining": 1800
        }
      }
    },
    {
      "id": "9c01d7c4-52aa-4f0e-8d40-2c4f27f81f02",
      "name": "Stamp Card",
      "barcode": "803611",
      "status": 1,
      "campaignIds": ["8b7d1f22-90ce-4f6d-9f5b-b0a4a2f7d356"],
      "collectables": {
        "stamp_K3M9A": { "label": "Stamps", "value": 4, "total": 12, "target": 10 }
      }
    }
  ],
  "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=5551234567",
  "method": "GET"
}

curl --request GET \
  --url "$BASE_URL/v1/customers/find?q=5551234567" \
  --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 },
    "stamp_K3M9A": { "label": "Stamps", "value": 4, "total": 12 }
  },
  "consents": { "marketing": true },
  "tags": [
    { "id": "f31c7e2a-...", "name": "VIP", "color": "#f5a623" }
  ],
  "categories": [],
  "barcode": "803606",
  "cards": [
    {
      "id": "41dd8263-288e-4b55-bf2e-6a82995a0441",
      "name": "Point Card",
      "barcode": "803606",
      "status": 1,
      "campaignIds": ["14c5a0ed-537e-400c-8463-e72bf277f600"],
      "collectables": {
        "point_MMSR5": { "label": "Points", "value": 1000, "total": 2760 }
      },
      "options": {
        "spend": {
          "pointstoconvert": 1,
          "convertto": 1,
          "collectwhilespending": false,
          "collectfromdiscountedamount": false,
          "ratio": 1
        },
        "collect": {
          "method": "percent",
          "percent": { "ratio": 5 }
        },
        "tier": {
          "level": 2,
          "track": "totalAmount",
          "trackValue": 3200,
          "nextLevel": 3,
          "nextThreshold": 5000,
          "remaining": 1800
        }
      }
    },
    {
      "id": "9c01d7c4-52aa-4f0e-8d40-2c4f27f81f02",
      "name": "Stamp Card",
      "barcode": "803611",
      "status": 1,
      "campaignIds": ["8b7d1f22-90ce-4f6d-9f5b-b0a4a2f7d356"],
      "collectables": {
        "stamp_K3M9A": { "label": "Stamps", "value": 4, "total": 12, "target": 10 }
      }
    }
  ],
  "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=5551234567",
  "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 five ways:

Customer id

Exact match on the customer’s id.

Opaque id

Exact match on opaqueId — the external identifier assigned from your own system.

Phone

Case-insensitive substring match on data.phone.

Exact match on data.email.

Barcode

Exact match on a card barcode. Only attempted when q is purely numeric and no customer field matched.

The first matching customer is returned, with loyalty balances (collectables), wallet cards (cards), active coupons (coupons), and the customer’s tags and categories. Each card also carries its own collectables subset, so when a phone or email search returns several cards you can relate every card to its balances without a second barcode lookup.

Request headers

string

required

Your active Bearer token: Bearer <accessToken>.

Query parameters

string

required

Search term: customer id, opaque id, 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.

string[]

Ids of the campaigns attached to this card. A card can carry several campaigns (e.g. points + stamps). Reference field for correlation.

object

This card’s loyalty balances, keyed by collectable key — the subset of the top-level collectables that belongs to this card. Use it to relate cards to balances when the customer has several cards.

Show card collectable entry fields

string

Optional human-readable label.

number

Current spendable balance.

number

Lifetime collected total.

number

Stamp target of the card’s stamp campaign — display progress as value/target (e.g. 4/10). Only present on stamp collectables.

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.

object

Point-earn configuration of the campaign, forwarded as-is. With method: "percent", percent.ratio is the percentage of the basket amount earned as points — use it for “you will earn X points” displays. Estimates only: active promotions can change the final earned amount.

object

Tier progress of the customer. Only present on tiered point campaigns.

Show tier fields

number

The customer’s current tier level.

string

Which counter drives tier progression (e.g. totalAmount).

number

The customer’s current value on the tracked counter.

number

The next tier’s level. Omitted when the customer is already at the top tier.

number

The tracked-counter threshold of the next tier. Omitted at the top tier.

number

How much is left to reach the next tier (nextThreshold - trackValue, never negative) — use it for “spend X more to reach the next tier” displays. Omitted at the top tier.

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.

array

Tags attached to the customer. Empty array when the customer has none.

Show tag fields

string

Tag id.

string

Display name of the tag.

string

Display color (hex). Omitted when not set.

array

Categories attached to the customer. Same shape as tags (id, name, color). Empty array when the customer has none.

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=5551234567" \
  --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 },
    "stamp_K3M9A": { "label": "Stamps", "value": 4, "total": 12 }
  },
  "consents": { "marketing": true },
  "tags": [
    { "id": "f31c7e2a-...", "name": "VIP", "color": "#f5a623" }
  ],
  "categories": [],
  "barcode": "803606",
  "cards": [
    {
      "id": "41dd8263-288e-4b55-bf2e-6a82995a0441",
      "name": "Point Card",
      "barcode": "803606",
      "status": 1,
      "campaignIds": ["14c5a0ed-537e-400c-8463-e72bf277f600"],
      "collectables": {
        "point_MMSR5": { "label": "Points", "value": 1000, "total": 2760 }
      },
      "options": {
        "spend": {
          "pointstoconvert": 1,
          "convertto": 1,
          "collectwhilespending": false,
          "collectfromdiscountedamount": false,
          "ratio": 1
        },
        "collect": {
          "method": "percent",
          "percent": { "ratio": 5 }
        },
        "tier": {
          "level": 2,
          "track": "totalAmount",
          "trackValue": 3200,
          "nextLevel": 3,
          "nextThreshold": 5000,
          "remaining": 1800
        }
      }
    },
    {
      "id": "9c01d7c4-52aa-4f0e-8d40-2c4f27f81f02",
      "name": "Stamp Card",
      "barcode": "803611",
      "status": 1,
      "campaignIds": ["8b7d1f22-90ce-4f6d-9f5b-b0a4a2f7d356"],
      "collectables": {
        "stamp_K3M9A": { "label": "Stamps", "value": 4, "total": 12, "target": 10 }
      }
    }
  ],
  "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=5551234567",
  "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

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)