validate-gift

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

redeem-gift

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

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

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.