Store Credit - BETA

The Store Credit API can be used to query, issue and redeem Lightspeed Retail (X-Series) Store Credit.

We recommend that you first familiarise yourself with Lightspeed Retail (X-Series)'s Store Credit functionality by reviewing the available documentation in our help centre.

This API allows an integrator to create store credit transactions outside of a Lightspeed Retail (X-Series) register - for example, for an external ecommerce app, or for an outlet which uses a different POS system.

The API does NOT support associating store credit transactions with sales on a Lightspeed Retail (X-Series) register. If you would like to be able to raise Lightspeed Retail (X-Series) sales and associate Lightspeed Retail (X-Series) payment methods with Store Credit sold and used via the API, please contact us on [email protected] for further information.

Examples

Getting a List of All Customers and their Store Credit Transactions

If you wanted to get a list of customers and their current store credit transactions you would do a GET to the /api/2.0/store_credits endpoint. This will return a list of customers and their current and historical store credit transactions. An example payload is shown below.

{
  "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
        }
      },
      ...
    ]
}

If you'd like to return the customer details, you can specify the query parameter includes[]=customer: /api/2.0/store_credits/?includes[]=customer .

Getting the Store Credit Balance for a Particular Customer

To get the store credit details for a particular customer you would need to do a GET to the /api/2.0/store_credits/:customerID endpoint. The customerID is the customer UUID from the Lightspeed Retail (X-Series) system. An example payload is shown below.

{
    "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 customers store credit you would need to POST to the /api/2.0/store_credits/:customerID/transactions endpoint with a JSON body payload which has 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"
}

If successful you should get a 200 OK response and 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 that transactions are unique and preventing the same transaction from being made more than once is a core component of ensuring your omni-channel solution works as expected.

Idempotency is achieved for Store Credit transactions by the client supplying a client_id, this can be an external reference number, transaction ID or even just a UUID. It needs to be unique per transaction and must be provided with all reloading and redeeming 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, simply and safely.