Gift Redemption - API Guidance


POST /api/integration/redemption/validate-gift

Verify a gift is valid and usable at the redemption location and retrieve gift information including current balance.

  "organizationID": "00000000-0000-0000-0000-000000000000",
  // - or -
  "pointOfSaleSystemOrganizationIdentifier": "string",
  "voucherCode": 000000000000,
  // - or -
  "voucherPublicToken": "string"

A voucherCode or voucherPublicToken are required - but not both. The voucherCode is the 12 digit number shown on the gift card - without formatting characters. The voucherPublicToken is encoded in the QR code shown on the gift card. The QR code contains a URL where the path component is the token. Either just the path component can be provided (the preferred approach) or the entire URL.

Either an organizationID or pointOfSaleSystemOrganizationIdentifier should be specified to identify the redemption location. The organizationID is Gift Local's internal unique identifier for the location (a Guid value) - but when POS redemption is enabled for a location - the POS system's internal ID can be configured such that it can be used as the location identifier in redemption related calls.

A location identifier is not required if the merchant’s account only has a single location (or the API key is only enabled for a single location). The account itself is identified by the API key used.

See validate-gift Reference


POST /api/integration/redemption/redeem-gift
Decrement the current balance of the gift.

  "organizationID": "00000000-0000-0000-0000-000000000000",  
  "voucherID": "00000000-0000-0000-0000-000000000000",  
  "amount": 0  

The voucherID is retrieved during the validation call.

The amount is a decimal if a monetary gift or an integer if an item gift - where it specified the quantity to redeem.

The organizationID is not required unless the merchant’s account has multiple locations. The account itself is identified by the API key used.

See validate-gift Reference

Constants Reference

The voucher payload returned from the APIs includes various constant values. The meaning of these constants can be found below.

Voucher Types

Voucher Types

Item types are identified with IsItem column above, but better to check voucher.isItemType property to determine if an item type.

To determine if a gift is promotional, you can check if either voucher.isPromoType or voucher.programIsPromotional is true depending on your use case.

Voucher Statuses

Voucher Status

DELIVERED (3), FAILED_DELIVERY (4), and CLAIMED (5) are redeemable - though better to check the voucher.isRedeemable property of the Voucher than doing a direct status ID comparison.

A voucher will transition to / remain in CLAIMED status if it is only partially redeemed. It must be fully redeemed to transition to REDEEMED status.

Error Codes Reference

Below is a sampling of the common error codes returned by the redemption and validation APIs.

VALIDATION_FAILUREEncapsulates various failures generally related to missing or incorrectly formatted fields. The messages property will provide details.

Generally validation errors can be corrected by resubmitting with updated input values.
NOT_FOUNDThe requested gift (or record) is not found.
INVALID_CODE_FORMATThe voucher code specified was not formatted as expected.
INVALID_TOKEN_FORMATThe voucher public token specified was not formatted as expected.
NOT_SUPPORTEDThe requested operation is not supported by the current account or by the system generally.
ACCOUNT_MISCONFIGUREDThe account is missing required configuration to be functional.
MISSING_OR_INVALID_GIFT_PROGRAMThe target gift program specified did not match the gift found.
INVALID_VOUCHER_TYPEThe target voucher type specified did not match the gift found.
ITEM_ELIGIBILITY_FAILURENo items on this check are eligible for discount with this gift card.
ALREADY_REDEEMEDFor Redemption API: the gift is already redeemed.
REDEMPTION_NOT_ALLOWEDFor Redemption API: Used when a gift is not in a redeemable state. The messages property will provide more details.

The Validation API will return this response in the single case where the gift failed during purchase but a voucher code was already generated.
NOT_AUTHORIZEDThe gift specified is not valid for redemption at the current account or location.
UNEXPECTED_ERRORAn internal server error occurred but was caught by the application.