> ## Documentation Index
> Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Get customer memberships
>
Documentation in progress
This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager.
Returns all loyalty memberships for a customer across programs, including the resolved customer identity and each membership's member, program, and cards. Use `identification_type` to choose how the `customerId` path value is interpreted.
Returns an empty `memberships` array when the customer exists but has no memberships. Returns 404 when the customer or member cannot be resolved.
## OpenAPI
````yaml /openapi/loyalties-v2.json get /v2/loyalties/memberships/{customerId}
openapi: 3.1.0
info:
title: Voucherify Loyalty v2 API
version: 2.0.0
description: >-
Complete OpenAPI specification for the Voucherify Loyalty v2 API.
All endpoints require the LOYALTY_V2 feature flag.
Combined from per-domain specs: programs.yaml, members.yaml,
program-operations.yaml, card-definitions.yaml, earning-rules.yaml,
tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml
servers:
- url: '{protocol}://{host}'
variables:
protocol:
default: https
enum:
- https
- http
host:
default: api.voucherify.io
security:
- X-App-Id: []
X-App-Token: []
- bearerAuth: []
tags:
- name: Programs
description: >-
Loyalty program CRUD, lifecycle management, program-scoped resource
assignments (card definitions, earning rules, rewards, tier structures),
member management (create, list, get, update, activate, deactivate,
delete), membership retrieval (member + program + cards with tier
progress, by customer ID, customer source ID, or member ID), card
operations (points adjustment, pending points, expiring points,
transactions), reward purchases, and activity history.
- name: Card Definitions
description: >-
CRUD operations, lifecycle management, and activity history for card
definitions. Card definitions describe the configuration for loyalty
cards, including code generation, points expiration, earning/spending
limits, pending points, refunds, and balance settings.
- name: Earning Rules
description: >-
Manage earning rules that define how customers earn points or receive
incentives based on triggers (events, segments, custom events). Includes
CRUD, lifecycle, and activity history.
- name: Tier Structures
description: >-
CRUD operations, lifecycle management, and activity history for tier
structures. Includes nested tier definitions (create, list, update,
delete) within tier structures. Tier structures define the tiering model
for loyalty programs — how members qualify for and move between tiers.
- name: Benefits
description: >-
Manage benefit definitions (fixed points, proportional points, material,
digital). Includes CRUD, lifecycle transitions, and activity history.
- name: Rewards
description: >-
CRUD, lifecycle operations, and activity history for reward definitions.
Rewards can be material (product/SKU) or digital (discount coupons, gift
vouchers).
- name: Examine
description: >-
Evaluation endpoints that estimate earning opportunities and reward
availability for a customer across their loyalty program memberships,
without side effects.
paths:
/v2/loyalties/memberships/{customerId}:
parameters:
- name: customerId
in: path
required: true
description: >-
Unique identifier of the customer or member, interpreted according to
`identification_type`: a Voucherify customer ID (`cust_...`), a
customer `source_id`, or a loyalty member ID (`lmbr_...`).
schema:
type: string
get:
tags:
- Programs
summary: Get customer memberships
description: >-
Documentation in progress
This documentation is in progress. The parameters, fields, request and
response bodies, and other data may be subject to change. If you need
more information or you want to share feedback, contact [Voucherify
support](https://www.voucherify.io/contact-support) or your Technical
Account Manager.
Returns all loyalty memberships for a customer across programs,
including the resolved customer identity and each membership's member,
program, and cards. Use `identification_type` to choose how the
`customerId` path value is interpreted.
Returns an empty `memberships` array when the customer exists but has no
memberships. Returns 404 when the customer or member cannot be resolved.
operationId: getCustomerMemberships
parameters:
- name: identification_type
in: query
required: false
description: >-
Defines how the `customerId` path value is interpreted.
`customer_id` - Voucherify customer ID (default).
`customer_source_id` - customer's `source_id`. `member_id` - loyalty
member ID.
schema:
type: string
enum:
- customer_id
- customer_source_id
- member_id
default: customer_id
responses:
'200':
description: Customer memberships across programs.
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipsResult'
examples:
Get customer memberships:
value:
customer:
id: cust_6onRrs4kCnvSVrTs5YtDPFBG
source_id: source-123
object: customer
memberships:
- member:
id: lmbr_128f962dbc8c4ba5dc
customer_id: cust_6onRrs4kCnvSVrTs5YtDPFBG
program_id: lprg_128f58429f4c4bf7b2
status: ACTIVE
metadata: {}
created_at: '2026-06-11T15:59:41.298Z'
updated_at: null
object: member
program:
id: lprg_128f58429f4c4bf7b2
name: VIP Program
status: ACTIVE
metadata: {}
object: program
cards:
- member_role: OWNER
created_at: '2026-06-11T15:59:41.298Z'
card:
id: lcard_128f962dbc8c4ba5dc
card_definition_id: lcdef_128f58429f4c4bf7b2
card_type: INDIVIDUAL
code: CARD-001
object: card
object: member_card
object: membership
object: memberships_result
'400':
description: >-
Validation error - request body or query parameters failed
validation, or the operation is not allowed in the current resource
state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
MembershipsResult:
type: object
description: Cross-program memberships result for a customer.
properties:
customer:
$ref: '#/components/schemas/MembershipsCustomer'
description: Resolved customer identity.
memberships:
type: array
description: >-
Memberships across all loyalty programs the customer belongs to.
Empty when the customer has no memberships.
items:
$ref: '#/components/schemas/MembershipWithoutTierProgress'
object:
type: string
const: memberships_result
description: Object type marker. Always `memberships_result`.
required:
- customer
- memberships
- object
ErrorResponse:
type: object
description: Standard error response returned by all Loyalty v2 endpoints.
properties:
code:
type: integer
description: HTTP status code of the error.
key:
type: string
description: Machine-readable error key.
message:
type: string
description: Human-readable error message.
details:
type: string
description: Additional details about the error.
request_id:
type: string
description: Unique identifier of the request that produced the error.
resource_id:
type: string
description: Unique identifier of the resource that produced the error.
resource_type:
type: string
description: Type of the resource that produced the error.
MembershipsCustomer:
type: object
description: Customer identity returned by the cross-program memberships endpoint.
properties:
id:
type: string
description: Unique Voucherify customer identifier.
source_id:
description: Customer `source_id`, or `null` when not set.
oneOf:
- type: string
- type: 'null'
object:
type: string
const: customer
description: Object type marker. Always `customer`.
required:
- id
- source_id
- object
MembershipWithoutTierProgress:
type: object
description: >-
A loyalty membership without tier-progress enrichment on cards. Combines
the member, the program, and the member's loyalty cards.
properties:
member:
$ref: '#/components/schemas/Member'
description: The loyalty program member.
program:
$ref: '#/components/schemas/ProgramSimple'
description: The loyalty program the member belongs to.
cards:
type: array
description: >-
Member's loyalty cards for the program. Card codes are generated
asynchronously, so `card.code` may be `null` right after member
creation. Tier progress is not included on this endpoint.
items:
$ref: '#/components/schemas/MemberCard'
object:
type: string
const: membership
description: Object type marker, always `membership`.
required:
- member
- program
- cards
- object
Member:
type: object
description: A loyalty program member.
properties:
id:
type: string
pattern: ^lmbr_[a-f0-9]+$
description: Unique member ID.
customer_id:
type: string
pattern: ^cust_[a-zA-Z0-9]+
description: Unique Voucherify ID of the customer enrolled as this member.
program_id:
type: string
pattern: ^lprg_[a-f0-9]+$
description: Unique Voucherify ID of the loyalty program the member belongs to.
status:
type: string
enum:
- ACTIVE
- INACTIVE
- DELETED
description: >-
Current member status. `INACTIVE` member can't earn points or redeem
rewards.
metadata:
type: object
description: Free-form metadata attached to the member (empty object when none).
created_at:
type: string
format: date-time
description: Timestamp when the member was created (ISO 8601).
updated_at:
type:
- string
- 'null'
format: date-time
description: >-
Timestamp when the member was last updated (ISO 8601), or `null` if
never updated.
object:
type: string
const: member
description: Object type marker, always `member`.
required:
- id
- customer_id
- program_id
- status
- metadata
- created_at
- updated_at
- object
ProgramSimple:
type: object
description: >-
A loyalty program in its simple representation, as embedded in
membership responses.
properties:
id:
type: string
description: Unique program identifier.
pattern: ^lprg_[a-f0-9]+$
name:
type: string
description: Program name.
status:
type: string
description: Program status.
enum:
- DRAFT
- ACTIVE
- INACTIVE
- DELETED
metadata:
type: object
description: User-defined key-value metadata. Defaults to `{}`.
object:
type: string
description: Object type marker. Always `program`.
const: program
required:
- id
- name
- status
- metadata
- object
MemberCard:
type: object
description: >-
A member's loyalty card - the member's assignment to the card
(`member_role`, `created_at`) combined with the card details in the
`card` object.
properties:
member_role:
type: string
enum:
- OWNER
- MEMBER
description: >-
Role of the member on this card. Currently, loyalty program members
can have only the `OWNER` role.
created_at:
type: string
format: date-time
description: Timestamp when the card was assigned to the member (ISO 8601).
card:
description: The loyalty card details, or `null` when the card is not available.
oneOf:
- $ref: '#/components/schemas/CardSimple'
- type: 'null'
object:
type: string
const: member_card
description: Object type marker, always `member_card`.
required:
- member_role
- created_at
- card
- object
CardSimple:
type: object
description: >-
A loyalty card in its simple representation, as embedded in member
responses.
properties:
id:
type: string
pattern: ^lcrd_[a-f0-9]+$
description: Unique Voucherify ID of the card.
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: >-
Unique Voucherify ID of the card definition the card was created
from.
card_type:
type: string
enum:
- INDIVIDUAL
description: Card type. Currently only `INDIVIDUAL` is supported.
code:
type:
- string
- 'null'
description: >-
Human-readable card code. Card code generation is asynchronous -
this field is `null` right after member creation and is populated
shortly after, once the background code generation completes.
lifetime_bucket:
$ref: '#/components/schemas/CardLifetimeBucket'
description: Lifetime point counters of the card.
balance:
$ref: '#/components/schemas/CardBalance'
description: Current available balance calculated from the lifetime bucket.
next_expiration:
description: >-
The nearest upcoming point expiration, or `null` when none is
scheduled.
oneOf:
- $ref: '#/components/schemas/CardNextExpiration'
- type: 'null'
next_activation:
description: >-
The nearest upcoming pending point activation, or `null` when none
is scheduled.
oneOf:
- $ref: '#/components/schemas/CardNextActivation'
- type: 'null'
object:
type: string
const: card
description: Object type marker, always `card`.
required:
- id
- card_definition_id
- card_type
- code
- lifetime_bucket
- balance
- next_expiration
- next_activation
- object
CardLifetimeBucket:
type: object
description: Lifetime points counters of a card.
properties:
points:
$ref: '#/components/schemas/CardLifetimeBucketPoints'
description: Lifetime counters of regular (active) points.
pending_points:
$ref: '#/components/schemas/CardLifetimeBucketPendingPoints'
description: Lifetime counters of pending points.
required:
- points
- pending_points
CardBalance:
type: object
description: Current available balance of a card.
properties:
points:
type: number
description: Currently available regular points.
default: 0
pending_points:
type: number
description: Currently pending (not yet activated) points.
default: 0
required:
- points
- pending_points
CardNextExpiration:
type: object
description: The nearest upcoming points expiration on a card.
properties:
points:
type: number
description: Number of points that will expire.
default: 0
date:
type: string
format: date
description: Date when the points expire (`YYYY-MM-DD`).
required:
- points
- date
CardNextActivation:
type: object
description: >-
The nearest upcoming pending points activation on a card. For the
`EVENT_BASED` type, `date` is omitted and `cancel_date` is returned
instead; for other types `date` is returned and `cancel_date` is
omitted.
properties:
points:
type: number
description: Number of pending points to be activated.
default: 0
type:
type: string
enum:
- IMMEDIATE
- PERIOD_BASED
- FIXED_DATES
- EVENT_BASED
description: Pending points activation type from the card definition.
date:
type: string
format: date
description: >-
Activation date (`YYYY-MM-DD`). Present for all types except
`EVENT_BASED`.
cancel_date:
type: string
format: date
description: >-
Date when the pending points are canceled if the activating event
does not occur (`YYYY-MM-DD`). Present only for the `EVENT_BASED`
type.
required:
- points
- type
CardLifetimeBucketPoints:
type: object
description: >-
Lifetime counters of regular points. All counters default to 0. The
available balance is calculated as: `total` - `subtracted` - `expired` -
`spent` - `refunded` + `returned` - `locked` + `unlocked` -
`purchased_reversed`.
properties:
total:
type: number
description: >-
Total accumulated points, including points added manually, earned by
fulfilling earning rules and activated from pending points
(excluding returned points).
default: 0
earned:
type: number
description: >-
Total points earned by fulfilling earning rules (does not include
activated pending points or points added manually).
default: 0
added:
type: number
description: Total manually added points.
default: 0
purchased:
type: number
description: >-
Total points purchased via a `LOYALTY_CARD_POINTS` reward (credited
to the target card).
default: 0
purchased_reversed:
type: number
description: Total purchased points reversed via reward refund.
default: 0
subtracted:
type: number
description: Total manually subtracted points.
default: 0
expired:
type: number
description: Total expired points.
default: 0
spent:
type: number
description: Total points spent on rewards.
default: 0
refunded:
type: number
description: >-
Total refunded points (points that were earned by products which
were later returned).
default: 0
returned:
type: number
description: Total returned points (by returning a purchased reward).
default: 0
locked:
type: number
description: Total locked points (by locking a purchased reward).
default: 0
unlocked:
type: number
description: Total unlocked points (by unlocking a purchased reward).
default: 0
required:
- total
- earned
- added
- purchased
- purchased_reversed
- subtracted
- expired
- spent
- refunded
- returned
- locked
- unlocked
CardLifetimeBucketPendingPoints:
type: object
description: >-
Lifetime counters of pending points. The available pending balance is
max(`total` - `activated` - `canceled`, 0).
properties:
total:
type: number
description: Total pending points ever added.
default: 0
activated:
type: number
description: Total pending points activated into regular points.
default: 0
canceled:
type: number
description: Total pending points canceled.
default: 0
required:
- total
- activated
- canceled
securitySchemes:
X-App-Id:
type: apiKey
name: X-App-Id
in: header
X-App-Token:
type: apiKey
name: X-App-Token
in: header
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````