Gift Cards
The Gift Cards API supports querying, creating, and managing Lightspeed Retail (X-Series) Gift Cards and their balances.
Before integrating, review Lightspeed Retail (X-Series) Gift Card behavior in the help centre.
The Gift Cards API can support an omni-channel experience where Lightspeed Retail (X-Series) Gift Cards are purchased and used across channels, including external websites and in-store.
When implementing this model, several caveats apply.
-
For a custom omni-channel implementation, define where the balance System of Record resides. The Gift Cards API supports Lightspeed Retail (X-Series) as the System of Record so payments can be accepted online and cards can be synchronized for in-store use at Lightspeed Retail (X-Series) locations.
-
The Gift Card API can also support online acceptance of Lightspeed Retail (X-Series) Gift Cards by debiting the associated Gift Card via the endpoints described below. When using this method, online and physical-store Gift Card flows should share a single source of truth for balances and transactions. For example, payment for a Gift Card can be collected online while the balance is maintained in Lightspeed Retail (X-Series): create the card through the API, then redeem and reload it through the API.
-
Gift Cards can also be used solely as a payment method. For this pattern, see the payments tutorials for integration guidance with an external system managing Gift Cards.
-
The methods documented below directly manipulate Gift Cards in Lightspeed Retail (X-Series) and do not create register sales. As a result, transactions created this way are not associated with a
sale_idor payment method. These methods are most suitable when separate accounting and reconciliation are in place. As these methods do not trigger sale webhooks, poll the/gift_cardsendpoint to reconcile Gift Cards created in this manner.
Idempotency
Ensuring transactions are unique and preventing duplicate transaction creation is a core part of a reliable omni-channel implementation.
Idempotency for Gift Card transactions is achieved by supplying a client_id (for example, an external reference number, transaction ID, or UUID). This value must be unique per transaction and must be provided for all reload and redeem transactions.
When Lightspeed Retail (X-Series) receives a Gift Card transaction, it checks the client_id to see if it has already been applied. If a second transaction is posted with the same client_id and transaction details, it will not be applied, and that previous transaction will be returned in its place. In this way, a client application can implement retries safely.
Create a Gift Card in Lightspeed Retail (X-Series)
Create a Gift Card with a POST request to /api/{date-version}/gift_cards. The request may include amount, number, and optionally expires_at in ISO-8601 format (YYYY-MM-DDTHH:MM:SS+00:00). Gift Card expiry must be enabled and configured in the Lightspeed Retail (X-Series) UI. If expires_at is omitted and Gift Card expiration is configured, it will be calculated from the validity period configured in the Lightspeed Retail (X-Series) UI.
{
"amount": 100,
"number": "55552314HCO",
"expires_at": "2020-09-19T23:59:59+00:00"
}Example response (201 Created):
{
"data": {
"id": "b88b6b9a-1b7f-4f97-87a7-3e0f0c6b7f3a",
"number": "55552314HCO",
"balance": "100.00",
"total_sold": "100.00",
"total_redeemed": "0.00",
"status": "ACTIVE",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:36:41+00:00",
"expires_at": "2026-09-19T23:59:59+00:00",
"sale_id": null,
"sale_source": "x-series",
"gift_card_transactions": [
{
"id": "BQLIjl9UoAE=",
"amount": "100.00",
"type": "ACTIVATION",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:36:41+00:00",
"client_id": null,
"source": "x-series",
"source_id": "361071433953353729"
}
]
}
}If the Gift Card already exists in Lightspeed Retail (X-Series), the API returns an error response.
Transactions created this way do not appear in the sales history and are not linked to an associated sale. The Gift Cards still appear in the Gift Cards Report in Lightspeed Retail (X-Series).
For reconciliation with an external system, use either the Gift Card id or number.
Check the Transaction History and Balance of a Gift Card in Lightspeed Retail (X-Series)
Retrieve transactions and current balance for an existing Gift Card with GET /api/{date-version}/gift_cards/by_number/{card_number}.
For the Gift Card shown above, a request to /api/{date-version}/gift_cards/by_number/55552314HCO returns:
{
"data": {
"id": "b88b6b9a-1b7f-4f97-87a7-3e0f0c6b7f3a",
"number": "55552314HCO",
"balance": "100.00",
"total_sold": "100.00",
"total_redeemed": "0.00",
"status": "ACTIVE",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:36:41+00:00",
"expires_at": "2026-09-19T23:59:59+00:00",
"sale_id": null,
"sale_source": "x-series",
"gift_card_transactions": [
{
"id": "BQLIjl9UoAE=",
"amount": "100.00",
"type": "ACTIVATION",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:36:41+00:00",
"client_id": null,
"source": "x-series",
"source_id": "361071433953353729"
}
]
}
}List the Balances and Transaction History for all Gift Cards in Lightspeed Retail (X-Series)
A GET request to /api/{date-version}/gift_cards lists balances and transaction history for all Gift Cards in a Lightspeed Retail (X-Series) account, including voided and expired cards.
Redeem (Debit) a Gift Card in Lightspeed Retail (X-Series)
All Gift Card transactions use /api/{date-version}/gift_cards/{card_number}/transactions and are distinguished by type. A debit uses type: "REDEEMING" and must use a negative amount. A client_id must be supplied to reference the external transaction (for example, an e-commerce transaction ID) and ensure idempotency.
The following example uses /api/{date-version}/gift_cards/55552314HCO/transactions to debit the Gift Card above by $10.00 and associates the transaction with client_id: 84abedcd-3ab0-4b7a-9c0d-5caf2e779993. The client_id behaves as an idempotency key: resubmitting the same request with the same client_id does not create a duplicate transaction.
{
"amount": -10.00,
"type": "REDEEMING",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993"
}Example response (201 Created):
{
"data": {
"id": "BQLIw66spAE=",
"amount": "-10.00",
"type": "REDEEMING",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:40:19+00:00",
"updated_at": "2026-03-26T15:40:19+00:00",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993",
"source": "x-series",
"source_id": "361071662917788673"
}
}The Gift Card transaction list then appears as follows:
{
"data": {
"id": "b88b6b9a-1b7f-4f97-87a7-3e0f0c6b7f3a",
"number": "55552314HCO",
"balance": "90.00",
"total_sold": "100.00",
"total_redeemed": "-10.00",
"status": "ACTIVE",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:40:19+00:00",
"expires_at": "2026-09-19T23:59:59+00:00",
"sale_id": null,
"sale_source": "x-series",
"gift_card_transactions": [
{
"id": "BQLIjl9UoAE=",
"amount": "100.00",
"type": "ACTIVATION",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:36:41+00:00",
"client_id": null,
"source": "x-series",
"source_id": "361071433953353729"
},
{
"id": "BQLIw66spAE=",
"amount": "-10.00",
"type": "REDEEMING",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:40:19+00:00",
"updated_at": "2026-03-26T15:40:19+00:00",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993",
"source": "x-series",
"source_id": "361071662917788673"
}
]
}
}If a debit exceeds the available balance, the API returns 422:
{
"errors": [
{
"status_code": "422",
"messages": [
"Gift Card does not have sufficient balance"
]
}
]
}This behavior supports online payment acceptance using Lightspeed Retail (X-Series) Gift Cards. Implementations can either retrieve transactions and display the balance, or attempt a debit for a specific amount and rely on the API response to determine success.
Load (Credit) a Gift Card in Lightspeed Retail (X-Series)
Crediting a Gift Card is represented by RELOADING in Lightspeed Retail (X-Series). Add funds by setting type to "RELOADING" and amount to the value to be added.
As with redemption, pass a transaction ID in client_id to ensure idempotency.
The example below uses /api/{date-version}/gift_cards/55552314HCO/transactions to add $150 to the card and provides client_id: dde78a68-6849-435c-b194-b8743f8328f4.
{
"amount": 150.00,
"type": "RELOADING",
"client_id": "dde78a68-6849-435c-b194-b8743f8328f4"
}Example response (201 Created):
{
"data": {
"id": "BQLJAA6spAI=",
"amount": "150.00",
"type": "RELOADING",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:45:04+00:00",
"updated_at": "2026-03-26T15:45:04+00:00",
"client_id": "dde78a68-6849-435c-b194-b8743f8328f4",
"source": "x-series",
"source_id": "361071901552513026"
}
}The Gift Card transaction list then appears as follows:
{
"data": {
"id": "b88b6b9a-1b7f-4f97-87a7-3e0f0c6b7f3a",
"number": "55552314HCO",
"balance": "240.00",
"total_sold": "250.00",
"total_redeemed": "-10.00",
"status": "ACTIVE",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:45:04+00:00",
"expires_at": "2026-09-19T23:59:59+00:00",
"sale_id": null,
"sale_source": "x-series",
"gift_card_transactions": [
{
"id": "BQLIjl9UoAE=",
"amount": "100.00",
"type": "ACTIVATION",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:36:41+00:00",
"client_id": null,
"source": "x-series",
"source_id": "361071433953353729"
},
{
"id": "BQLIw66spAE=",
"amount": "-10.00",
"type": "REDEEMING",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:40:19+00:00",
"updated_at": "2026-03-26T15:40:19+00:00",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993",
"source": "x-series",
"source_id": "361071662917788673"
},
{
"id": "BQLJAA6spAI=",
"amount": "150.00",
"type": "RELOADING",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:45:04+00:00",
"updated_at": "2026-03-26T15:45:04+00:00",
"client_id": "dde78a68-6849-435c-b194-b8743f8328f4",
"source": "x-series",
"source_id": "361071901552513026"
}
]
}
}Reversing a Gift Card Transaction
Only REDEEMING transactions can be reversed. Reverse a Gift Card redemption by sending a DELETE request for the transaction id.
For example, to reverse the $10 redemption transaction shown above (id: BQLIw66spAE=), send DELETE /api/{date-version}/gift_cards/transactions/BQLIw66spAE=.
Example response:
{
"data": {
"id": "BQLJH56spAM=",
"amount": "10.00",
"type": "REVERSING",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:48:12+00:00",
"updated_at": "2026-03-26T15:48:12+00:00",
"client_id": null,
"source": "x-series",
"source_id": "361072091083460611"
}
}Reversing transactions is useful in scenarios such as split payments across Credit Card and Gift Card channels. For example, if the Gift Card portion is debited but the Credit Card payment fails, the Gift Card transaction can be reversed immediately. This approach is also applicable for refunds and similar flows.
The reversing transaction is then visible in the Gift Card transaction log.
Finding a Gift Card using a Transaction ID
If the id of a Gift Card transaction is available (for example, BQLIw66spAE=), it can be used to retrieve the full transaction log for the corresponding Gift Card.
A GET request to /api/{date-version}/gift_cards/transactions/BQLIw66spAE= returns the Gift Card and its full transaction history.
This endpoint accepts the transaction id returned within gift_card_transactions, not the Gift Card id.
Deleting (Voiding) a Gift Card
A Gift Card cannot be permanently deleted, but it can be voided with DELETE /api/{date-version}/gift_cards/by_number/{card_number}. Voided gift card numbers cannot be reused, and the Gift Card is no longer valid for redemption or reloading.
To void the Gift Card above (number: 55552314HCO), send DELETE /api/{date-version}/gift_cards/by_number/55552314HCO.
This returns the Gift Card transaction log. The card status is set to "VOIDED", and balance is set to 0.
{
"data": {
"id": "b88b6b9a-1b7f-4f97-87a7-3e0f0c6b7f3a",
"number": "55552314HCO",
"balance": "0.00",
"total_sold": "250.00",
"total_redeemed": "-10.00",
"status": "VOIDED",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:52:27+00:00",
"expires_at": "2026-09-19T23:59:59+00:00",
"sale_id": null,
"sale_source": "x-series",
"gift_card_transactions": [
{
"id": "BQLIjl9UoAE=",
"amount": "100.00",
"type": "ACTIVATION",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:36:41+00:00",
"updated_at": "2026-03-26T15:36:41+00:00",
"client_id": null,
"source": "x-series",
"source_id": "361071433953353729"
},
{
"id": "BQLIw66spAE=",
"amount": "-10.00",
"type": "REDEEMING",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:40:19+00:00",
"updated_at": "2026-03-26T15:40:19+00:00",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993",
"source": "x-series",
"source_id": "361071662917788673"
},
{
"id": "BQLJAA6spAI=",
"amount": "150.00",
"type": "RELOADING",
"user_id": "0a4c4486-f925-11ee-fc19-d1b2735216b2",
"created_at": "2026-03-26T15:45:04+00:00",
"updated_at": "2026-03-26T15:45:04+00:00",
"client_id": "dde78a68-6849-435c-b194-b8743f8328f4",
"source": "x-series",
"source_id": "361071901552513026"
}
]
}
}Updated 6 days ago