A valid request URL is required to generate request examples{
"items": [
{
"id": "gc-2026-000142",
"code": "GC-4F2A-9B71",
"kind": "gift_card",
"currency": "EUR",
"initialBalanceCents": 5000,
"balanceCents": 3500,
"status": "active",
"expiresAt": "2028-01-31T23:59:59.000Z"
}
],
"total": 1,
"page": 1,
"pageSize": 20,
"pageCount": 1
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123,
"fieldErrors": [
{
"field": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}List stored-value instruments (carte cadeau, avoir)
Returns one page of the issued instrument book (gift cards, credit notes and store credit share one aggregate). Filter with kind and/or status, sort by code or balanceCents, and walk with page/pageSize (max 100) until pageCount. Use this to survey or reconcile the book; to resolve ONE card a customer is holding, use the by-code lookup instead — a scanned code is not searchable here.
A valid request URL is required to generate request examples{
"items": [
{
"id": "gc-2026-000142",
"code": "GC-4F2A-9B71",
"kind": "gift_card",
"currency": "EUR",
"initialBalanceCents": 5000,
"balanceCents": 3500,
"status": "active",
"expiresAt": "2028-01-31T23:59:59.000Z"
}
],
"total": 1,
"page": 1,
"pageSize": 20,
"pageCount": 1
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123,
"fieldErrors": [
{
"field": "<string>",
"message": "<string>"
}
]
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}{
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"statusCode": 123
}
}Authorizations
Authorization: Bearer <token>. Accepts EITHER a Keycloak access token (scopes-in-token) OR an opaque POS session token; both resolve to the same pos.* scope vocabulary the route guards enforce.
Query Parameters
1-based page index to return. Defaults to 1.
1 <= x <= 9007199254740991Rows per page, 1..100. Defaults to 20.
1 <= x <= 100Instrument kind to filter on: gift_card / credit_note / store_credit.
gift_card, credit_note, store_credit Instrument status to filter on, e.g. active / depleted / void.
active, depleted, void Field to order by: code or balanceCents.
code, balanceCents Order direction for sortField (default asc).
asc, desc Response
A page of instrument read models with the pagination totals.
A page of instrument read models with the pagination totals.
The rows on this page, in the query's sort order.
Show child attributes
Show child attributes
Total rows matching the filter across ALL pages, not just this one.
0 <= x <= 9007199254740991The 1-based page number served.
0 < x <= 9007199254740991Rows requested per page.
0 < x <= 9007199254740991Total number of pages; stop walking when page reaches it.
0 <= x <= 9007199254740991