/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
usedAssets	Assets to check before redeeming. Each entry is `{ "key": "<assetKey from member.assets[]>" }`, the same `key` you will send on /transaction. Answered in the response `usedAssets`	array	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": 1850,
    "items": [
      {
        "lineId": "1",
        "code": "LATTE001",
        "name": "Latte",
        "departmentCode": "DRINKS",
        "departmentName": "Beverages",
        "quantity": 1,
        "subtotal": 1500,
        "total": 1500
      },
      {
        "lineId": 3,
        "code": "2084",
        "name": "Croquetas",
        "departmentCode": "FOOD",
        "departmentName": "Food",
        "quantity": 1,
        "subtotal": 350,
        "total": 350
      }
    ],
    "payments": [
      {
        "type": "CASH",
        "amount": 1850
      }
    ],
    "employee": "Demo Cashier"
  },
  "usedAssets": [
    { "key": "Qm3xT8uLpZa1bC2dE3fG" },
    { "key": "6OtRspANcZcM87WSEWHz" }
  ]
}'

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 `x-return-benefits: true` and the request's `usedAssets` is non-empty	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 non-empty usedAssets array, the response adds a computed usedAssets array.

The example below answers the Long Instance request above: one automatic deal applies to the latte, the first used asset applies to the croquetas, and the second used asset fails.

{
  "status": "success",
  "member": {
    "membershipKey": "0fe31b8b-5ad5-48af-81e9-4adc7d596042",
    "points": { "balance": 0, "useForPayments": false },
    "credit": { "balance": 0, "useForPayments": true }
  },
  "avaliableDeals": [
    {
      "key": "66f1c0a2e4b0a1b2c3d4e5f6",
      "name": "Coffee 10% off",
      "description": "",
      "totalAmount": -150,
      "benefits": [
        {
          "type": "discount",
          "total": -150,
          "details": [
            {
              "discount": -150,
              "discountQuantity": 1,
              "discountUnitAmount": -150,
              "item": { "lineId": 1, "code": "LATTE001", "quantity": 1, "total": 1500 }
            }
          ]
        }
      ]
    }
  ],
  "usedAssets": [
    {
      "key": "66f1c0a2e4b0a1b2c3d4e5f7",
      "name": "Free croquetas",
      "description": "",
      "totalAmount": -350,
      "benefits": [
        {
          "type": "discount",
          "total": -350,
          "details": [
            {
              "discount": -350,
              "discountQuantity": 1,
              "discountUnitAmount": -350,
              "item": { "lineId": 3, "code": "2084", "quantity": 1, "total": 350 }
            }
          ]
        }
      ]
    },
    { "key": "6OtRspANcZcM87WSEWHz", "valid": false, "error": "Asset condition is not met!" }
  ]
}

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 non-empty; an empty array when the member holds no assets.
Requesting x-return-benefits: true without a transaction in the request body returns error 303 — see Error Codes.

Entry fields

Each entry of avaliableDeals and usedAssets has these fields:

Field	Type	Description
`key`	string	Applicable entry: the campaign id. Failed `usedAssets` entry: the asset key you sent.
`name`, `description`	string	The campaign's name and description.
`totalAmount`	number	Total discount of this entry, negative, smallest currency unit.
`benefits[].type`	string	`discount`.
`benefits[].total`	number	This benefit's discount, negative.
`benefits[].details[]`	array	One row per discounted basket line.
`details[].discount`	number	Discount on that line, negative.
`details[].discountQuantity`	number	Units of the line that were discounted. Can be fractional when a free item is shared across several lines.
`details[].discountUnitAmount`	number	Discount per unit, negative.
`details[].item`	object	The line: `lineId`, `code`, `quantity`, and `total` (the line total you sent).
`valid`	boolean	Only on a failed `usedAssets` entry, always `false`. An entry without `valid` applies.
`error`	string	Only on a failed entry: `Member did not give consent yet!`, `Used asset does not belong to the member.`, `Asset is already used!`, `Campaign not found!`, `Asset is expired!`, `Campaign is expired or inactive!`, `Asset condition is not met!`.

Rules for using the entries:

usedAssets entries come back in the same order as the request's usedAssets. Match them by position, not by key: an applicable gift carries its campaign id, so two gifts from one campaign share a key.
To redeem, send the asset key from your own request (the assetKey from member.assets[]) on /transaction, never the preview's campaign id. avaliableDeals[].key goes back unchanged as appliedDeals[].key.
Send each entry's totalAmount unchanged as its appliedAmount on /transaction: negative, smallest currency unit.
usedAssets is returned only when the request's usedAssets is non-empty. If the member holds no assets at all, it comes back as an empty array, with no entry per requested asset.
Send each usedAssets[] entry with its key. The preview and /transaction look the asset up by key only.
A free-item gift whose item is not in the basket fails with Asset condition is not met!; the engine never adds the item.

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)​

Entry fields​

Error Response​

Error Codes​

Field Reference​

Member Object​

Asset Object​

Transaction Object​