Lightspeed Commerce Gift Cards API

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