Store Credit - BETA

The Store Credit API can be used to query, issue and redeem Vend Store Credit.

We recommend that you first familiarise yourself with Vend’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 Vend 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 Vend register. If you would like to be able to raise Vend sales and associate Vend payment methods with Store Credit sold and used via the API, please contact us on api@vendhq.com 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 Vend 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 Vend 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.