Loyalty API (v2)

Download OpenAPI specification:Download

This document is a technical description of the Loyalty API for Storebox. The Storebox Loyalty API is the programming interface for the Storebox Loyalty Bank.

Storebox Loyalty Bank is an API that provides merchants the opportunity to dynamically track their customers purchase history patterns and award points or vouchers based on business rules and for users of the loyalty program to utilize these points and coupons.

The Storebox Loyalty Bank includes services for linking customers to the bank and any existing loyalty programs that may exist for future reference, so that the Storebox Loyalty Bank can be used with an existing loyalty card.

Merchants can use the API to integrate purchases in the physical store or at their webshop to the Storebox Loyalty Bank and thereby have a central and simple identification process based on the customers’ payment card (PAN).

The intended audience for this documentation is technicians developing system integration to Storebox.

The Storebox Loyalty API is organized around REST. The API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs. JSON is the data interchange format and will be returned in responses from the API, including errors.

Authentication

basicAuth

The simplest authentication scheme is to use HTTP Basic authentication.

In each API call the username/password must be provided. This will be used by the storebox.com system to authenticate the calling system and authorize it to perform the requested operation. The username and password will be delivered by Storebox upon registration. The password can be changed at regular intervals. For each API call HTTP Authorization header should be set:

Authorization: Basic {Base64(<username>:<password>)}
Security Scheme Type HTTP
HTTP Authorization Scheme basic

Users

Users are a central part the loyalty API. They are the entity to be identified based on provided tokens and will often have coupons, points and/or cards associated.

Concepts:

Member id A user can have one or more member ids with an associated type, for identification purposes. A member id is provided upon user creation and must be unique.
User linkage Users can linked either one-directional or bi-directional. The linkage can be used at lookup time to identify whether a member is part of a company, family, etc.

Create a new user

Creates a new user, associates it with the given member ids and links it with the given linkedMemberIds

Request Body schema: application/json
memberIds
required
Array of objects (member-id-set)
linkedMemberIds
Array of objects (member-id-set)

Responses

201

User created

400

Invalid request/values

404

Linked member id not found

409

Member id already exists

post /v2/users

Production

https://loyalty.storebox.com/v2/users

Test

https://test-loyalty.storebox.com/v2/users

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "memberIds":
    [
    ],
  • "linkedMemberIds":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "userId": "string"
}

Get user on member id

Lookup a user based on a provided member Id. This endpoint will return all relevant information on the user like memberIds, points (if enabled), coupons (if enabled) and linked users (if enabled).

path Parameters
memberId
required
string
Example: e75ca15c8ae1401c943ff15df437f1d8

Member id that should be looked up

Responses

200

User found and returned

404

User not found

get /v2/users/memberId/{memberId}

Production

https://loyalty.storebox.com/v2/users/memberId/{memberId}

Test

https://test-loyalty.storebox.com/v2/users/memberId/{memberId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "provider": "storebox",
  • "memberIds":
    [
    ],
  • "card":
    {
    },
  • "linkedMemberIds":
    [
    ],
  • "points":
    [
    ],
  • "coupons":
    [
    ]
}

Delete a user

Deletes the user found by the specified member id. Deleting a user will delete all cards, coupons, points, etc. associated with the user. This operation cannot be undone.

path Parameters
memberId
required
string
Example: e75ca15c8ae1401c943ff15df437f1d8

Member id that should be looked up

Responses

200

User found and deleted

404

User not found

delete /v2/users/memberId/{memberId}

Production

https://loyalty.storebox.com/v2/users/memberId/{memberId}

Test

https://test-loyalty.storebox.com/v2/users/memberId/{memberId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timestamp": 1549880850241,
  • "status": "40X",
  • "error": "Http status text",
  • "message": "Cause of the error"
}

Update a user

Add/remove member ids and add/remove linked users

path Parameters
memberId
required
string
Example: e75ca15c8ae1401c943ff15df437f1d8

Member id that should be looked up

Request Body schema: application/json
addMemberIds
Array of objects (member-id-set)
removeMemberIds
Array of objects (member-id-set)
addLinkedMemberIds
Array of objects (member-id-set)
removeLinkedMemberIds
Array of objects (member-id-set)

Responses

200

User updated

400

Invalid parameter/request

404

User to update or Linked member id not found

409

Member id already exists

put /v2/users/memberId/{memberId}

Production

https://loyalty.storebox.com/v2/users/memberId/{memberId}

Test

https://test-loyalty.storebox.com/v2/users/memberId/{memberId}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "addMemberIds":
    [
    ],
  • "removeMemberIds":
    [
    ],
  • "addLinkedMemberIds":
    [
    ],
  • "removeLinkedMemberIds":
    [
    ]
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timestamp": 1549880850241,
  • "status": "40X",
  • "error": "Http status text",
  • "message": "Cause of the error"
}

Get user by token

Lookup a user based on a provided token. This endpoint will return all relevant information on the user like memberIds, points (if enabled), coupons (if enabled) and linked users (if enabled).

path Parameters
token
required
string

Token referencing the users card

Responses

200

User found and returned

404

User not found

get /v2/users/token/{token}

Production

https://loyalty.storebox.com/v2/users/token/{token}

Test

https://test-loyalty.storebox.com/v2/users/token/{token}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "provider": "storebox",
  • "memberIds":
    [
    ],
  • "card":
    {
    },
  • "linkedMemberIds":
    [
    ],
  • "points":
    [
    ],
  • "coupons":
    [
    ]
}

Get users by token - includes linked users

Like the get user endpoint this endpoint returns the user found, based on the provided token. In addition, this endpoint will also return all directly linked members complete with coupons, points etc.

path Parameters
token
required
string

Token referencing the users card

Responses

200

User found and returned

404

User not found

get /v2/users/token/{token}/linked

Production

https://loyalty.storebox.com/v2/users/token/{token}/linked

Test

https://test-loyalty.storebox.com/v2/users/token/{token}/linked

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "memberIds":
    [
    ],
  • "points":
    [
    ],
  • "coupons":
    [
    ],
  • "linkedMember":
    [
    ]
}

Get users by member id - includes linked users

Like the get user endpoint this endpoint returns the user found, based on the provided member id. In addition, this endpoint will also return all directly linked members complete with coupons, points etc.

path Parameters
memberId
required
string
Example: e75ca15c8ae1401c943ff15df437f1d8

Member id that should be looked up

Responses

200

User found and returned

404

User not found

get /v2/users/memberId/{memberId}/linked

Production

https://loyalty.storebox.com/v2/users/memberId/{memberId}/linked

Test

https://test-loyalty.storebox.com/v2/users/memberId/{memberId}/linked

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "memberIds":
    [
    ],
  • "points":
    [
    ],
  • "coupons":
    [
    ],
  • "linkedMember":
    [