/member/details

Description

This API call is used to verify the customer is a loyalty member, retrieve their member details (name, balance, etc.), and optionally evaluate their transaction context for benefits and redeemable assets.

Purpose

To verify if a customer is a registered loyalty member
To display member information, balances, and gift list
To preview benefits or discounts before finalizing a purchase

When to Use

To display member profile before or during checkout
To fetch up-to-date balances and gift eligibility
To run a preview of discounts on a draft transaction

Request Format

Method & URL

POST /member/details

See API Servers for the base URL to use for your brand (the example below uses a fixed dev URL for illustration).

Headers

Header	Type	Required	Description
`x-api-key`	string	Yes	API key used to authenticate the request
`x-source-type`	string	Yes	Origin of the request (e.g., POS, Web)
`x-source-name`	string	Yes	Name of the client or integration
`x-pos-id`	string	Yes	Unique identifier of the POS terminal
`x-branch-id`	string	Yes	Identifier of the branch where the request originates
`x-return-assets`	string	No	Filter assets by status: `active`, `inactive`, `all`
`x-return-benefits`	boolean	No	Set to `true` or `false` to trigger benefit calculation (default: `false`)

Request Body

Field	Description	Type	Mandatory
member	Object representing a member’s identifier	Member	Y
transaction	Customer’s transaction details	Transaction	N

Request Example

Short Instance - Just for Identification

curl --location --request POST 'https://dev-pos-api.fidelizacion.app/v1/member/details' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{api-key}}' \
--header 'x-source-type: POS' \
--header 'x-source-name: pos_terminal_01' \
--header 'x-pos-id: POS001' \
--header 'x-branch-id: BR001' \
--header 'x-return-assets: active' \
--header 'x-return-benefits: false' \
--data-raw '{
  "member": {
    "phoneNumber": "123456789"
  }
}'

Long Instance - Identification + Transaction Preview

curl --location --request POST 'https://dev-pos-api.fidelizacion.app/v1/member/details' \
--header 'Content-Type: application/json' \
--header 'x-api-key: {{api-key}}' \
--header 'x-source-type: POS' \
--header 'x-source-name: pos_terminal_01' \
--header 'x-pos-id: POS001' \
--header 'x-branch-id: BR001' \
--header 'x-return-assets: active' \
--header 'x-return-benefits: true' \
--data-raw '{
  "member": {
    "phoneNumber": "123456789"
  },
  "transaction": {
    "transactionId": "TX-DEMO-01",
    "dateTime": "2025-06-17T18:30:00Z",
    "totalAmount": 1500,
    "items": [
      {
        "lineId": "1",
        "code": "LATTE001",
        "name": "Latte",
        "departmentCode": "DRINKS",
        "departmentName": "Beverages",
        "quantity": 1,
        "subtotal": 1500,
        "total": 1500
      }
    ],
    "payments": [
      {
        "type": "CASH",
        "amount": 1500
      }
    ],
    "employee": "Demo Cashier"
  },
  "usedAssets": []
}'

Success Response

Field	Description	Type
status	Indicates request status	string
member	Member object	object
avaliableDeals	(Conditional) Present when `x-return-benefits: true`. Field name matches the live API exactly — not a documentation typo	array
usedAssets	(Conditional) Computed array, present when the request includes a `usedAssets` array	array

{
  "status": "success",
  "member": {
    "status": "active",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "123456789",
    "email": "member@example.com",
    "gdpr": true,
    "termsOfUse": true,
    "tags": [],
    "preferredLanguage": "en",
    "birthday": "1991-02-26T00:00:00.000Z",
    "cardNumber": "1234567890123456",
    "visit": 0,
    "totalSpent": 0,
    "customFields": {},
    "membershipKey": "0fe31b8b-5ad5-48af-81e9-4adc7d596042",
    "commonExtId": "0fe31b8b-5ad5-48af-81e9-4adc7d596042",
    "businessId": 7,
    "allowedSMS": true,
    "allowedEmail": true,
    "allowedPush": false,
    "points": {
      "balance": 0,
      "useForPayments": false
    },
    "credit": {
      "balance": 0,
      "useForPayments": true
    },
    "assets": [
      {
        "campaignId": "6a21b682bd293321900aad44",
        "assetKey": "6OtRspANcZcM87WSEWHz",
        "assignDate": "2025-02-01T09:01:02.123Z",
        "status": "active",
        "validFrom": "2025-11-09T23:00:00.000Z",
        "validUntil": "2030-11-10T22:59:59.999Z",
        "assetDetails": {
          "campaignId": "6a21b682bd293321900aad44",
          "kind": "gift",
          "name": "Buy 1 Get 1 Free",
          "description": "Buy any coffee and get another one for free. Valid for all coffee drinks.",
          "image": "https://vault.uye.app/hub/assets/basicGift.png"
        }
      },
      {
        "campaignId": "6a21b689ee4835acd16acf41",
        "assetKey": "4r5zcgpt9HYnEkOcCWNc",
        "assignDate": "2025-01-01T09:01:02.123Z",
        "status": "inactive",
        "validFrom": "2024-12-31T23:00:00.000Z",
        "validUntil": "2030-12-30T22:59:59.999Z",
        "assetDetails": {
          "campaignId": "6a21b689ee4835acd16acf41",
          "kind": "gift",
          "name": "Free Cookie",
          "description": "Get a free cookie with any purchase. Valid for all items.",
          "image": "https://vault.uye.app/hub/assets/basicGift.png"
        }
      }
    ],
    "behaviors": {
      "favouriteItems": [],
      "favouriteBranch": {
        "branchId": "BR001",
        "name": "BRANCH-01"
      }
    },
    "registeredAt": "2024-06-20T13:34:56.045Z"
  }
}

Benefits Preview Response (`x-return-benefits: true`)

When x-return-benefits: true is set, the response adds avaliableDeals. When the request also includes a usedAssets array, the response adds a computed usedAssets array.

{
  "status": "success",
  "member": {
    "membershipKey": "0fe31b8b-5ad5-48af-81e9-4adc7d596042",
    "points": { "balance": 0, "useForPayments": false },
    "credit": { "balance": 0, "useForPayments": true }
  },
  "avaliableDeals": [],
  "usedAssets": []
}

avaliableDeals — field name matches the live API exactly (avaliableDeals, not availableDeals) — do not correct the spelling in requests or docs.
usedAssets (response) — computed array, present when the request's usedAssets is present.
Requesting x-return-benefits: true without a transaction in the request body returns error 303 — see Error Codes.

Error Response

Field	Description	Type
status	Error status indicator	string
error	Error object	object

{
  "status": "error",
  "error": {
    "code": "203",
    "message": "Cannot find any member with the given identifier!"
  }
}

Error Codes

Code	Description
`101`	Missing `X-Api-Key`
`102`	Missing `X-Source-Type`
`103`	Missing `X-Source-Name`
`104`	Missing `X-Pos-Id`
`105`	Missing `X-Branch-Id`
`201`	Invalid `X-Return-Assets` value
`202`	Invalid `X-Return-Benefits` value
`203`	Member not found
`303`	Transaction required to calculate benefits

Field Reference

Member Object

For detailed information about the member response fields, see the Member reference page.

The preferredLanguage field is returned as an ISO 639-1 two-letter code — the primary language subtag of a BCP 47 tag (e.g. en, es, ca).

Asset Object

The assets array in the member response contains Asset objects, which represent redeemable promotional items and benefits assigned to the member. Each asset includes:

campaignId — Unique identifier of the issuing campaign
assetKey — Unique identifier of this specific asset instance
assignDate — When the asset was assigned to the member
status — Asset status ("active" or "inactive")
validFrom / validUntil — Validity date range (ISO 8601)
assetDetails — Campaign metadata including name, description, and image

For comprehensive field documentation and examples, refer to the Asset reference page.

Transaction Object

For detailed information about the transaction request fields, see the Transaction reference page.

Description​

Purpose​

When to Use​

Request Format​

Method & URL​

Headers​

Request Body​

Request Example​

Short Instance - Just for Identification​

Long Instance - Identification + Transaction Preview​

Success Response​

Benefits Preview Response (x-return-benefits: true)​

Error Response​

Error Codes​

Field Reference​

Member Object​

Asset Object​

Transaction Object​