Gift cards
The store gift cards: face value, balance and the store liability for each card. The card code is not stored or returned.
Gift cards
Objects
GiftCard
idintegerrequiredID of the record, unique among records of its kind in the store.
last4stringrequiredThe last four characters of the card code, used to recognise the card in the customer's hands. The code itself is not stored.
statusstringrequiredState: active — accepted for payment while it has a balance and has not expired; pending_payment — sold with a non-cash method, payment not confirmed yet; disabled — blocked (lost, dispute), the liability remains; deactivated — voided, the balance is cleared.
- Values:
activepending_paymentdisableddeactivated
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
- Values:
ARSUSDBRLCLPCOPMXNPENRUB
initial_amountintegerrequiredFace value at issue, in minor units of the currency.
balanceintegerrequiredCard balance in minor units of the currency — the sum of its activity entries (/v1/gift-card-transactions).
outstandingintegerrequiredThe store liability for the card: the balance, except for an unpaid card (pending_payment), for which no money came in. A blocked or expired card keeps its liability.
expires_atstring (date-time) or nullrequiredEnd of validity; null means no expiry. An expired card is not accepted for payment.
issued_atstring (date-time)requiredWhen the card was issued.
issued_order_idinteger or nullrequiredID of the order (/v1/orders) that sold the card; null for an issue without a sale (compensation, promo).
reissued_from_idinteger or nullrequiredID of the card whose balance was moved here by a reissue; null for a regular issue.
customer_idinteger or nullID of the owning customer (/v1/customers); null for a bearer card. Only with customer access.
notestring or nullrequiredStaff note at issue; null if there is none.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
Gift cards: face value, balance and the store liability for each card
get/gift-cards
Scope: finance:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/gift-cards" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"last4": "string",
"status": "active",
"currency": "ARS",
"initial_amount": 0,
"balance": 0,
"outstanding": 0,
"expires_at": "2026-01-15T12:00:00Z",
"issued_at": "2026-01-15T12:00:00Z",
"issued_order_id": 0,
"reissued_from_id": 0,
"customer_id": 0,
"note": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Gift card
get/gift-cards/{card}
Scope: finance:read
Parameters
Path
cardintegerrequiredGift card ID.
Responses
200Success
application/json
Returns GiftCard
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/gift-cards/{card}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"last4": "string",
"status": "active",
"currency": "ARS",
"initial_amount": 0,
"balance": 0,
"outstanding": 0,
"expires_at": "2026-01-15T12:00:00Z",
"issued_at": "2026-01-15T12:00:00Z",
"issued_order_id": 0,
"reissued_from_id": 0,
"customer_id": 0,
"note": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}