Lightspeed Commerce

Lightspeed Commerce Gift Cards API

Gift Card operations

GitHub OpenAPI
Business capability
Tender and Payment Acceptance Management BC-2320.20

Operations 11

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /gift_cards List gift cards · List gift cards #
Ask an LLM
“Which gift cards have been issued by my store?”
“Can I list only gift cards with a particular status, like voided ones?”
Tell an agent
List all gift cards with status {status}.
Page through gift cards issued before gift card {before}.
POST /gift_cards Issue and activate a new gift card · Create gift card #
Ask an LLM
“How do I sell a new gift card with a starting balance?”
“Can I set an expiry date when issuing a gift card?”
Tell an agent
Issue gift card number {number} with a balance of {amount}.
Activate gift card {number} loaded with {amount} that expires on {expires}.
DELETE /gift_cards/by_id/{id} Void a gift card by its internal ID · Void gift card by id #
Ask an LLM
“Can I cancel a gift card using its internal ID so its balance goes to zero?”
“What happens to the balance when a gift card is voided by ID?”
Tell an agent destructive · confirm first
Void the gift card with internal ID {id}.
Zero out and void gift card record {id}.
GET /gift_cards/by_id/{id} Look up a gift card by its internal ID · Find gift card by id #
Ask an LLM
“Can I fetch a gift card and its transaction history using its internal ID rather than the card number?”
“What does a gift card record show about activations, redemptions and reloads?”
Tell an agent
Get the gift card with internal ID {id}.
Show the balance and transactions of gift card ID {id}.
DELETE /gift_cards/by_number/{card_number} Void a gift card by card number · Void gift card by number #
Ask an LLM
“How do I void a lost gift card using the number printed on it?”
“Does voiding a card by its number set its status to VOIDED?”
Tell an agent destructive · confirm first
Void gift card number {card_number} through the by-number endpoint.
Cancel the gift card printed with number {card_number} and zero its balance.
GET /gift_cards/by_number/{card_number} Look up a gift card by card number · Find gift card by number #
Ask an LLM
“What's the remaining balance on the gift card a customer just handed me?”
“Can I see every redemption made on a gift card by its printed number?”
Tell an agent
Look up gift card {card_number} using the by-number endpoint.
Check the balance of gift card number {card_number}.
DELETE /gift_cards/transactions/{transaction_id} Reverse a gift card redemption · Reverse gift card transaction #
Ask an LLM
“Can I undo a gift card redemption that was charged by mistake?”
“Which gift card transactions are allowed to be reversed?”
Tell an agent destructive · confirm first
Reverse gift card transaction {transaction}.
Undo the redemption recorded as transaction {transaction}.
GET /gift_cards/transactions/{transaction_id} Find the gift card behind a transaction · Find gift card by transaction id #
Ask an LLM
“Which gift card was used in a given gift card transaction?”
“Can I look up a transaction that came from the e-series system instead of x-series?”
Tell an agent
Find the gift card for transaction {transaction}.
Find the gift card for transaction {transaction} in source system {system}.
POST /gift_cards/{card_number}/transactions Redeem or reload a gift card · Create a gift card transaction #
Ask an LLM
“How do I take money off a gift card balance at checkout?”
“Can I top up an existing gift card and extend its expiry at the same time?”
Tell an agent
Create a {type} transaction of {amount} on gift card {card_number} with client reference {client}.
Reload gift card {card_number} with {amount}, reference {client}.
DELETE /gift_cards/{number} Void a gift card (legacy number path) · Void gift card #
Ask an LLM
“Is there an older endpoint to void a gift card directly under /gift_cards by number?”
“Can I still void a card through the plain gift card number path?”
Tell an agent destructive · confirm first
Void gift card {number} using the legacy plain number path.
Void card {number} with the older gift card endpoint.
GET /gift_cards/{number} Look up a gift card (legacy number path) · Find gift card #
Ask an LLM
“Is there an older endpoint that looks up a gift card directly under /gift_cards by number?”
“Can I read a gift card's transactions through the plain gift card number path?”
Tell an agent
Fetch gift card {number} using the legacy plain number path.
Read gift card {number} and its transactions from the legacy route.

Documentation

📖
Documentation
https://x-series-api.lightspeedhq.com/docs/introduction
📖
APIReference
https://x-series-api.lightspeedhq.com/reference
📖
GettingStarted
https://x-series-api.lightspeedhq.com/docs/quick_start
📖
Documentation
https://api-portal.lsk.lightspeed.app/
📖
APIReference
https://api-docs.lsk.lightspeed.app/
📖
GettingStarted
https://api-portal.lsk.lightspeed.app/quick-start/intro

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/lightspeed/refs/heads/main/openapi/lightspeed-gift-cards-api-openapi.yml

Other Resources

🔗
ChangeLog
https://x-series-api.lightspeedhq.com/changelog
🔗
LLMsTxt
https://raw.githubusercontent.com/api-evangelist/lightspeed/refs/heads/main/llms/lightspeed-llms.txt
🔗
SignUp
https://developers.retail.lightspeed.app/register
🔗
ChangeLog
https://api-docs.lsk.lightspeed.app/changes

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/lightspeed:lightspeed-gift-cards-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

lightspeed-gift-cards-api-openapi.yml Raw ↑ 
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 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
    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
    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
    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
    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
    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
  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