Store-facing lookups: card balance, item eligibility, accepted providers, and catalog SKUs.
Get card balance
Headers
x-zpl-api-keyGateway API key. Required on every request.
x-api-keyYour store API key — authenticates the request as your store.
Get card balance › Request Body
cardNumberGets or sets the card number. This field is required.
Get card balance › Responses
OK
Response body for POST /api/public/v1/cards/balance. Reports the card's spendable
balance broken out by benefit wallet. The card number is masked to the last 4 digits.
isOkGets or sets a value indicating whether the operation was successful.
errorMessageGets or sets the error message if the operation failed.
errorCodeGets or sets a stable, machine-readable error code when the operation failed with a
known business error (e.g. "Incorrect" / "Locked" for PIN checkout).
Clients should switch on this instead of parsing ErrorMessage. Null for
success and for generic/unclassified failures.
Check item eligibility
Headers
x-zpl-api-keyGateway API key. Required on every request.
x-api-keyYour store API key — authenticates the request as your store.
Check item eligibility › Request Body
cardNumberFull PAN of the card being checked.
codeThe scanned item code (store PLU or provider UPC/EAN).
Check item eligibility › Responses
OK
Response body for POST /api/public/v1/items/check. Tells a register whether a
scanned item is covered by the card and how much it can still draw
(AmountCovered), already combined across the card's funding sources. Does not
depend on the item's price (no amount on the request); the register covers a line with
min(lineAmount, amountCovered).
isOkGets or sets a value indicating whether the operation was successful.
errorMessageGets or sets the error message if the operation failed.
errorCodeGets or sets a stable, machine-readable error code when the operation failed with a
known business error (e.g. "Incorrect" / "Locked" for PIN checkout).
Clients should switch on this instead of parsing ErrorMessage. Null for
success and for generic/unclassified failures.
List providers
Lists the providers the calling store accepts.
The gateway merges its own routing configuration into this list: IINs your store is approved to route to a provider are added to the matching provider (matched on name), and a provider the gift card backend does not return at all is appended with providerId 0. iins is deduplicated and sorted ascending.
The response may be reused for 60 minutes (Cache-Control: private, max-age=3600). It is scoped to your API key, so it must not be held in a shared cache. Routing changes made in the portal take effect immediately.
Headers
x-zpl-api-keyGateway API key. Required on every request.
x-api-keyYour store API key — authenticates the request as your store.
List providers › Responses
OK
Gets or sets the results list if the operation was successful.
isOkGets or sets a value indicating whether the operation was successful.
errorMessageGets or sets the error message if the operation failed.
errorCodeGets or sets a stable, machine-readable error code when the operation failed with a known business error. Clients should switch on this instead of parsing ErrorMessage. Null for success and for generic/unclassified failures.
totalCountGets or sets the total count of items available (useful for pagination). This value is null when pagination is not used.
pageGets or sets the current page number (1-based). This value is null when pagination is not used.
pageSizeGets or sets the number of items per page. This value is null when pagination is not used.
List SKUs
query Parameters
page1-based page number (default 1).
pageSizeItems per page, 1–500 (default 50).
lastUpdatedOptional delta-sync filter: only SKUs with a catalog update at or after this instant are returned (values without a UTC offset are treated as UTC). The provider list per returned SKU stays complete.
Headers
x-zpl-api-keyGateway API key. Required on every request.
x-api-keyYour store API key — authenticates the request as your store.
List SKUs › Responses
OK
Gets or sets the results list if the operation was successful.
isOkGets or sets a value indicating whether the operation was successful.
errorMessageGets or sets the error message if the operation failed.
errorCodeGets or sets a stable, machine-readable error code when the operation failed with a known business error. Clients should switch on this instead of parsing ErrorMessage. Null for success and for generic/unclassified failures.
totalCountGets or sets the total count of items available (useful for pagination). This value is null when pagination is not used.
pageGets or sets the current page number (1-based). This value is null when pagination is not used.
pageSizeGets or sets the number of items per page. This value is null when pagination is not used.
Get SKU
path Parameters
skuProvider catalog item code (exact match).
Headers
x-zpl-api-keyGateway API key. Required on every request.
x-api-keyYour store API key — authenticates the request as your store.
Get SKU › Responses
OK
One item code available to a store across its accepted providers' catalogs, returned by
GET /api/public/v1/skus. The same code may be listed by several providers, each with
its own category — those appear as entries in Providers.
isOkGets or sets a value indicating whether the operation was successful.
errorMessageGets or sets the error message if the operation failed.
errorCodeGets or sets a stable, machine-readable error code when the operation failed with a
known business error (e.g. "Incorrect" / "Locked" for PIN checkout).
Clients should switch on this instead of parsing ErrorMessage. Null for
success and for generic/unclassified failures.