Lightspeed Commerce

Lightspeed Commerce Store Credits API

Store Credit operations

GitHub OpenAPI

Operations 9

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 /store_credits List store credit customers and recent activity · Get store credit usage for the store #
Ask an LLM
“Which customers have store credit and what have they done with it lately?”
“Can I page through all store credit balances with recent transactions?”
Tell an agent
List store credit customers with balances and their latest transactions.
Show store credit usage for the store, {page_size} customers per page.
POST /store_credits/balances-bulk Get store credit balances in bulk · Bulk Store Credit customers balances #
Ask an LLM
“How do I get just the balances of all store credit customers in one call?”
“Is there a bulk lookup that skips the transaction history?”
Tell an agent
Fetch store credit balances in bulk without transaction history.
Get only the balance for every store credit customer.
POST /store_credits/bulk Get store credit customers and history in bulk · Bulk Store Credit customers #
Ask an LLM
“Can I bulk-fetch store credit customers with their recent transaction lists?”
“What does the bulk store credit POST return besides balances?”
Tell an agent
Bulk-fetch store credit customers with balances and last transactions.
Run the bulk store credit lookup including each customer's transaction list.
GET /store_credits/report Get the store credit report · Store credit report #
Ask an LLM
“Where can I see a report of all store credit in my store?”
“Is there a summary report of outstanding store credit?”
Tell an agent
Get the store credit report.
Pull the report summarizing store credits.
GET /store_credits/{customerId} Get a customer's store credit history · Store Credit operations and a balance of a customer #
Ask an LLM
“What store credit operations has a particular customer had?”
“How do I see a customer's store credit history along with their balance?”
Tell an agent
Show the store credit history and balance for customer {customerId}.
List all store credit operations for customer {customerId}.
GET /store_credits/{customerId}/balance Get a customer's store credit balance · Store Credit balance of a customer #
Ask an LLM
“How much store credit does this customer have left?”
“Can I check a customer's balance without the transaction history?”
Tell an agent
Get the store credit balance for customer {customerId}.
Tell me how much store credit customer {customerId} has.
POST /store_credits/{customerId}/hold Place a temporary hold on store credit · Create a store credit HOLD transaction #
Ask an LLM
“How do I temporarily reserve part of a customer's store credit before checkout?”
“Can I put a hold on store credit that I redeem later?”
Tell an agent
Hold {amount} of store credit for customer {customerId}.
Create a store credit hold of {amount} on customer {customerId} with client ID {client_id}.
POST /store_credits/{customerId}/hold/reverse Release a store credit hold · Reverse a store credit HOLD transaction #
Ask an LLM
“How do I release a store credit hold if the customer abandons checkout?”
“Can I reverse a specific hold by its reference ID?”
Tell an agent
Reverse the store credit hold for customer {customerId}.
Release hold {reference_id} on customer {customerId}'s store credit.
POST /store_credits/{customerId}/transactions Issue or redeem store credit · Create a store credit transaction #
Ask an LLM
“How do I redeem part of a customer's store credit balance?”
“Can I issue store credit to a customer with a note?”
Tell an agent
Create a {type} store credit transaction of {amount} for customer {customerId} with client ID {client_id}.
Redeem {amount} from customer {customerId}'s store credit with note {notes}.

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-store-credits-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-store-credits-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-store-credits-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 Store Credits 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: Store Credit operations
  name: Store Credits
paths:
  /store_credits:
    get:
      description: 'Returns all the store credit customers in a store with their store credit balance

        and a list of last store credit transactions for each customer


        🔒 Requires: `store_credits:read` scope'
      operationId: ListStoreCredit
      parameters:
      - description: The maximum number of items to be returned in the response
        in: query
        name: page_size
        schema:
          type: integer
      - description: Include supplementary data. The only valid value for includes[] is 'customer'.
        in: query
        name: includes[]
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Store Credit customer data in the shop
                items:
                  $ref: '#/components/schemas/StoreCreditCustomer'
                type: array
          description: The list of store credit customers.
      summary: Get store credit usage for the store
      tags:
      - Store Credits
  /store_credits/balances-bulk:
    post:
      description: 'Returns all the store credit customers in a store with their store credit balance.


        🔒 Requires: `store_credits:read` scope'
      operationId: BulkBalancesStoreCreditList
      requestBody:
        content:
          application/json:
            schema:
              items:
                format: uuid
                type: string
              type: array
        description: The list of customer ids to get related store credit for.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCreditBalancesBulkResponse'
          description: A list of customers with associated store credit balances.
      summary: Bulk Store Credit customers balances
      tags:
      - Store Credits
  /store_credits/bulk:
    post:
      description: 'Returns all the store credit customers in a store with their store credit balance

        and a list of last store credit transactions for each customer


        🔒 Requires: `store_credits:read` scope'
      operationId: BulkStoreCreditList
      requestBody:
        content:
          application/json:
            schema:
              items:
                format: uuid
                type: string
              type: array
        description: The list of customer ids to get related store credit for.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCreditBulkResponse'
          description: A list of customers with associated store credit balances.
      summary: Bulk Store Credit customers
      tags:
      - Store Credits
  /store_credits/report:
    get:
      description: 'Returns a report of store credits.


        🔒 Requires: `store_credits:read` scope'
      operationId: StoreCreditReport
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCreditReport'
          description: A summary of a Store Credit usage in a store
      summary: Store credit report
      tags:
      - Store Credits
  /store_credits/{customerId}:
    get:
      description: 'Returns a balance and a history of store credit operations for the given customer id.


        🔒 Requires: `store_credits:read` scope'
      operationId: ListStoreCreditForCustomer
      parameters:
      - description: Customer id
        in: path
        name: customerId
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCreditCustomer'
          description: The store credit details for the given customer.
        '404':
          content:
            application/json:
              schema:
                type: object
          description: The given customer not found.
      summary: Store Credit operations and a balance of a customer
      tags:
      - Store Credits
  /store_credits/{customerId}/balance:
    get:
      description: 'Returns a balance for the given customer id.


        🔒 Requires: `store_credits:read` scope'
      operationId: StoreCreditBalanceForCustomer
      parameters:
      - description: Customer id
        in: path
        name: customerId
        required: true
        schema:
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCreditCustomerBalance'
          description: The store credit details for the given customer.
        '404':
          content:
            application/json:
              schema:
                type: object
          description: The given customer not found.
      summary: Store Credit balance of a customer
      tags:
      - Store Credits
  /store_credits/{customerId}/hold:
    post:
      description: 'Creates a tranaction that represents temporary store credit redemption

        That redemption should be reverted later AND may get followed by a REDEMPTION'
      operationId: CreateStoreCreditHold
      parameters:
      - description: The customer id to create a hold for.
        in: path
        name: customerId
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreCreditCreateHoldParams'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCreditTransaction'
          description: A HOLD Transaction successfully created for a customer
        '400':
          content:
            application/json:
              schema:
                type: object
          description: Invalid parameters or insufficient store credit balance
        '404':
          content:
            application/json:
              schema:
                type: object
          description: The given customer was not found.
      summary: Create a store credit HOLD transaction
      tags:
      - Store Credits
  /store_credits/{customerId}/hold/reverse:
    post:
      description: Creates a tranaction reverting a HOLD operation
      operationId: ReverseStoreCreditHold
      parameters:
      - description: The customer id of the hold owner
        in: path
        name: customerId
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                reference_id:
                  description: id of a previous HOLD transaction
                  type: string
              type: object
      responses:
        '200':
          description: The hold transaction was reverted succesfully
        '404':
          content:
            application/json:
              schema:
                type: object
          description: The given customer was not found.
      summary: Reverse a store credit HOLD transaction
      tags:
      - Store Credits
  /store_credits/{customerId}/transactions:
    post:
      description: 'Creates a new store credit transaction. The type determines what sort of transaction it is.


        * "REDEMPTION" - Use this type when you want to redeem a certain amount from the store credit balance. The amount MUST be negative. If you want to add an amount to the balance use the "ISSUE" type.

        🔒 Requires: `store_credits:write:redeem`

        * "ISSUE" - Use this type when you issue store credit to a customer.

        🔒 Requires: `store_credits:write:issue`

        * "REVERSE" - Use this type when voiding an earlier ISSUE or REDEMPTION transaction.

        🔒 Requires: `store_credits:write:redeem`


        If the customer account does not have enough credit to honour a REDEMPTION 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.

        When creating an REVERSE operation, client_id must be equal to client_id of a reversed operation.

        See the tutorial for more information.'
      operationId: CreateStoreCreditTransaction
      parameters:
      - description: The customer id to apply the store transaction to.
        in: path
        name: customerId
        required: true
        schema:
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreCreditTransactionParams'
        description: The store credit transaction details
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreCreditTransaction'
          description: A transaction successfully created for the customer
        '404':
          content:
            application/json:
              schema:
                type: object
          description: The given customer was not found.
        '422':
          content:
            application/json:
              schema:
                type: object
          description: There is insufficient balance for this customer to honour the transaction.
      summary: Create a store credit transaction
      tags:
      - Store Credits
components:
  schemas:
    StoreCreditTransaction:
      description: A store credit operation
      properties:
        amount:
          description: The amount of the transaction
          format: double
          type: number
        client_id:
          description: 'An operation idempotency identifier.

            The client must provide this and normally it should be the transaction id from the client system.

            An operation and it''s reverse operation must have the same client_id

            '
          type: string
        created_at:
          description: The date time the transaction was created.
          example: '2026-01-02T15:04:05Z'
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(Z|[+-]\d{2}:\d{2})$
          type: string
        id:
          description: transaction unique identifier (base64 encoded)
          type: string
        notes:
          description: The notes associated with the transaction.
          type: string
        sale_id:
          description: The sale id the transaction is associated with. This should be null for transactions initiated outside of Lightspeed Retail. If it is a sale id, it will be in UUID format.
          format: uuid
          type: string
        type:
          description: The type of the transaction
          enum:
          - ISSUE
          - REDEMPTION
          - REVERSE
          type: string
        user_id:
          description: The user id of the person who performed the transaction (during a sale or a manual issue)
          format: uuid
          type: string
      title: Store Credit Transaction for Customer
      type: object
    StoreCreditCustomerBalance:
      description: The store credit balance and statistics for the customer
      properties:
        balance:
          description: The customers store credit balance.
          format: double
          type: number
        customer_id:
          description: The customers public id.
          type: string
        total_credit_issued:
          description: Total amount of store credit issued to this customer.
          format: double
          type: number
        total_credit_redeemed:
          description: Total amount of store credit spent by this customer.
          format: double
          type: number
      title: Store Credit Customer Balance
      type: object
    StoreCreditCreateHoldParams:
      properties:
        amount:
          description: The amount of the transaction.
          format: double
          type: number
        client_id:
          description: 'The client id is a unique transaction identifier. See StoreCreditTransactionParams

            '
          type: string
      required:
      - amount
      title: Store Credit Transaction Parameters to create a HOLD transaction
      type: object
    StoreCreditBalancesBulkResponse:
      description: The fields returned by the store_credit /store_credits/balances-bulk
      properties:
        data:
          description: An array of Store Credit Customer balances
          items:
            $ref: '#/components/schemas/StoreCreditCustomerBalance'
          type: array
      required:
      - data
      title: Store Credit Bulk Response
      type: object
    StoreCreditReport:
      description: The store credit report for a retailer.
      properties:
        outstanding_balance:
          description: The outstanding balance.
          format: double
          type: number
        total_value_issued:
          description: The total credit issued.
          format: double
          type: number
        total_value_redeemed:
          description: The total value redeemed.
          format: double
          type: number
      title: Store Credit Report
      type: object
    StoreCreditCustomer:
      description: The store credit information for a customer.
      properties:
        balance:
          description: The customers store credit balance.
          format: double
          type: number
        created_at:
          description: Creation timestamp in UTC.
          type: string
        customer_id:
          description: The customer id.
          format: uuid
          type: string
        id:
          description: Store Credit Customer's internal ID.
          format: string
          type: string
        store_credit_transactions:
          description: The transactions associated with this customer.
          items:
            $ref: '#/components/schemas/StoreCreditTransaction'
          type: array
        total_credit_issued:
          description: Total amount of store credit issued to this customer.
          format: double
          type: number
        total_credit_redeemed:
          description: Total amount of store credit spent by this customer.
          format: double
          type: number
      required:
      - customer_id
      - balance
      - total_credit_issued
      - total_credit_redeemed
      title: Store Credit Customer
      type: object
      x-examples:
        example-1:
          balance: 10
          customer_id: 160c0c4b-9966-4dc1-a916-8407eb10d74e
          store_credit_transactions:
          - amount: 10
            client_id: string
            created_at: string
            notes: string
            sale_id: 7e9bee0e-09d3-495f-848b-5926aa2ded33
            type: ISSUE
            user_id: a169451c-8525-4352-b8ca-070dd449a1a5
          total_credit_issued: 10
          total_credit_redeemed: 0
    StoreCreditBulkResponse:
      description: Store credit customer list with balance and transactions
      properties:
        data:
          description: An array of Store Credit Customers
          items:
            $ref: '#/components/schemas/StoreCreditCustomer'
          type: array
      required:
      - data
      title: Store Credit Bulk Response
      type: object
      x-examples:
        example-1:
          data:
          - balance: 10
            customer_id: 160c0c4b-9966-4dc1-a916-8407eb10d74e
            store_credit_transactions:
            - amount: 10
              client_id: string
              created_at: string
              notes: string
              sale_id: 7e9bee0e-09d3-495f-848b-5926aa2ded33
              type: ISSUE
              user_id: a169451c-8525-4352-b8ca-070dd449a1a5
            total_credit_issued: 10
            total_credit_redeemed: 10
    StoreCreditTransactionParams:
      description: The store credit transaction parameters for a customer transaction.
      properties:
        amount:
          description: The amount of the transaction.
          format: double
          type: number
        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
        notes:
          description: The notes associated with the transaction.
          type: string
        type:
          description: The type of the transaction
          enum:
          - ISSUE
          - REDEMPTION
          - REVERSE
          type: string
        user_id:
          description: The user id of the person who handled the transaction.
          format: uuid
          type: string
      required:
      - amount
      - client_id
      - type
      title: Store Credit Transaction Parameters for Customer
      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