Gift Cards
Gift Cards - BETA
The Gift Cards API can be used to query, create, and manage Lightspeed Retail (X-Series) Gift Cards and their balances.
We recommend that you first familiarise yourself with Lightspeed Retail (X-Series)'s Gift Card functionality by reviewing the available documentation in our help centre.
One of the ways you can use the Gift Cards API is to create an omni-channel experience for your customers so that Lightspeed Retail (X-Series) Gift Cards can be purchased and used wherever they prefer to shop - on your website or in-store.
If you'd like to use the Gift Card API to facilitate this, there are a number of caveats you need to be aware of.
When designing your own omni-channel experience using our Gift Cards API, you need to first make some decisions about where you want the System of Record for balances to be held. Our Gift Cards API will allow you to use Lightspeed Retail (X-Series) as this System of Record so that you can accept payment for Lightspeed Retail (X-Series) Gift Cards online and then those Gift Cards can be pushed through to Lightspeed Retail (X-Series) which will allow them to be used at your in-store locations that use Lightspeed Retail (X-Series).
You can also then use the Gift Card API to accept Lightspeed Retail (X-Series) Gift Cards as a payment method online by debiting the associated Gift Card using the APIs described here.
Should you choose to use this method, you need to ensure that your online store and physical store's gift cards use only one source of truth for transactions and balances. To do this, you can collect payment for a Gift Card online but you shouldn't hold its balance online - the card should be created in Lightspeed Retail (X-Series) using the API and transactions on the card should use the API to be redeemed and, if desired, reloaded.
You may also want to explore using Gift Cards solely as a payment method - in this case, exploring our payments tutorials will allow you to build an integration with an external system that will manage Gift Cards.
The methods documented below directly manipulate Gift Cards in Lightspeed Retail (X-Series) and do not raise register sales for them. This means that this method does not associate a sale_id or payment method with the transaction. You might want to use the below methods only if you are satisfied that you can account for an reconcile these transactions separately. The below methods won't trigger any sale webhooks so you'll need to poll the /gift_cards endpoint to ensure that the gift cards created in this manner are reconciled.
If the methods below don't suit your use case and you'd like to be able to raise Lightspeed Retail (X-Series) sales and associate Lightspeed Retail (X-Series) payment methods with Gift Cards sold and used via the API, please contact us on [email protected] for further information.
Idempotency
Ensuring that transactions are unique and preventing the same transaction from being made more than once is a core component of ensuring your omni-channel solution works as expected.
Idempotency is achieved for Gift Card transactions by the client supplying a client_id, this can be an external reference number, transaction ID or even just a UUID. It needs to be unique per transaction and must be provided with all reloading and redeeming 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, simply and safely.
Create a Gift Card in Lightspeed Retail (X-Series)
Creating a Gift Card is performed by a POST to the /api/2.0/gift_cards endpoint. You can provide an amount, number and optionally a YYYY-MM-DD expiry_date as follows. If you don't include an expiry date, it will either be calculated based on the validity period set in the Lightspeed Retail (X-Series) UI, or it will be null if you haven't enabled expiry:
{
"amount": 100,
"number": "55552314HCO",
"expires_at": "2020-09-19"
}
You'll get a response as follows:
{
"id": "AgSGHxPz1-U=",
"number": "55552314HCO",
"sale_id": null,
"created_at": "2019-09-18T23:09:39+00:00",
"expires_at": "2020-09-19T23:59:59+00:00",
"gift_card_transactions": [
{
"id": "AgSGHxPz1-Y=",
"amount": 100.0000,
"type": "ACTIVATION",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-18T23:09:39+00:00",
"client_id": null
}
],
"status": "ACTIVE",
"balance": 100.0000,
"total_sold": 100.0000,
"total_redeemed": 0.0000
}
If this Gift Card already exists in Lightspeed Retail (X-Series), you'll receive a 422 status.
Note that transactions made in this manner won't show in the Sales Ledger and won't be linked to an associated sale. The Gift Cards will however show in your Gift Cards Report in Lightspeed Retail (X-Series).
Should you want to reconcile the above with an external system, you can do so using the id field or the number of the card.
Check the Transactions and Balance of a Gift Card in Lightspeed Retail (X-Series)
You can find the transactions and balance of an existing Gift Card with a GET request to the /api/2.0/gift_cards/:number endpoint.
For the above Gift Card I created, this will be a GET to /api/2.0/gift_cards/55552314HCO and will return the following response:
{
"id": "AgSGHxPz1-U=",
"number": "55552314HCO",
"sale_id": null,
"created_at": "2019-09-18T23:09:39+00:00",
"expires_at": "2020-09-18T23:59:59+00:00",
"gift_card_transactions": [
{
"id": "AgSGHxPz1-Y=",
"amount": 100.0000,
"type": "ACTIVATION",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-18T23:09:39+00:00",
"client_id": null
}
],
"status": "ACTIVE",
"balance": 100.0000,
"total_sold": 100.0000,
"total_redeemed": 0.0000
}
List the Balances and Transactions for all Gift Cards in Lightspeed Retail (X-Series)
A GET request to the /api/2.0/gift_cards endpoint will list the balances and transactions for all Gift Cards in your Lightspeed Retail (X-Series) account. This includes all voided and expired cards.
Redeem (Debit) a Gift Card in Lightspeed Retail (X-Series)
All Gift Card transactions are performed using the /api/2.0/gift_cards/:number/transactions endpoint using different type fields to represent the different transaction types. A debit is a REDEEMING type and must be a negative amount. You can pass a client_id if you want to reference an external transaction - say an e-commerce transaction id or some other external identifier.
My Gift Card's number is 55552314HCO so the below example uses the /api/2.0/gift_cards/55552314HCO/transactions endpoint to debit the Gift Card I created above by $10.00 and associates the client_id of 84abedcd-3ab0-4b7a-9c0d-5caf2e779993 with the transaction. The client_id is used similar to an idempotency key so posting a request that uses the same client_id will result in only the original transaction being persisted.
{
"amount": -10.00,
"type": "REDEEMING",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993"
}
You'll get a response as follows:
{
"id": "AgSG-qHD1Bs=",
"amount": -10.0000,
"type": "REDEEMING",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-18T23:24:39+00:00",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993"
}
The complete transaction list of the Gift Card will then look as follows:
{
"id": "AgSFaGh2VlE=",
"number": "55552314HCO",
"sale_id": "02e60bb7-8de1-11e9-f4c2-da67a61057bd",
"created_at": "2019-09-18T22:57:12+00:00",
"expires_at": null,
"gift_card_transactions": [
{
"id": "AgSFaGh2VlI=",
"amount": 100.0000,
"type": "ACTIVATION",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-18T22:57:12+00:00",
"client_id": null
},
{
"id": "AgSG-qHD1Bs=",
"amount": -10.0000,
"type": "REDEEMING",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-18T23:24:39+00:00",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993"
}
],
"status": "ACTIVE",
"balance": 90.0000,
"total_sold": 100.0000,
"total_redeemed": -10.0000
}
If you try to debit a Gift Card for more than its available balance, you'll get a 422 response as below:
{
"errors": [
{
"status_code": "422",
"messages": [
"Gift Card does not have sufficient balance"
]
}
]
}
You can therefore use this functionality to accept payment for online transactions using Lightspeed Retail (X-Series) Gift Cards. Depending on whether you want to indicate to the user the balance of their card, you can either retrieve the transactions and return the balance, or you can just try to debit a payment for a given amount and the Lightspeed Retail (X-Series) API will tell you whether or not the transaction was successful.
Load (Credit) a Gift Card in Lightspeed Retail (X-Series)
Crediting a Gift Card is referred to as RELOADING in Lightspeed Retail (X-Series). You can credit (ie. add funds) to a Gift Card by setting the type field to "RELOADING" and by setting the amount field to the amount you wish to add to the card.
As with the redeem example, you must pass a transaction ID in the client_id field to ensure idempotency.
The example below uses the /api/2.0/gift_cards/55552314HCO/transactions endpoint to add $150 to the card and provides a client_id of dde78a68-6849-435c-b194-b8743f8328f4
{
"amount": 150.00,
"type": "RELOADING",
"client_id": "dde78a68-6849-435c-b194-b8743f8328f4"
}
You'll get a response as follows:
{
"id": "AgSPkyfMkcM=",
"amount": 150.0000,
"type": "RELOADING",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-19T01:54:52+00:00",
"client_id": "dde78a68-6849-435c-b194-b8743f8328f4"
}
The complete transaction list of the Gift Card will then look as follows:
{
"id": "AgSFaGh2VlE=",
"number": "55552314HCO",
"sale_id": "02e60bb7-8de1-11e9-f4c2-da67a61057bd",
"created_at": "2019-09-18T22:57:12+00:00",
"expires_at": null,
"gift_card_transactions": [
{
"id": "AgSFaGh2VlI=",
"amount": 100.0000,
"type": "ACTIVATION",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-18T22:57:12+00:00",
"client_id": null
},
{
"id": "AgSG-qHD1Bs=",
"amount": -10.0000,
"type": "REDEEMING",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-18T23:24:39+00:00",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993"
},
{
"id": "AgSPkyfMkcM=",
"amount": 150.0000,
"type": "RELOADING",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-19T01:54:52+00:00",
"client_id": "dde78a68-6849-435c-b194-b8743f8328f4"
},
],
"status": "ACTIVE",
"balance": 240.0000,
"total_sold": 250.0000,
"total_redeemed": -10.0000
}
Reversing a Gift Card Transaction
Only transactions of the type REDEEMING can be reversed. To reverse a Gift Card redemption transaction, you need to use a DELETE request against the transactions id.
If I want to reverse the $10 redemption transaction I created in the Redeem a transaction example above, it has an id of AgSG-qHD1Bs= so I would send a DELETE request to /api/2.0/gift_cards/transactions/AgSG-qHD1Bs=
I'll then get the following response:
{
"id": "AgSPji1skcA=",
"amount": 10.0000,
"type": "REVERSING",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-19T01:54:32+00:00",
"client_id": null
}
Reversing transactions could be useful if you are accepting a split payment across a Credit Card and Gift Card online. You'd debit the Gift Card with the split amount but let's say the Credit Card payment gets declined, you could then immediately reverse the Gift Card transaction. Reversing transactions are also useful in cases of refunds and similar scenarios.
The associated transaction will then be shown in the complete transaction log of the Gift Card
Finding a Gift Card using a Transaction ID
If you have the id of a specific Gift Card transaction (eg. the above AgSPji1skcA=), you can use that to get the full transaction log of the Gift Card that transaction belongs to.
A GET request to /api/2.0/gift_cards/transactions/AgSG-qHD1Bs= will return the complete transaction list for the card as in the examples above.
Note that this can only be used to search for gift_card_transactions, not an actual Gift Card id.
Deleting (Voiding) a Gift Card
A Gift Card can't be permanently deleted but it can be voided by sending a DELETE request to the /api/2.0/gift_cards/:number endpoint
To void the above Gift Card with the number 55552314HCO, send a DELETE to /api/2.0/gift_cards/55552314HCO
This will return the transaction log of the Gift Card. The number of the card will have -VOIDED- appended to it and the date/time of when it was voided as below. The status of the Gift Card will be "VOIDED" and its balance will be set to 0.
{
"id": "AgSFaGh2VlE=",
"number": "55552314HCO-VOIDED-2019-09-19-02-29-30",
"created_at": "2019-09-18T22:57:12+00:00",
"expires_at": null,
"gift_card_transactions": [
{
"id": "AgSFaGh2VlI=",
"amount": 100.0000,
"type": "ACTIVATION",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-18T22:57:12+00:00",
"client_id": null
},
{
"id": "AgSG-qHD1Bs=",
"amount": -10.0000,
"type": "REDEEMING",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-18T23:24:39+00:00",
"client_id": "84abedcd-3ab0-4b7a-9c0d-5caf2e779993"
},
{
"id": "AgSPkyfMkcM=",
"amount": 150.0000,
"type": "RELOADING",
"user_id": "02e60bb7-8d62-11e9-f4c2-b314f6a36e4f",
"created_at": "2019-09-19T01:54:52+00:00",
"client_id": "dde78a68-6849-435c-b194-b8743f8328f4"
},
],
"status": "VOIDED",
"balance": 0.0000,
"total_sold": 250.0000,
"total_redeemed": -10.0000
}
Updated 17 days ago