openapi: 3.2.0 info: contact: email: x-series.api@lightspeedhq.com name: Lightspeed Developer Relations url: https://developers.retail.lightspeed.app description: Lightspeed Retail (X-Series) API. license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html termsOfService: https://developers.lightspeedhq.com/terms title: 2026-07 Gift Cards API version: 2026-07 servers: - url: https://{domain_prefix}.retail.lightspeed.app/api/2026-07 variables: domain_prefix: default: example description: Domain prefix of the store to be operated on security: - bearerAuth: [] tags: - description: Gift Card operations name: Gift Cards paths: /gift_cards: get: description: 'Returns a paginated list of gift cards. 🔒 Requires: `gift_cards:read` scope' operationId: ListGiftCards parameters: - description: Pagination cursor for reverse-chronological traversal. Pass the ID of a gift card to retrieve the next page of gift cards created before it, ordered from newest to oldest. in: query name: before schema: type: string - description: The maximum number of items to be returned in the response. Defaults to 1000. Maximum value is 1000. in: query name: page_size schema: default: 1000 maximum: 1000 type: integer - description: Find by gift card number. in: query name: card_number schema: type: string - description: Filter by gift card status. in: query name: status schema: enum: - ACTIVE - INACTIVE - REDEEMED - VOIDED - EXPIRED type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GiftCardCollection' description: The gift card list was successfully retrieved. summary: List gift cards tags: - Gift Cards post: description: 'Creates and activates a new gift card. The gift card will be created with one transaction with status "ACTIVATION" which contains the initial balance of the gift card. 🔒 Requires: `gift_cards:write:issue` scope' operationId: CreateGiftCard requestBody: content: application/json: schema: $ref: '#/components/schemas/GiftCardActivationParams' description: Create gift card parameters required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/GiftCardSingleton' description: Gift card successfully created. '422': content: application/json: schema: type: object description: Gift card has already been created and activated. summary: Create gift card tags: - Gift Cards /gift_cards/by_id/{id}: delete: description: 'Voids the gift card with the given id. The gift card balance will be set to zero and its status changed to "VOIDED". 🔒 Requires: `gift_cards:write:issue` scope' operationId: VoidGiftCardById parameters: - description: The id of the gift card to be voided. in: path name: id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GiftCardSingleton' description: Gift card successfully voided. '404': content: application/json: schema: type: object description: The gift card was not found. summary: Void gift card by id tags: - Gift Cards get: description: 'Finds and returns the gift card with the given id. Returns a 404 if the card does not exist. Within the gift card structure returned is the field `gift_card_transactions` which contains a list of all the transactions associated with the gift card. In this list you will see one or more of the following statuses: * "ACTIVATION" - This transaction type is added automatically when the gift card is created. The amount will be the initial balance that was loaded onto the gift card. * "REDEEMING" - This status indicates the customer used their gift card to pay for one or more items. The amount MUST be negative. * "IMPORTING" - You should only see this if gift cards were imported into the gift card system. * "VOIDING" - You will see this status if the gift card has been voided. Note that the balance of the card is set to zero when the gift card is voided. * "EXPIRING" - This transaction is added automatically when the gift card expires. Again note that the balance is set to zero when the gift card expires. * "REVERSING" - This status indicates that a given transaction was reversed. * "RELOADING" - This status means that more credit was loaded onto the gift card. 🔒 Requires: `gift_cards:read` scope' operationId: FindGiftCardById parameters: - description: The id of the gift card to find. in: path name: id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GiftCardSingleton' description: Gift card successfully retrieved. '404': content: application/json: schema: type: object description: Gift card was not found. summary: Find gift card by id tags: - Gift Cards /gift_cards/by_number/{card_number}: delete: description: 'Voids the gift card with the given card number. The gift card balance will be set to zero and its status changed to "VOIDED". 🔒 Requires: `gift_cards:write:issue` scope' operationId: VoidGiftCardByNumber parameters: - description: The number of the gift card to be voided. in: path name: card_number required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GiftCardSingleton' description: Gift card successfully voided. '404': content: application/json: schema: type: object description: The gift card was not found. summary: Void gift card by number tags: - Gift Cards get: description: 'Finds and returns the gift card with the given card number. Returns a 404 if the card does not exist. Within the gift card structure returned is the field `gift_card_transactions` which contains a list of all the transactions associated with the gift card. In this list you will see one or more of the following statuses: * "ACTIVATION" - This transaction type is added automatically when the gift card is created. The amount will be the initial balance that was loaded onto the gift card. * "REDEEMING" - This status indicates the customer used their gift card to pay for one or more items. The amount MUST be negative. * "IMPORTING" - You should only see this if gift cards were imported into the gift card system. * "VOIDING" - You will see this status if the gift card has been voided. Note that the balance of the card is set to zero when the gift card is voided. * "EXPIRING" - This transaction is added automatically when the gift card expires. Again note that the balance is set to zero when the gift card expires. * "REVERSING" - This status indicates that a given transaction was reversed. * "RELOADING" - This status means that more credit was loaded onto the gift card. 🔒 Requires: `gift_cards:read` scope' operationId: FindGiftCardByNumber parameters: - description: The number of the gift card to find. in: path name: card_number required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GiftCardSingleton' description: Gift card successfully retrieved. '404': content: application/json: schema: type: object description: Gift card was not found. summary: Find gift card by number tags: - Gift Cards /gift_cards/transactions/{transaction_id}: delete: description: 'Reverses the given transaction on the gift card. If the reversal is successful, a new transaction will be added to the gift card transactions with the status "REVERSING". Only transactions of type "REDEEMING" can be reversed. 🔒 Requires: `gift_cards:write:redeem` scope' operationId: ReverseGiftCardTransaction parameters: - description: The transaction id to be reversed for the gift card. in: path name: transaction_id required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GiftCardTransactionSingleton' description: The gift card transaction was successfully reversed. '400': content: application/json: schema: type: object description: Only transactions of type "REDEEMING" can be reversed. '404': content: application/json: schema: type: object description: A 404 is returned if the gift card transaction is not found. summary: Reverse gift card transaction tags: - Gift Cards get: description: 'Finds and returns the gift card associated with the given transaction id. Returns a 404 if the gift card with the given transaction id was not found. Supports an optional `system_id` query parameter to specify the source system (defaults to x-series, also supports e-series). 🔒 Requires: `gift_cards:read` scope' operationId: FindGiftCardByTransactionId parameters: - description: The transaction id of the gift card transaction to find. in: path name: transaction_id required: true schema: type: string - description: The source system identifier. Defaults to x-series if not specified. in: query name: system_id schema: default: x-series enum: - x-series - e-series type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GiftCardSingleton' description: The gift card with this transaction id was successfully found. '404': content: application/json: schema: type: object description: The gift card associated with the transaction id was not found. summary: Find gift card by transaction id tags: - Gift Cards /gift_cards/{card_number}/transactions: post: description: 'Creates a new gift card transaction on the specified gift card. The request body requires the `type`, `amount`, and `client_id` fields. The `type` determines what sort of transaction it is. * "REDEEMING" - Use this type when you want to redeem a certain amount from the gift card balance. The amount MUST be negative. If you want to add an amount to the balance use the "RELOADING" type. * "RELOADING" - Use this type when you load a new amount onto a gift card. If the gift card does not have enough credit to honour the transaction a 422 HTTP status code will be returned. ## Idempotency Please populate the client_id field with a unique transaction identifier, to ensure that the transaction is safe from double-submit problems. See [the tutorial](/docs/gift_cards#idempotency) for more information. 🔒 Requires: `gift_cards:write:redeem` scope' operationId: CreateGiftCardTransaction parameters: - description: The number of the gift card to add the transaction to. in: path name: card_number required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/GiftCardTransactionParams' description: Create gift card transaction parameters required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/GiftCardTransactionSingleton' description: Gift card transaction successfully created. '404': content: application/json: schema: type: object description: The gift card was not found. '422': content: application/json: schema: type: object description: Gift card does not have sufficient balance. summary: Create a gift card transaction tags: - Gift Cards /gift_cards/{number}: delete: description: 'Void the given gift card. 🔒 Requires: `gift_cards:write:issue` scope' operationId: VoidGiftCard parameters: - description: The number of the gift card to be voided. in: path name: number required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GiftCard' description: Gift card successfully voided. '404': content: application/json: schema: type: object description: The gift card was not found. summary: Void gift card tags: - Gift Cards get: description: 'Finds and returns the given card number. Returns a 404 if the card does not exist. Within the gift card structure returned is the field gift__card__transactions which contains a list of all the transactions associated with the gift card. In this list you will see one or more of the following statuses: * "ACTIVATION" - This transaction type is added automatically when the gift card is created. The amount will be the initial balance that was loaded onto the gift card. * "REDEEMING" - This status indicates the customer used their gift card to pay for one or more items. The amount MUST be negative. * "IMPORTING" - You should only see this if gift cards were imported into the gift card system. * "VOIDING" - You will see this status if the gift card has been voided. Note that the balance of the card is set to zero when the gift card is voided. * "EXPIRING" - This transaction is added automatically when the gift card expires. Again note that the balance is set to zero when the gift card expires. * "REVERSING" - This status indicates that a given transaction was reversed. * "RELOADING" - This status means that more credit was loaded onto the gift card. 🔒 Requires: `gift_cards:read` scope' operationId: FindGiftCard parameters: - description: The number of the gift card to find. in: path name: number required: true schema: type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/GiftCard' description: Gift card successfully retrieved. '404': content: application/json: schema: type: object description: Gift card was not found. summary: Find gift card tags: - Gift Cards components: schemas: GiftCardTransactionSingleton: description: A single gift card transaction response. properties: data: $ref: '#/components/schemas/GiftCardTransaction' required: - data title: Gift Card Transaction Response type: object GiftCardSingleton: description: A single gift card response. properties: data: $ref: '#/components/schemas/GiftCard' required: - data title: Gift Card Response type: object GiftCardTransactionParams: description: The parameters for creating a new gift card transaction. properties: amount: description: The transaction amount. Must be negative for REDEEMING transactions and positive for RELOADING transactions. type: string client_id: description: A unique transaction identifier for idempotency. The client must provide this and is normally the transaction id from the client system. type: string expires_at: description: Optional new expiry date for the gift card in YYYY-MM-DD format. Can be used to extend the gift card's expiry when reloading. type: string time_zone: description: The timezone to use when interpreting the `expires_at` date (e.g. "Pacific/Auckland"). See the list of tz database time zones for valid values. type: string type: description: The type of the transaction. enum: - REDEEMING - RELOADING type: string user_id: description: The ID of the user creating the transaction. If omitted, the authenticated user will be used. type: string required: - amount - client_id - type title: Gift Card Transaction Parameters type: object GiftCardCollection: description: A paginated list of gift cards. properties: data: description: An array of Gift Cards. items: $ref: '#/components/schemas/GiftCard' type: array required: - data title: Gift Card Collection type: object GiftCardActivationParams: description: The parameters for creating and activating a new gift card. properties: amount: description: The initial balance to be loaded onto the gift card. Represented as a string for precision (e.g. "100.00"). example: '10.00' type: string expires_at: description: The expiry date of the gift card in YYYY-MM-DD format. If omitted, the expiry will be calculated based on the validity period configured in the Lightspeed Retail UI, or will be null if expiry is not enabled. type: string number: description: The unique number to assign to the gift card. type: string time_zone: description: The timezone to use when interpreting the `expires_at` date (e.g. "Pacific/Auckland"). See the list of tz database time zones for valid values. type: string user_id: description: The ID of the user creating the gift card. If omitted, the authenticated user will be used. type: string required: - amount - number title: Gift Card Activation Parameters type: object GiftCardTransaction: description: A gift card transaction with the amount represented as a string for precision. properties: amount: description: The transaction amount, represented as a string for precision. type: string client_id: description: The client id is a unique transaction identifier. The client must provide this and is normally the transaction id from the client system. type: - string - 'null' created_at: description: The creation timestamp in UTC. type: string id: description: Auto-generated object ID. type: string source: description: The source of the transaction. type: - string - 'null' source_id: description: The source id is a unique identifier for the transaction in the source system. type: - string - 'null' type: description: The type of transaction. enum: - ACTIVATION - REDEEMING - IMPORTING - VOIDING - EXPIRING - REVERSING - RELOADING type: string user_id: description: The user id associated with the transaction. type: string title: Gift Card Transaction type: object GiftCard: description: A gift card with monetary values represented as strings for precision. properties: balance: description: The balance of the gift card, represented as a string for precision. type: string created_at: description: The creation timestamp in UTC. type: string expires_at: description: The expiry timestamp in UTC. type: - string - 'null' gift_card_transactions: description: An array of Gift Card Transactions. items: $ref: '#/components/schemas/GiftCardTransaction' type: array id: description: Auto-generated object ID. type: string number: description: The gift card number. type: string sale_id: description: The ID of the sale associated with the gift card creation, if it was created through a register sale. Null if the gift card was created directly via the API. type: - string - 'null' sale_source: description: The source system where the gift card was created (e.g. x-series, e-series). type: string status: description: The gift card status. enum: - ACTIVE - INACTIVE - REDEEMED - VOIDED - EXPIRED type: string total_redeemed: description: The amount redeemed with this gift card, represented as a string for precision. type: string total_sold: description: The amount loaded onto this gift card during activation or reloading, represented as a string for precision. type: string title: Gift Card type: object securitySchemes: bearerAuth: description: Bearer Token for API authentication. scheme: bearer type: http externalDocs: description: List of tz database time zones url: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones