Store Credit

The Store Credit API supports querying, issuing, and redeeming Lightspeed Retail (X-Series) Store Credit.

Before integrating, review Lightspeed Retail (X-Series) Store Credit behavior in the help centre.

This API enables creation of Store Credit transactions outside a Lightspeed Retail (X-Series) register, for example from an external ecommerce app or an outlet using a different POS system.

The API does not support associating Store Credit transactions with sales on a Lightspeed Retail (X-Series) register.

Examples

Getting a List of All Customers and their Store Credit Transactions

To retrieve a list of customers and their Store Credit transactions, send GET /api/{date-version}/store_credits. The response includes current and historical Store Credit transactions. Example payload:

{
  "data": [
        {
            "id": "AghZsWvnoAM=",
            "customer_id": "0242ac14-002c-11e9-f1cd-d8f0aa3284db",
            "created_at": "2019-09-30T20:28:55+00:00",
            "customer": null,
            "balance": 0.0000,
            "store_credit_transactions": [
                {
                    "id": "AghiNYlXwAE=",
                    "amount": -20.0000,
                    "type": "REDEMPTION",
                    "notes": null,
                    "user_id": "08002782-0c90-11e6-e3ed-117ec127b1ca",
                    "sale_id": "0242ac19-002c-11e9-ffbb-e3c0ddbc7fdb",
                    "client_id": "0f6799a5-3a64-ba69-11e9-e3c0e37e2787",
                    "created_at": "2019-09-30T22:57:45+00:00"
                },
                {
                    "id": "AghZsWv3oAQ=",
                    "amount": 20.0000,
                    "type": "ISSUE",
                    "notes": null,
                    "user_id": "08002782-0c90-11e6-e3ed-117ec12866a9",
                    "sale_id": "0242ac19-002c-11e9-ffbb-e3c0ddbc7fdb",
                    "client_id": "0f6799a5-3a64-ba69-11e9-e3c0e37e2787",
                    "created_at": "2019-09-30T20:28:55+00:00"
                }
            ],
            "total_credit_issued": 20.0000,
            "total_credit_redeemed": -20.0000
        }
    ]
}

To include customer details, specify includes[]=customer, for example: /api/{date-version}/store_credits/?includes[]=customer.

Getting the Store Credit Balance for a Particular Customer

To retrieve Store Credit details for a specific customer, send GET /api/{date-version}/store_credits/{customerID}. customerID is the customer UUID from Lightspeed Retail (X-Series). Example payload:

{
    "id": "AggOK48W8AE=",
    "customer_id": "0242ac14-002c-11e9-f1cd-d8f0aa3284db",
    "created_at": "2019-09-29T22:29:04+00:00",
    "customer": null,
    "balance": 20.0000,
    "store_credit_transactions": [
        {
            "id": "AggVdTPHNAI=",
            "amount": -5.0000,
            "type": "REDEMPTION",
            "notes": null,
            "user_id": "08002782-0c90-11e6-e3ed-117ec127b1ca",
            "sale_id": "e4cde176-f7c4-4fa8-b1c1-afc8adfc4216",
            "client_id": "e323a0dd-0871-47f1-8a2a-f5d0cb5703ed",
            "created_at": "2019-09-30T00:36:25+00:00"
        },
        {
            "id": "AggY1T36QGs=",
            "amount": 25.0000,
            "type": "ISSUE",
            "notes": null,
            "user_id": "08002782-0c90-11e6-e3ed-117ec127b1ca",
            "sale_id": "8e9fa943-a763-417f-ba65-40d2489720f6",
            "client_id": "66983bc7-0007-4460-b5bb-bf7073942d4e",
            "created_at": "2019-09-30T01:35:24+00:00"
        }
    ],
    "total_credit_issued": 25.0000,
    "total_credit_redeemed": -5.0000
}

Redeeming Store Credit

To redeem an amount from a customer Store Credit balance, send POST /api/{date-version}/store_credits/{customerID}/transactions with a request body in the following format:

{
    "store_credit_customer_id": "0242ac14-002c-11e9-f1cd-d8f0aa3284db",
    "amount": -5.00,
    "type": "REDEMPTION",
    "notes": null,
    "user_id": "08002782-0c90-11e6-e3ed-117ec127b1ca",
    "client_id": "0f6799a5-3a64-ba69-11e9-e3c0e37e2788"
}

On success, the API returns 200 OK with the following payload:

{
    "id": "AghumxX9PAE=",
    "amount": -5.0000,
    "type": "REDEMPTION",
    "notes": null,
    "user_id": "08002782-0c90-11e6-e3ed-117ec127b1ca",
    "sale_id": null,
    "client_id": "0f6799a5-3a64-ba69-11e9-e3c0e37e2788",
    "created_at": "2019-10-01T02:34:24+00:00"
}

Idempotency

Ensuring transactions are unique and preventing duplicate transaction creation is a core part of reliable omni-channel implementations.

Idempotency for Store Credit transactions is achieved by supplying a client_id (for example, an external reference number, transaction ID, or UUID). This value must be unique per transaction and must be provided for all reload and redeem transactions.

When Lightspeed Retail (X-Series) receives a Store Credit transaction, it checks the client_id to see if it has already been applied. If a second transaction is posted with the same client_id and transaction details, it will not be applied, and that previous transaction will be returned in its place. In this way, a client application can implement retries safely.