Overview
GiftRocker offers a secure JSON REST API to partners needing to create, redeem or check balances of GiftRocker gift cards and promotions on behalf of shared merchants. Contact Alex at GiftRocker.com if you are a POS maker, online ordering portal or marketing platform and would like to integrate.
Authentication
GiftRocker’s API supports both basic authentication and OAUTH 2.0. The choice of authentication method and other security measures, e.g. OAUTH or basic authentication + governor limits, will be decided by GiftRocker and partner at the start of an integration project. Endpoints and authentication details will then be provided for GiftRocker’s sandbox and production environments.
Transaction Types
Transaction types are designated in the API header and in the message body through JSON request and response object names.
| Header Transaction Type | Request Object | Response Object |
|---|---|---|
| GET_BALANCE | getBalance | getBalanceResponse |
| REDEEM | redeem | redeemResponse |
| ADD_VALUE | addValue | addValueResponse |
| ACTIVATE | activate | activateResponse |
| REVERSE | reverse | reverseResponse |
| CREATE | create | createResponse |
Transaction Header
The transaction HTTP header is an array identifying the partner, merchant, transaction type and unique transaction id. The partner and merchant identifiers are used for authentication.
| Array Element Name | Element Value | Description |
|---|---|---|
| content-type | application/json | Defines the media type for the service as JavaScript Object Notation (JSON) |
| Authentication | Bearer or Basic | Expiring OAUTH token from a token service or Base64(username:password) |
| TransactionType | e.g. GET_BALANCE | See transaction type table for the complete set of values |
| MerchantID | UUID v4, 36 character string – Canonical Format | Unique identifier for the merchant in GiftRocker |
| DeviceID | up to 64 bytes | Optional identifier of the device used to initiate the transaction |
| Source | constant | Required. Indicates how the transaction was initiated. Values include: SWIPED, SCANNED, KEYED, PROMO |
| TransactionID | up to 64 byte, UUID v4 recommended | Unique identifier for each transaction |
Get Balance
Get Balance will return a gift card’s current value. It can be called prior to a a gift card’s redemption allowing an order to be totaled with a valid gift card prior to placing. Following is the getBalance object from a request, response envelope and getBalanceResponse object:
{“getBalance”: {“giftCardReference”:”ad034bed”}}
{“transactionStatus”:”ACCEPT”,”getBalanceResponse”:{“currentBalance”:”15.00″}}
| Action | Label | Description |
|---|---|---|
| request | giftCardReference | 8-64 characters alphanumeric not case sensitive |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance returned as a string, e.g. “15.00” |
| response | beginDate | date certificate becomes effective |
| response | endDate | date after which certificate expires |
| response | description | short description of the gift card for the customer. may include terms and conditions, e.g. gift card welcome at Dad’s Great Fish from January 1st, 2026 through March 31, 2026 |
Activate
Activate initializes and sets a value for a gift card reference that is known within GiftRocker and associated with the merchant. Activate works with uninitialized cards and cards that have been fully redeemed. Following is the activate object from a request, response envelope and activateResponse object:
{“activate”: {“initialBalance”:15.00, “giftCardReference”:”ad034bed”,”orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”activateResponse”:{“currentBalance”:”15.00″}}
| Action | Label | Description |
|---|---|---|
| request | giftCardReference | 8-64 characters alphanumeric not case sensitive |
| request | initialBalance | currency with 2 decimal places, e.g. 15.00 |
| request | orderID | Optional but recommended up to 64 character order identifier from the requesting partner. |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance returned as a string, e.g. “15.00” |
| response | beginDate | date certificate becomes effective |
| response | endDate | date after which certificate expires |
| response | description | short description of the gift card for the customer. may include terms and conditions, e.g. gift card welcome at Dad’s Great Fish from January 1st, 2026 through March 31, 2026 |
Redeem
Redeem subtracts value from a gift card known within GiftRocker and associated with the merchant or associated with the merchant’s enterprise. If a redemption request is larger than the value of the gift card, the redemption value will be limited. Following is the redeem object from a request, response envelope and redeemResponse object:
{“redeem”: {“redeemedValue”:0.25, “giftCardReference”:”ad034bed”,”orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”redeemResponse”:{“currentBalance”:”14.75″,”redeemedValue”:”0.25″}}
| Action | Label | Description |
|---|---|---|
| request | giftCardReference | 8-64 characters alphanumeric not case sensitive |
| request | redeemedValue | currency with two decimal places representing redeem request |
| request | orderID | Optional but recommended up to 64 character order identifier from the requesting partner. |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance returned as a string, e.g. “15.00” |
| response | redeemedValue | currency with two decimal places representing the actual value redeemed returned as a string, e.g. “0.25” |
| response | beginDate | date certificate becomes effective |
| response | endDate | date after which certificate expires |
| response | description | short description of the gift card for the customer. may include terms and conditions, e.g. gift card welcome at Dad’s Great Fish from January 1st, 2026 through March 31, 2026 |
Add Value
Add value adds value to a gift card known within GiftRocker and associated with the merchant or associated with the merchant’s enterprise. Following is the add value object from a request, response envelope and addValueResponse object:
{“addValue”: {“additionalValue”:0.5, “giftCardReference”:”ad034bed”,”orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”addValueResponse”:{“currentBalance”:”15.00″,”additionalValue”:”0.50″}}
| Action | Label | Description |
|---|---|---|
| request | giftCardReference | 8-64 characters alphanumeric not case sensitive |
| request | additionalValue | currency with two decimal places |
| request | orderID | Optional but recommended up to 64 character order identifier from the requesting partner. |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance returned as a string, e.g. “15.00” |
| response | additionalValue | currency with two decimal places representing the actual value added returned as a string, e.g. “0.50” |
| response | beginDate | date certificate becomes effective |
| response | endDate | date after which certificate expires |
| response | description | short description of the gift card for the customer. may include terms and conditions, e.g. gift card welcome at Dad’s Great Fish from January 1st, 2026 through March 31, 2026 |
Reverse
Reverse allows partners to back a transaction out of GiftRocker. Reverse restores the Gift Card to the state and values from before the original transaction. Reverse can be used to ensure system integrity when a response isn’t received from GiftRocker. For example, if a redeem request is originated and no response is received, the originating partner will not know whether the service failed on the request or on the response. Before originating a new request, a reverse should be used referencing the unique identifier of the original transaction. Following is the reverse object from a request, response envelope and reverseResponse object:
{“reverse”: {“previousTransaction”:”106f41f3-6895-447d-a766-d308d546b286″,”giftCardReference”:”ad034bed”,”orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”reverseResponse”:{“currentBalance”:”15.00″}}
| Action | Label | Description |
|---|---|---|
| request | previousTransaction | up to 64 characters, TransactionID from the original request |
| request | giftCardReference | 8-64 characters alphanumeric not case sensitive |
| request | orderID | Optional but recommended up to 64 character order identifier from the requesting partner. |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below. |
| response | currentBalance | currency with two decimal places representing the gift card’s balance returned as a string, e.g. “15.00” |
Create
Create allows partners to generate gift cards or promotions, e.g. a $20 gift card for a good review. Shopkeepers grant permission to partners to generate these certificates on their behalf and can set limits on denomination and frequency. Following is the request and response when creating a certificate:
{“create”: {“createValue”:15.00, “recipient”:”alex@giftrocker.com”,”offering”:”c3por2d2″,orderID”:”1954b170-9a43-4dbf-9897-e9aa84fce9a0″}}
{“transactionStatus”:”ACCEPT”,”createResponse”:{“reference”:”728243859827″,”currentBalance”:”15.00″}}
| Action | Label | Description |
|---|---|---|
| request | createValue | Optional depending on offering. If traditional gift cards, createValue is currency. If a fixed price promotion, not required. If an event ticket, will be ticket count |
| request | recipient | Required – email or US phone number |
| request | offering | Optional – merchant default is used if omitted. An offering can be a gift card, promotion or event ticket as defined within GiftRocker |
| request | orderID | Optional but recommended up to 64 character order identifier from the requesting partner |
| response | transactionStatus | ACCEPT is the desired status. Error messages can be found below |
| response | currentBalance | Currency with two decimal places representing the gift card’s balance returned as a string, e.g. “15.00” |
| response | reference | 8 to 64 alpha numeric certificate reference |
| response | beginDate | date certificate becomes effective |
| response | endDate | date after which certificate expires |
| response | description | short description of the gift card for the customer. may include terms and conditions, e.g. gift card welcome at Dad’s Great Fish from January 1st, 2026 through March 31, 2026 |
Error Messages
Successful requests will return an HTTP 200 status. Unsuccessful requests will return an HTTP 400 status and one of the following transaction status constants:
| Error Message | Description |
|---|---|
| ERROR_INVALID_TRANSACTION_TYPE | Not GET_BALANCE, REDEEM, ACTIVATE, ADD_VALUE, REVERSE or CREATE |
| ERROR_CARD_ALREADY_ACTIVATED | Attempting to activate a card that is already active |
| ERROR_CARD_NOT_ACTIVATED | GET_BALANCE on a card that is not activated |
| ERROR_CARD_INVALID | Card not found for this merchant |
| ERROR_INVALID_INPUT_PROPERTIES | One or more attributes are invalid |
| ERROR_TRANSACTION_DOES_NOT_EXIST | Attempt to reverse failed because the original transaction was not received. Ok to resubmit the original transaction |
| ERROR_TRANSACTION_CANNOT_BE_REVERSED | Either reverse is not supported on this transaction type or the underlying certificate changed in a way where this reverse would not make sense |
| ERROR_INVALID_MERCHANT | Merchant ID in header is not found |
| ERROR_SUSPENDED_MERCHANT | Merchant api requests included too many failed balance lookups suggesting robotic cracking activity |
| ERROR_INVALID_RECIPIENT | Email invalid or phone not 10 digits |
| ERROR_INVALID_OFFERING1 | Offering does not exist |
| ERROR_INVALID_OFFERING2 | Merchant is not authorized to use this offering. You may have a different merchant’s offering |
| ERROR_INVALID_OFFERING3 | Cannot create certificate from offering |
| ERROR_INVALID_AMOUNT | Amount is not numeric or not within the offering’s lower and upper limit |
| ERROR_BANNED_RECIPIENT | Email or phone associated to a bad apple, e.g. disputed transaction |
| ERROR_CREATE_DUPLICATE | Offering has a limit of one per email/phone |
| ERROR_CREATE_LIMIT_REACHED | Offering creates have exceeded limit set by merchant. Limits can be hourly, daily or lifetime |
| ERROR_NOT_YET_AVAILABLE | Offering’s sell begin date is in the future |
| ERROR_NO_LONGER_AVAILABLE | Offering’s sell end date is in the past |
Idempotency, Uniqueness and Timeouts
GiftRocker’s API response times are typically .2 seconds (200ms). A 5 second timeout is recommended. After a timeout, the same transaction can be sent again with the same TransactionId. If GiftRocker received the initial message and the response failed, the exact response will be resent. If GiftRocker did not receive the initial message, an appropriate new response will be sent. One retry is recommended. Following 2 failed attempts, a reverse should be called.
Data Types and Timezone
Currency values on requests are numeric with 2 decimal places. Currency values on responses are also numeric with 2 decimal places and represented as strings, e.g. “currentBalance”:”15.00″.
Date formats are yyyy-mm-dd hh:mm:ss, e.g. 2026-03-01 09:30:00. A gift card expiring at the end of the day would have a time of 23:59:59.
Timezones and currency codes are managed within GiftRocker and assumed static for each partner location.
Security
To guard against robots programmed to guess gift card references, GiftRocker requires Google’s CAPTCHA or equivalent protection on gift card interfaces. As an additional measure, governors can be setup to guard against failed protection, e.g. if GiftRocker detects more than 20 invalid gift card references within an hour for a merchant, that merchant’s account will be suspended for the hour and GiftRocker support will be notified.
Change Log
| Date | Update |
|---|---|
| 2/1/2026 | Version 2.0 created to support OAUTH as an authentication option |
| 3/1/2026 | Added begin and end dates to each Create, Activate, Add Value, Redeem and Get Balance |