WLL Rewards Core API

Introduction

The White Label Loyalty (WLL) Core Rewards API enables developers to create rich and fully customizable loyalty experiences for end-users through a simple to manage and update loyalty logic on the fly from WLL’s easy to use backend console.

Platform Topology

Getting Started

Once you have received your API key you can begin using the API. The API key should be included in every request as the value of the X-Api-Key header.

To report end-user interactions you must set up your system authentication configuration in the WLL Console. This can be any RS256 or HS256 JWT signing configuration, WLL can supply the requisite OAuth infrastructure or your pre-existing authentication system can be used seamlessly.

Sandbox environment

While developing your solution you can use the fully isolated sandbox environment. This environment and all APIs are identical, the only difference is that you should make your API calls with a different base URL.

API testing

Click the button below to open an API testing workspace in Insomnia.

Run in Insomnia}

Once opened you should see a workspace with some pre-configured API requests available to test. Insomnia workspace home

Some APIs require administrative authentication. You can should configure the workspace base environment options with your API key and admin auth credentials. View step 3 in this support document for more information.

Insomnia configuration

Authorization

All requests to the API must contain a X-Api-Key header to identify your tenant account. In addition to the API key, some methods additionally require a Authorization header to identify the user or entity accessing the API, and ensure the requester has sufficient permissions for the requested operation.

This means that there are three levels of authorization which you should be aware when using this API:

  1. 🔑 Anonymous (API key only)

  2. 👤 User (API key + end-user auth token)

  3. 🔒 Admin (API key + administrative auth token)

Each API method described in this documentation will advise which type of authorization is requried.

Integrating with other systems

The White Label Loyalty (WLL) platform models interactions between customer and business as a stream of events from which customer loyalty can be derived. The logic governing the loyalty programme can be defined and adjusted at any time via our cloud management console. Thus, the main work needed when integrating a system with WLL is to analyze what business events occur within the system and determine which events should be reported to WLL.

Events Processing

Codifying Events

The first step to integrating any system with the WLL platform is to codify the business events from which the loyalty programme logic will be derived. There are two parts to this step:

  1. selecting which things happening during the day-to-day running of the business will be important to the loyalty programme,

  2. planning the shape of the data payload which represents each of these things.

The codification of these events can be done via the WLL administrative console by creating Event Types. During the creation process you will be asked to provide a name to represent the event type throughout the platform plus a schema for validating any data payload sent as part of an event of this type. For clarity it is recommended that event type names should follow the principles outlined in the section below.

In addition to the taxonomical aspects of creating an event type you will also need to define whether it is a public or private event type. Private event types may only be reported by a secure server with access to a privileged secret. Whereas public event types are reported directly by authenticated users.

Kinds of Events

There are three main kinds of business events which you might want to codify and report to WLL.

Customer Actions

Customer actions are things which customers have themselves done during some interaction with the business. These kinds of events will almost always be public events since they are generally reported from the client side. We recommend naming these event types in the form of a past-participle verb followed by a noun, such as VISITED_SHOP, REDEEMED_CODE, or ATE_SANDWICH. In this way reporting an event can be thought in terms of a sentence “Jane Doe visited a shop” wherein the accompanying payload provide further detail.

Customer Proceedings

Customer proceedings are things which relate to a customer but haven’t been directly triggered by the customer. These events are usually triggered by a back-office business process. These kinds of events will almost always be private events since the source of truth for these things will usually be a secure backend server.

We recommend naming these event types in the form of a noun followed by a past-participle verb, such as INVOICE_RAISED, REFUND_AWARDED, CARD_INVALIDATED. In this way reporting an event can be thought of in terms of a sentence “Jane Doe’s invoice was raised”.

Business Proceedings

Business proceedings are things which occur during the day-to-day running of the business but don’t relate to a specific customer.

Reporting Events

Once the business has decided on which events are relevant all events should be reported to the /events endpoint of the WLL Rewards API. Documentation on the format of this API call is here.

When reporting events you will likely want to supply a data payload for the WLL platform to capture. This data payload will enable you to customize the loyalty logic at a granular level. For example the number of points awarded to a user for an event could be configured to vary based on the time of day, the day of week, total spend, or any other data that is passed in the payload.

Examples

Invoice Raised

When a invoice is raised for a customer, the integrating system could report an event to the WLL platform similar to the below:

POST https://api.rewards.wlloyalty.net/events
Content-Type: "application/json"
X-Api-Key: $api_key
Authorization: Bearer $event_type_secret

{
  "type": "INVOICE_RAISED",
  "subject": "$user_id",
  "payload": {
    "invoiceId": "031a81d8-2936-4ccc-8955-3009c078e6f1",
    "balance": 1299,
    "dueDate": "2019-03-01T12:00:00Z"
  }
}
Invoice Paid

When a invoice is paid by a customer, the integrating system could report an event to the WLL platform similar to the below:

POST https://api.rewards.wlloyalty.net/events
Content-Type: "application/json"
X-Api-Key: $api_key
Authorization: Bearer $event_type_secret

{
  "type": "INVOICE_PAID",
  "subject": "$user_id",
  "payload": {
    "invoiceId": "031a81d8-2936-4ccc-8955-3009c078e6f1",
    "balance": 0,
    "overdue": true,
    "daysLate": 4,
    "paymentMethod": "CASH"
  }
}

Events

Events Collection

POST api.rewards.wlloyalty.net/v1/events
RequestsPublic EventTypePrivate EventType
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "type": "VISITED_VENUE",
  "payload": {}
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "The name of the event-type being submitted."
    },
    "payload": {
      "type": "object",
      "properties": {},
      "description": "The free-form data payload for this event."
    }
  },
  "required": [
    "type"
  ]
}
Responses201
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": 0,
    "type": {
      "id": "d7efcfb2-dfe3-47a7-b826-4ef8b9b0012f",
      "name": "COMPLETED_EXAMPLE_ACTION",
      "description": "",
      "isPrivate": false,
      "schema": {
        "$schema": "http://json-schema.org/draft-06/schema#",
        "type": "object",
        "properties": {},
        "required": []
      },
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z"
    },
    "subject": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "reportedAt": "2018-06-08T08:57:47.198Z",
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "reactedAt": "2018-06-08T08:57:47.198Z",
    "occuredAt": "2018-06-08T08:57:47.198Z",
    "payload": {}
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "type": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "isPrivate": {
              "type": "boolean"
            },
            "schema": {
              "type": "object",
              "properties": {
                "$schema": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "properties": {
                  "type": "object",
                  "properties": {}
                },
                "required": {}
              }
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "isPrivate"
          ]
        },
        "subject": {
          "type": "string"
        },
        "reportedAt": {
          "type": "string"
        },
        "registeredAt": {
          "type": "string"
        },
        "reactedAt": {
          "type": "string"
        },
        "occuredAt": {
          "type": "string"
        },
        "payload": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "type",
        "subject",
        "reportedAt",
        "payload"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $secret
Body
{
  "type": "VISITED_VENUE",
  "payload": {},
  "subject": ""
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "The name of the event-type being submitted."
    },
    "payload": {
      "type": "object",
      "properties": {},
      "description": "The free-form data payload for this event."
    },
    "subject": {
      "type": "string",
      "description": "The authentication ID of the user who is the subject of this event."
    }
  },
  "required": [
    "type"
  ]
}
Responses201
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": 0,
    "type": {
      "id": "d7efcfb2-dfe3-47a7-b826-4ef8b9b0012f",
      "name": "COMPLETED_EXAMPLE_ACTION",
      "description": "",
      "isPrivate": false,
      "schema": {
        "$schema": "http://json-schema.org/draft-06/schema#",
        "type": "object",
        "properties": {},
        "required": []
      },
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z"
    },
    "subject": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "reportedAt": "2018-06-08T08:57:47.198Z",
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "reactedAt": "2018-06-08T08:57:47.198Z",
    "occuredAt": "2018-06-08T08:57:47.198Z",
    "payload": {}
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "type": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "isPrivate": {
              "type": "boolean"
            },
            "schema": {
              "type": "object",
              "properties": {
                "$schema": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "properties": {
                  "type": "object",
                  "properties": {}
                },
                "required": {}
              }
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "isPrivate"
          ]
        },
        "subject": {
          "type": "string"
        },
        "reportedAt": {
          "type": "string"
        },
        "registeredAt": {
          "type": "string"
        },
        "reactedAt": {
          "type": "string"
        },
        "occuredAt": {
          "type": "string"
        },
        "payload": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "type",
        "subject",
        "reportedAt",
        "payload"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Submit an Event
POST/events

Use this endpoint to pass back information about the interactions between end-users and the business. This endpoint can be used in one of two ways; the first is that actions carried out directly by an authenticated user can be reported directly to the API for a public event-type.

The second mode of use is for interactions which occur indirectly to the end-user, in this case an event can be reported for a private event-type from a trusted environment using a secret token. This mode can be used to easily integrate 3rd-party systems.

To submit a public event the authenticated user’s access token should be included in the Authorization header instead. To submit a private event the event-type secret must be included as a bearer token in the Authorization header. The event-type scecret can be retrieved via the WLL Console.

It is not possible to pass a custom subject for a public event-type, since the subject will be automatically assigned based on the authenticated user.

The payload must conform to the schema dictated by the event-type. If no schema is defined then the payload may be omitted.

🔐 Multiple authorization modes

Requests to this method require one of two authorization types depending on the kind of event being submitted. Details are explained above. Non-compliant requests will be rejected.

N.B. Authorization for private events is a special case not used elsewhere.


GET api.rewards.wlloyalty.net/v1/events?limit=10&skip=0&sort=id&order=ASC&filter=reportedAt:(gt:'2019-01-01T00:00:00')
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "id": 0,
      "type": {
        "id": "d7efcfb2-dfe3-47a7-b826-4ef8b9b0012f",
        "name": "COMPLETED_EXAMPLE_ACTION",
        "description": "",
        "isPrivate": false,
        "schema": {
          "$schema": "http://json-schema.org/draft-06/schema#",
          "type": "object",
          "properties": {},
          "required": []
        },
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z"
      },
      "subject": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "reportedAt": "2018-06-08T08:57:47.198Z",
      "registeredAt": "2018-06-08T08:57:47.198Z",
      "reactedAt": "2018-06-08T08:57:47.198Z",
      "occuredAt": "2018-06-08T08:57:47.198Z",
      "payload": {}
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List all Events
GET/events{?limit,skip,sort,order,filter}

Get a list of all the events which have been reported for your tenant.

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:events scope. Non-compliant requests will be rejected.

Filtering

It is possible to apply basic filter conditions to the result set using the filter query parameter. This parameter accepts an O-Rison encoded JSON object expressing the set of conditions to be applied.

The general format of this filter object (expressed in JSON) is as follows:

{
  "field1": { "operator": "value" },
  "field2": { "operator": "value" }
}

Where field1 and field2 are field names of this entity, operator is one of [eq, neq, gt, lt, in, has], and "value" is the exact value to compare against. The value need not necessarily be a string, the type appropriate for the field should be used. See the O-Rison documentation for help on how to format other types. Dates and datetimes should be passed as ISO 8601 strings.

The same filter encoded as O-Rison would be as follows:

field1:(operator:'value'),field2:(operator:'value')
URI Parameters
HideShow
limit
number (optional) Example: 10

The number of items to retrieve.

skip
number (optional) Example: 0

The number of items to skip before selecting.

sort
string (optional) Example: id

The property to use for sorting.

Choices: id occuredAt reportedAt registeredAt reactedAt

order
string (optional) Example: ASC

The order to sort items.

Choices: ASC DESC

filter
string (optional) Example: reportedAt:(gt:'2019-01-01T00:00:00')

O-Rison encoded filter string


Individual Event

GET api.rewards.wlloyalty.net/v1/events/16389
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": 0,
    "type": {
      "id": "d7efcfb2-dfe3-47a7-b826-4ef8b9b0012f",
      "name": "COMPLETED_EXAMPLE_ACTION",
      "description": "",
      "isPrivate": false,
      "schema": {
        "$schema": "http://json-schema.org/draft-06/schema#",
        "type": "object",
        "properties": {},
        "required": []
      },
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z"
    },
    "subject": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "reportedAt": "2018-06-08T08:57:47.198Z",
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "reactedAt": "2018-06-08T08:57:47.198Z",
    "occuredAt": "2018-06-08T08:57:47.198Z",
    "payload": {}
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "number"
        },
        "type": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "isPrivate": {
              "type": "boolean"
            },
            "schema": {
              "type": "object",
              "properties": {
                "$schema": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "properties": {
                  "type": "object",
                  "properties": {}
                },
                "required": {}
              }
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "isPrivate"
          ]
        },
        "subject": {
          "type": "string"
        },
        "reportedAt": {
          "type": "string"
        },
        "registeredAt": {
          "type": "string"
        },
        "reactedAt": {
          "type": "string"
        },
        "occuredAt": {
          "type": "string"
        },
        "payload": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "type",
        "subject",
        "reportedAt",
        "payload"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve an Event
GET/events/{id}

Retrieve the details of a single Event.

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:events scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
number (required) Example: 16389

ID of the Event.


Event Reactions

GET api.rewards.wlloyalty.net/v1/events/16389/reactions
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "totalPoints": 12,
    "reactions": [
      {
        "type": "POINTS",
        "points": {
          "operation": "SUM",
          "arguments": [
            {
              "type": "NUMBER",
              "value": ""
            }
          ]
        }
      }
    ]
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "totalPoints": {
          "type": "number"
        },
        "reactions": {
          "type": "array"
        }
      },
      "required": [
        "totalPoints",
        "reactions"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve reaction information
GET/events/{id}/reactions

Retrieve information about the reactions which occured for a given event.

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:events scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
number (required) Example: 16389

ID of the Event.


EventTypes

Event-Type Collection

GET api.rewards.wlloyalty.net/v1/event_types
RequestsDefault
Headers
X-Api-Key: $api_key
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "id": "d7efcfb2-dfe3-47a7-b826-4ef8b9b0012f",
      "name": "COMPLETED_EXAMPLE_ACTION",
      "description": "",
      "isPrivate": false,
      "schema": {
        "$schema": "http://json-schema.org/draft-06/schema#",
        "type": "object",
        "properties": {},
        "required": []
      },
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z"
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List All EventTypes
GET/event_types

Get a list of all the event-types which have been configured for your tenant. Private event-types will not report their secret, this must be retrieved securely via the WLL console.


Individual Event-Type

GET api.rewards.wlloyalty.net/v1/event_types/5a79eb9e-52d8-44ea-abff-451edf08ed55
RequestsDefault
Headers
X-Api-Key: $api_key
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "d7efcfb2-dfe3-47a7-b826-4ef8b9b0012f",
    "name": "COMPLETED_EXAMPLE_ACTION",
    "description": "",
    "isPrivate": false,
    "schema": {
      "$schema": "http://json-schema.org/draft-06/schema#",
      "type": "object",
      "properties": {},
      "required": []
    },
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "isPrivate": {
          "type": "boolean"
        },
        "schema": {
          "type": "object",
          "properties": {
            "$schema": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "properties": {
              "type": "object",
              "properties": {}
            },
            "required": {}
          }
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "isPrivate"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve an EventType
GET/event_types/{id}

Retrieve the details of a single EventType.

URI Parameters
HideShow
id
uuid (required) Example: 5a79eb9e-52d8-44ea-abff-451edf08ed55

ID of the EventType.


Rewards

Rewards Collection

GET api.rewards.wlloyalty.net/v1/rewards?limit=10&skip=0&sort=priority&order=ASC&filter=price:(gt:10)
RequestsDefault
Headers
X-Api-Key: $api_key
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "name": "Free Cup of Coffee",
      "pictureUrl": "https://example.com/pic.jpg",
      "price": 0,
      "priority": 0,
      "availability": {
        "start": "2018-06-08T18:19:10.878Z",
        "end": "2018-06-09T18:19:10.878Z"
      }
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List All Rewards
GET/rewards{?limit,skip,sort,order,filter}

Get a list of all rewards which your token is authorized to view.

By default this endpoint will return all rewards which are available at the time of request. However it will not exclude rewards which aren’t directly purchasable by users. To exclude such rewards you can supply the following query ?filter=purchasable:(eq:!t).

To list only the rewards which aren’t assigned to a particular Venue, filter for a null value on the venues field e.g. venues:(eq:!n).

Filtering

It is possible to apply basic filter conditions to the result set using the filter query parameter. This parameter accepts an O-Rison encoded JSON object expressing the set of conditions to be applied.

The general format of this filter object (expressed in JSON) is as follows:

{
  "field1": { "operator": "value" },
  "field2": { "operator": "value" }
}

Where field1 and field2 are field names of this entity, operator is one of [eq, neq, gt, lt, in, has], and "value" is the exact value to compare against. The value need not necessarily be a string, the type appropriate for the field should be used. See the O-Rison documentation for help on how to format other types. Dates and datetimes should be passed as ISO 8601 strings.

The same filter encoded as O-Rison would be as follows:

field1:(operator:'value'),field2:(operator:'value')
URI Parameters
HideShow
limit
number (optional) Example: 10

The number of items to retrieve.

skip
number (optional) Example: 0

The number of items to skip before selecting.

sort
string (optional) Example: priority

The property to use for sorting.

Choices: priority price value name

order
string (optional) Example: ASC

The order to sort items.

Choices: ASC DESC

filter
string (optional) Example: price:(gt:10)

O-Rison encoded filter string


Individual Reward

GET api.rewards.wlloyalty.net/v1/rewards/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
X-Api-Key: $api_key
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z",
    "name": "Free Cup of Coffee",
    "pictureUrl": "https://example.com/pic.jpg",
    "price": 0,
    "priority": 0,
    "availability": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "purchasable": false,
    "description": "Redeem this reward for a free cup of coffee",
    "terms": "",
    "value": 0,
    "discounts": [
      {
        "type": "FIXED",
        "value": 1000,
        "sku": "321ZA",
        "productSku": "AZ123"
      }
    ],
    "tier": {
      "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
      "name": "Gold",
      "priority": 0
    },
    "venues": [
      {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "anyidentifier123",
        "name": "starbucks"
      }
    ]
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "pictureUrl": {
          "type": "string"
        },
        "price": {
          "type": "number"
        },
        "priority": {
          "type": "number"
        },
        "availability": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "purchasable": {
          "type": "boolean"
        },
        "description": {
          "type": "string"
        },
        "terms": {
          "type": "string"
        },
        "value": {
          "type": "number"
        },
        "discounts": {
          "type": "array"
        },
        "tier": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "priority": {
              "type": "number"
            }
          },
          "required": [
            "id",
            "name",
            "priority"
          ]
        },
        "venues": {
          "type": "array"
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "name",
        "pictureUrl",
        "price",
        "priority",
        "availability",
        "purchasable",
        "description",
        "terms",
        "value",
        "discounts"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve a Reward
GET/rewards/{id}

Retrieve the details of a single Reward.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the reward.


Users

Users Collection

POST api.rewards.wlloyalty.net/v1/users
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "isRestricted": false,
  "profile": {
    "familyName": "Doe",
    "givenName": "Jane",
    "emailAddress": "jane.doe@example.com",
    "telephoneNumber": "01437 522633",
    "gender": "UNKNOWN",
    "birthdate": "1970-01-01",
    "streetAddress": "12 Bedford Street",
    "city": "Leeds",
    "postcode": "LS1 5PZ",
    "region": "West Yorkshire",
    "country": "GB",
    "pictureUrl": "https://example.com/pic.jpg",
    "attributes": {
      "key": "value"
    }
  },
  "externalIdentifier": "your custom identifier",
  "authIdentifier": "unique external user ID",
  "linkedVenues": [
    {
      "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
    }
  ],
  "referralInviteCode": "custom.app.link/XYI123sSD",
  "referralActivity": {
    "source": "EMAIL",
    "sourceUserId": "xyz@abcdef.com",
    "userAgent": "IOS",
    "ipAddress": "127.0.0.1",
    "activityType": "REGISTER"
  }
}
Responses201
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "isRestricted": false,
    "profile": {
      "familyName": "Doe",
      "givenName": "Jane",
      "emailAddress": "jane.doe@example.com",
      "telephoneNumber": "01437 522633",
      "gender": "UNKNOWN",
      "birthdate": "1970-01-01",
      "streetAddress": "12 Bedford Street",
      "city": "Leeds",
      "postcode": "LS1 5PZ",
      "region": "West Yorkshire",
      "country": "GB",
      "pictureUrl": "https://example.com/pic.jpg",
      "attributes": {
        "key": "value"
      }
    },
    "externalIdentifier": "any string",
    "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "linkedVenues": [
      {
        "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
      }
    ],
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "accountNumber": 1000001,
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z",
    "flags": {
      "genderProvided": false
    },
    "referralCodeUsedForRegistration": {
      "inviteCode": "custom.app.link/XYI123sSD",
      "inviteLink": "custom.app.link/XYI123sSD",
      "campaign": {
        "name": "Holidays Referral Campaign",
        "linkConfig": {
          "title": "Join us!",
          "description": "Your friend has invited you to checkout this app",
          "desktopUrl": "www.custom-domain.com",
          "imageUrl": "imgur.com/12323",
          "iosUrl": "iosappstorelink",
          "androidUrl": "androidplaystorelink"
        },
        "isActive": true,
        "tranches": [],
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
        "createdAt": "2021-05-08T08:57:47.198Z",
        "updatedAt": "2021-05-08T08:57:47.198Z"
      },
      "referrer": {},
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
      "createdAt": "2021-06-08T08:57:47.198Z",
      "updatedAt": "2021-06-08T08:57:47.198Z"
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "isRestricted": {
          "type": "boolean"
        },
        "profile": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string"
            },
            "givenName": {
              "type": "string"
            },
            "emailAddress": {
              "type": "string"
            },
            "telephoneNumber": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "UNKNOWN",
                "MALE",
                "FEMALE",
                "OTHER"
              ]
            },
            "birthdate": {
              "type": "string"
            },
            "streetAddress": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "postcode": {
              "type": "string"
            },
            "region": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "attributes": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "familyName",
            "givenName",
            "emailAddress"
          ]
        },
        "externalIdentifier": {
          "type": "string"
        },
        "authIdentifier": {
          "type": "string"
        },
        "linkedVenues": {
          "type": "array"
        },
        "id": {
          "type": "string"
        },
        "accountNumber": {
          "type": "number"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        },
        "flags": {
          "type": "object",
          "properties": {
            "genderProvided": {
              "type": "boolean"
            }
          }
        },
        "referralCodeUsedForRegistration": {
          "type": "object",
          "properties": {
            "inviteCode": {
              "type": "string"
            },
            "inviteLink": {
              "type": "string"
            },
            "campaign": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "linkConfig": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "desktopUrl": {
                      "type": "string"
                    },
                    "imageUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "iosUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "androidUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "title",
                    "description",
                    "desktopUrl"
                  ]
                },
                "isActive": {
                  "type": "boolean"
                },
                "tranches": {
                  "type": "array"
                },
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "linkConfig",
                "isActive",
                "id"
              ]
            },
            "referrer": {
              "type": "object",
              "properties": {}
            },
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "inviteCode",
            "inviteLink",
            "campaign",
            "id"
          ]
        }
      },
      "required": [
        "isRestricted",
        "profile",
        "authIdentifier",
        "id",
        "accountNumber",
        "createdAt",
        "updatedAt"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Register a new User
POST/users

Register a new user on the system with the profile data passed in the request body.

This endpoint can be used in one of two ways: as an administrative action or as a user action. The mode is dependent on the token passed in the Authorization header.

If the token is found to be administrative the authIdentifier property must be passed so that the user can in future be identified from their authentication token.

Otherwise the token will be checked against the tenant authentication configuration. In this case the authIdentifier will be derived from the sub claim of the passed JWT.

Fields

externalIdentifier can be used to attach any arbitrary string to the user, this is sometimes useful when linking this representation of the user to one in a seperate system. This field is not checked for uniqueness but it cannot be more than 512 characters in length.

authIdentifier is required when creating a user in administrative mode to associate the account with the ID used by the tenant authentication server. If the API will never be directly called with a user authentication token, this field can be an arbitrary unique string and may be used instead of externalIdentifier. This field will be ignored if the endpoint is invoked in user mode.

isRestricted is intended to be used for GDPR workflows where the end-user requests restriction of further processing of their data. This must be false when a new account is being created since if the user does not give permission for their data to be processed an account cannot be created.

linkedVenues can be used to provide a list of venues which this user should be associated with. The array should contain an object with the venue ID as a property.

profile.familyName the user’s family name (surname, last name): Required; string; between 1 and 64 characters in length.

profile.givenName the user’s given name (first name): Required; string; between 1 and 64 characters in length.

profile.emailAddress the user’s email address: Required; string; email format.

profile.gender the user’s gender, if not provided it will be guessed based on the given name: Optional; enum (UNKNOWN, MALE, FEMALE, OTHER).

profile.country the user’s country of residence: Optional; string; ISO 3166-1 alpha-2 format.

profile.city the user’s city of residence: Optional; string; between 1 and 256 characters in length.

profile.postcode the user’s postcode: Optional; string; between 1 and 128 characters in length.

profile.pictureUrl the HTTPS URL for a picture to represent the user: Optional; string; HTTPS URLs only.

profile.attributes optional aribitrary map of keys and values: Optional; object; Any JSON key-values.

referralInviteCode optional the invite code or link this user used during registration. See the Referral Campaign section for more info on this flow. If provided, the referralActivity property must be provided as well.

referralActivity optional contains data that explains the new user’s referral journey, which can later help with attribution. If provided, the referralInviteCode property must be provided as well.

Of note are three properties, source, sourceUserId and activityType.

source and sourceUserId describe the touch point through which the referral link was originally shared and clicked on. Eg: the referral code was shared via email to the email address ‘abc123@xyz.com’, making EMAIL as the source and ‘abc123@xyz.com’ as the sourceUserId. If this data isn’t available, simply passing a device id of the new user as sourceUserId, and OTHER as source is OK.

activityType describes whether this attribution data is about a CLICK or a REGISTER activity. For the purposes of a new user’s registration, activityType should be REGISTER.

🔐 Multiple authorization modes

Requests to this method require either:

👤 User Authorization

🔒 Admin Authorization

Details are explained above. Non-compliant requests will be rejected.


GET api.rewards.wlloyalty.net/v1/users?limit=10&skip=0&sort=id&order=ASC&filter=isRestricted:(eq:!f)
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "isRestricted": false,
      "profile": {
        "familyName": "Doe",
        "givenName": "Jane",
        "emailAddress": "jane.doe@example.com",
        "telephoneNumber": "01437 522633",
        "gender": "UNKNOWN",
        "birthdate": "1970-01-01",
        "streetAddress": "12 Bedford Street",
        "city": "Leeds",
        "postcode": "LS1 5PZ",
        "region": "West Yorkshire",
        "country": "GB",
        "pictureUrl": "https://example.com/pic.jpg",
        "attributes": {
          "key": "value"
        }
      },
      "externalIdentifier": "any string",
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "linkedVenues": [
        {
          "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
        }
      ],
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      },
      "referralCodeUsedForRegistration": {
        "inviteCode": "custom.app.link/XYI123sSD",
        "inviteLink": "custom.app.link/XYI123sSD",
        "campaign": {
          "name": "Holidays Referral Campaign",
          "linkConfig": {
            "title": "Join us!",
            "description": "Your friend has invited you to checkout this app",
            "desktopUrl": "www.custom-domain.com",
            "imageUrl": "imgur.com/12323",
            "iosUrl": "iosappstorelink",
            "androidUrl": "androidplaystorelink"
          },
          "isActive": true,
          "tranches": [],
          "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
          "createdAt": "2021-05-08T08:57:47.198Z",
          "updatedAt": "2021-05-08T08:57:47.198Z"
        },
        "referrer": {},
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
        "createdAt": "2021-06-08T08:57:47.198Z",
        "updatedAt": "2021-06-08T08:57:47.198Z"
      }
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List all Users
GET/users{?limit,skip,sort,order,filter}

Get a list of all the users registered in your tenant.

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:users scope. Non-compliant requests will be rejected.

Filtering

It is possible to apply basic filter conditions to the result set using the filter query parameter. This parameter accepts an O-Rison encoded JSON object expressing the set of conditions to be applied.

The general format of this filter object (expressed in JSON) is as follows:

{
  "field1": { "operator": "value" },
  "field2": { "operator": "value" }
}

Where field1 and field2 are field names of this entity, operator is one of [eq, neq, gt, lt, in, has], and "value" is the exact value to compare against. The value need not necessarily be a string, the type appropriate for the field should be used. See the O-Rison documentation for help on how to format other types. Dates and datetimes should be passed as ISO 8601 strings.

The same filter encoded as O-Rison would be as follows:

field1:(operator:'value'),field2:(operator:'value')
URI Parameters
HideShow
limit
number (optional) Example: 10

The number of items to retrieve.

skip
number (optional) Example: 0

The number of items to skip before selecting.

sort
string (optional) Example: id

The property to use for sorting.

Choices: id createdAt updatedAt

order
string (optional) Example: ASC

The order to sort items.

Choices: ASC DESC

filter
string (optional) Example: isRestricted:(eq:!f)

O-Rison encoded filter string


Specific User

GET api.rewards.wlloyalty.net/v1/users/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "isRestricted": false,
    "profile": {
      "familyName": "Doe",
      "givenName": "Jane",
      "emailAddress": "jane.doe@example.com",
      "telephoneNumber": "01437 522633",
      "gender": "UNKNOWN",
      "birthdate": "1970-01-01",
      "streetAddress": "12 Bedford Street",
      "city": "Leeds",
      "postcode": "LS1 5PZ",
      "region": "West Yorkshire",
      "country": "GB",
      "pictureUrl": "https://example.com/pic.jpg",
      "attributes": {
        "key": "value"
      }
    },
    "externalIdentifier": "any string",
    "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "linkedVenues": [
      {
        "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
      }
    ],
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "accountNumber": 1000001,
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z",
    "flags": {
      "genderProvided": false
    },
    "referralCodeUsedForRegistration": {
      "inviteCode": "custom.app.link/XYI123sSD",
      "inviteLink": "custom.app.link/XYI123sSD",
      "campaign": {
        "name": "Holidays Referral Campaign",
        "linkConfig": {
          "title": "Join us!",
          "description": "Your friend has invited you to checkout this app",
          "desktopUrl": "www.custom-domain.com",
          "imageUrl": "imgur.com/12323",
          "iosUrl": "iosappstorelink",
          "androidUrl": "androidplaystorelink"
        },
        "isActive": true,
        "tranches": [],
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
        "createdAt": "2021-05-08T08:57:47.198Z",
        "updatedAt": "2021-05-08T08:57:47.198Z"
      },
      "referrer": {},
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
      "createdAt": "2021-06-08T08:57:47.198Z",
      "updatedAt": "2021-06-08T08:57:47.198Z"
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "isRestricted": {
          "type": "boolean"
        },
        "profile": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string"
            },
            "givenName": {
              "type": "string"
            },
            "emailAddress": {
              "type": "string"
            },
            "telephoneNumber": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "UNKNOWN",
                "MALE",
                "FEMALE",
                "OTHER"
              ]
            },
            "birthdate": {
              "type": "string"
            },
            "streetAddress": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "postcode": {
              "type": "string"
            },
            "region": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "attributes": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "familyName",
            "givenName",
            "emailAddress"
          ]
        },
        "externalIdentifier": {
          "type": "string"
        },
        "authIdentifier": {
          "type": "string"
        },
        "linkedVenues": {
          "type": "array"
        },
        "id": {
          "type": "string"
        },
        "accountNumber": {
          "type": "number"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        },
        "flags": {
          "type": "object",
          "properties": {
            "genderProvided": {
              "type": "boolean"
            }
          }
        },
        "referralCodeUsedForRegistration": {
          "type": "object",
          "properties": {
            "inviteCode": {
              "type": "string"
            },
            "inviteLink": {
              "type": "string"
            },
            "campaign": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "linkConfig": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "desktopUrl": {
                      "type": "string"
                    },
                    "imageUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "iosUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "androidUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "title",
                    "description",
                    "desktopUrl"
                  ]
                },
                "isActive": {
                  "type": "boolean"
                },
                "tranches": {
                  "type": "array"
                },
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "linkConfig",
                "isActive",
                "id"
              ]
            },
            "referrer": {
              "type": "object",
              "properties": {}
            },
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "inviteCode",
            "inviteLink",
            "campaign",
            "id"
          ]
        }
      },
      "required": [
        "isRestricted",
        "profile",
        "authIdentifier",
        "id",
        "accountNumber",
        "createdAt",
        "updatedAt"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve specific User
GET/users/{id}

Retrieve the details of the user specified by their ID.

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:users scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the User to retrieve.


PATCH api.rewards.wlloyalty.net/v1/users/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "isRestricted": false,
  "profile": {
    "familyName": "Doe",
    "givenName": "Jane",
    "emailAddress": "jane.doe@example.com",
    "telephoneNumber": "01437 522633",
    "gender": "UNKNOWN",
    "birthdate": "1970-01-01",
    "streetAddress": "12 Bedford Street",
    "city": "Leeds",
    "postcode": "LS1 5PZ",
    "region": "West Yorkshire",
    "country": "GB",
    "pictureUrl": "https://example.com/pic.jpg",
    "attributes": {
      "key": "value"
    }
  },
  "externalIdentifier": "any string",
  "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "linkedVenues": [
    {
      "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
    }
  ],
  "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "accountNumber": 1000001,
  "createdAt": "2018-06-08T08:57:47.198Z",
  "updatedAt": "2018-06-08T08:57:47.198Z",
  "flags": {
    "genderProvided": false
  },
  "referralCodeUsedForRegistration": {
    "inviteCode": "custom.app.link/XYI123sSD",
    "inviteLink": "custom.app.link/XYI123sSD",
    "campaign": {
      "name": "Holidays Referral Campaign",
      "linkConfig": {
        "title": "Join us!",
        "description": "Your friend has invited you to checkout this app",
        "desktopUrl": "www.custom-domain.com",
        "imageUrl": "imgur.com/12323",
        "iosUrl": "iosappstorelink",
        "androidUrl": "androidplaystorelink"
      },
      "isActive": true,
      "tranches": [],
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
      "createdAt": "2021-05-08T08:57:47.198Z",
      "updatedAt": "2021-05-08T08:57:47.198Z"
    },
    "referrer": {},
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
    "createdAt": "2021-06-08T08:57:47.198Z",
    "updatedAt": "2021-06-08T08:57:47.198Z"
  }
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "isRestricted": false,
    "profile": {
      "familyName": "Doe",
      "givenName": "Jane",
      "emailAddress": "jane.doe@example.com",
      "telephoneNumber": "01437 522633",
      "gender": "UNKNOWN",
      "birthdate": "1970-01-01",
      "streetAddress": "12 Bedford Street",
      "city": "Leeds",
      "postcode": "LS1 5PZ",
      "region": "West Yorkshire",
      "country": "GB",
      "pictureUrl": "https://example.com/pic.jpg",
      "attributes": {
        "key": "value"
      }
    },
    "externalIdentifier": "any string",
    "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "linkedVenues": [
      {
        "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
      }
    ],
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "accountNumber": 1000001,
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z",
    "flags": {
      "genderProvided": false
    },
    "referralCodeUsedForRegistration": {
      "inviteCode": "custom.app.link/XYI123sSD",
      "inviteLink": "custom.app.link/XYI123sSD",
      "campaign": {
        "name": "Holidays Referral Campaign",
        "linkConfig": {
          "title": "Join us!",
          "description": "Your friend has invited you to checkout this app",
          "desktopUrl": "www.custom-domain.com",
          "imageUrl": "imgur.com/12323",
          "iosUrl": "iosappstorelink",
          "androidUrl": "androidplaystorelink"
        },
        "isActive": true,
        "tranches": [],
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
        "createdAt": "2021-05-08T08:57:47.198Z",
        "updatedAt": "2021-05-08T08:57:47.198Z"
      },
      "referrer": {},
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
      "createdAt": "2021-06-08T08:57:47.198Z",
      "updatedAt": "2021-06-08T08:57:47.198Z"
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "isRestricted": {
          "type": "boolean"
        },
        "profile": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string"
            },
            "givenName": {
              "type": "string"
            },
            "emailAddress": {
              "type": "string"
            },
            "telephoneNumber": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "UNKNOWN",
                "MALE",
                "FEMALE",
                "OTHER"
              ]
            },
            "birthdate": {
              "type": "string"
            },
            "streetAddress": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "postcode": {
              "type": "string"
            },
            "region": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "attributes": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "familyName",
            "givenName",
            "emailAddress"
          ]
        },
        "externalIdentifier": {
          "type": "string"
        },
        "authIdentifier": {
          "type": "string"
        },
        "linkedVenues": {
          "type": "array"
        },
        "id": {
          "type": "string"
        },
        "accountNumber": {
          "type": "number"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        },
        "flags": {
          "type": "object",
          "properties": {
            "genderProvided": {
              "type": "boolean"
            }
          }
        },
        "referralCodeUsedForRegistration": {
          "type": "object",
          "properties": {
            "inviteCode": {
              "type": "string"
            },
            "inviteLink": {
              "type": "string"
            },
            "campaign": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "linkConfig": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "desktopUrl": {
                      "type": "string"
                    },
                    "imageUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "iosUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "androidUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "title",
                    "description",
                    "desktopUrl"
                  ]
                },
                "isActive": {
                  "type": "boolean"
                },
                "tranches": {
                  "type": "array"
                },
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "linkConfig",
                "isActive",
                "id"
              ]
            },
            "referrer": {
              "type": "object",
              "properties": {}
            },
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "inviteCode",
            "inviteLink",
            "campaign",
            "id"
          ]
        }
      },
      "required": [
        "isRestricted",
        "profile",
        "authIdentifier",
        "id",
        "accountNumber",
        "createdAt",
        "updatedAt"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Update specific User
PATCH/users/{id}

Update the details of the user specified by their ID.

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:users scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the User to update.


DELETE api.rewards.wlloyalty.net/v1/users/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "affected": 1
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "affected": {
          "type": "number"
        }
      }
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Delete specific User
DELETE/users/{id}

Delete a specific user by their ID. Note that this operation deletes the profile data only. The top-level identifier information is retained to prevent conflicts

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:users scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the User to retrieve.


Active User

GET api.rewards.wlloyalty.net/v1/users/me
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "isRestricted": false,
    "profile": {
      "familyName": "Doe",
      "givenName": "Jane",
      "emailAddress": "jane.doe@example.com",
      "telephoneNumber": "01437 522633",
      "gender": "UNKNOWN",
      "birthdate": "1970-01-01",
      "streetAddress": "12 Bedford Street",
      "city": "Leeds",
      "postcode": "LS1 5PZ",
      "region": "West Yorkshire",
      "country": "GB",
      "pictureUrl": "https://example.com/pic.jpg",
      "attributes": {
        "key": "value"
      }
    },
    "externalIdentifier": "any string",
    "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "linkedVenues": [
      {
        "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
      }
    ],
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "accountNumber": 1000001,
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z",
    "flags": {
      "genderProvided": false
    },
    "referralCodeUsedForRegistration": {
      "inviteCode": "custom.app.link/XYI123sSD",
      "inviteLink": "custom.app.link/XYI123sSD",
      "campaign": {
        "name": "Holidays Referral Campaign",
        "linkConfig": {
          "title": "Join us!",
          "description": "Your friend has invited you to checkout this app",
          "desktopUrl": "www.custom-domain.com",
          "imageUrl": "imgur.com/12323",
          "iosUrl": "iosappstorelink",
          "androidUrl": "androidplaystorelink"
        },
        "isActive": true,
        "tranches": [],
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
        "createdAt": "2021-05-08T08:57:47.198Z",
        "updatedAt": "2021-05-08T08:57:47.198Z"
      },
      "referrer": {},
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
      "createdAt": "2021-06-08T08:57:47.198Z",
      "updatedAt": "2021-06-08T08:57:47.198Z"
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "isRestricted": {
          "type": "boolean"
        },
        "profile": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string"
            },
            "givenName": {
              "type": "string"
            },
            "emailAddress": {
              "type": "string"
            },
            "telephoneNumber": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "UNKNOWN",
                "MALE",
                "FEMALE",
                "OTHER"
              ]
            },
            "birthdate": {
              "type": "string"
            },
            "streetAddress": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "postcode": {
              "type": "string"
            },
            "region": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "attributes": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "familyName",
            "givenName",
            "emailAddress"
          ]
        },
        "externalIdentifier": {
          "type": "string"
        },
        "authIdentifier": {
          "type": "string"
        },
        "linkedVenues": {
          "type": "array"
        },
        "id": {
          "type": "string"
        },
        "accountNumber": {
          "type": "number"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        },
        "flags": {
          "type": "object",
          "properties": {
            "genderProvided": {
              "type": "boolean"
            }
          }
        },
        "referralCodeUsedForRegistration": {
          "type": "object",
          "properties": {
            "inviteCode": {
              "type": "string"
            },
            "inviteLink": {
              "type": "string"
            },
            "campaign": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "linkConfig": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "desktopUrl": {
                      "type": "string"
                    },
                    "imageUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "iosUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "androidUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "title",
                    "description",
                    "desktopUrl"
                  ]
                },
                "isActive": {
                  "type": "boolean"
                },
                "tranches": {
                  "type": "array"
                },
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "linkConfig",
                "isActive",
                "id"
              ]
            },
            "referrer": {
              "type": "object",
              "properties": {}
            },
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "inviteCode",
            "inviteLink",
            "campaign",
            "id"
          ]
        }
      },
      "required": [
        "isRestricted",
        "profile",
        "authIdentifier",
        "id",
        "accountNumber",
        "createdAt",
        "updatedAt"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve active User
GET/users/me

Retrieve the details of the currently authenticated user.

👤 User authorization required

Requests to this method must provide a Authorization header containing a valid user token signed as per the tenant authentication configuration. Non-compliant requests will be rejected.


PATCH api.rewards.wlloyalty.net/v1/users/me
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "isRestricted": false,
  "profile": {
    "familyName": "Doe",
    "givenName": "Jane",
    "emailAddress": "jane.doe@example.com",
    "telephoneNumber": "01437 522633",
    "gender": "UNKNOWN",
    "birthdate": "1970-01-01",
    "streetAddress": "12 Bedford Street",
    "city": "Leeds",
    "postcode": "LS1 5PZ",
    "region": "West Yorkshire",
    "country": "GB",
    "pictureUrl": "https://example.com/pic.jpg",
    "attributes": {
      "key": "value"
    }
  },
  "externalIdentifier": "any string",
  "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "linkedVenues": [
    {
      "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
    }
  ],
  "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "accountNumber": 1000001,
  "createdAt": "2018-06-08T08:57:47.198Z",
  "updatedAt": "2018-06-08T08:57:47.198Z",
  "flags": {
    "genderProvided": false
  },
  "referralCodeUsedForRegistration": {
    "inviteCode": "custom.app.link/XYI123sSD",
    "inviteLink": "custom.app.link/XYI123sSD",
    "campaign": {
      "name": "Holidays Referral Campaign",
      "linkConfig": {
        "title": "Join us!",
        "description": "Your friend has invited you to checkout this app",
        "desktopUrl": "www.custom-domain.com",
        "imageUrl": "imgur.com/12323",
        "iosUrl": "iosappstorelink",
        "androidUrl": "androidplaystorelink"
      },
      "isActive": true,
      "tranches": [],
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
      "createdAt": "2021-05-08T08:57:47.198Z",
      "updatedAt": "2021-05-08T08:57:47.198Z"
    },
    "referrer": {},
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
    "createdAt": "2021-06-08T08:57:47.198Z",
    "updatedAt": "2021-06-08T08:57:47.198Z"
  }
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "isRestricted": false,
    "profile": {
      "familyName": "Doe",
      "givenName": "Jane",
      "emailAddress": "jane.doe@example.com",
      "telephoneNumber": "01437 522633",
      "gender": "UNKNOWN",
      "birthdate": "1970-01-01",
      "streetAddress": "12 Bedford Street",
      "city": "Leeds",
      "postcode": "LS1 5PZ",
      "region": "West Yorkshire",
      "country": "GB",
      "pictureUrl": "https://example.com/pic.jpg",
      "attributes": {
        "key": "value"
      }
    },
    "externalIdentifier": "any string",
    "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "linkedVenues": [
      {
        "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
      }
    ],
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "accountNumber": 1000001,
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z",
    "flags": {
      "genderProvided": false
    },
    "referralCodeUsedForRegistration": {
      "inviteCode": "custom.app.link/XYI123sSD",
      "inviteLink": "custom.app.link/XYI123sSD",
      "campaign": {
        "name": "Holidays Referral Campaign",
        "linkConfig": {
          "title": "Join us!",
          "description": "Your friend has invited you to checkout this app",
          "desktopUrl": "www.custom-domain.com",
          "imageUrl": "imgur.com/12323",
          "iosUrl": "iosappstorelink",
          "androidUrl": "androidplaystorelink"
        },
        "isActive": true,
        "tranches": [],
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
        "createdAt": "2021-05-08T08:57:47.198Z",
        "updatedAt": "2021-05-08T08:57:47.198Z"
      },
      "referrer": {},
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
      "createdAt": "2021-06-08T08:57:47.198Z",
      "updatedAt": "2021-06-08T08:57:47.198Z"
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "isRestricted": {
          "type": "boolean"
        },
        "profile": {
          "type": "object",
          "properties": {
            "familyName": {
              "type": "string"
            },
            "givenName": {
              "type": "string"
            },
            "emailAddress": {
              "type": "string"
            },
            "telephoneNumber": {
              "type": "string"
            },
            "gender": {
              "type": "string",
              "enum": [
                "UNKNOWN",
                "MALE",
                "FEMALE",
                "OTHER"
              ]
            },
            "birthdate": {
              "type": "string"
            },
            "streetAddress": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "postcode": {
              "type": "string"
            },
            "region": {
              "type": "string"
            },
            "country": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "attributes": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "familyName",
            "givenName",
            "emailAddress"
          ]
        },
        "externalIdentifier": {
          "type": "string"
        },
        "authIdentifier": {
          "type": "string"
        },
        "linkedVenues": {
          "type": "array"
        },
        "id": {
          "type": "string"
        },
        "accountNumber": {
          "type": "number"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        },
        "flags": {
          "type": "object",
          "properties": {
            "genderProvided": {
              "type": "boolean"
            }
          }
        },
        "referralCodeUsedForRegistration": {
          "type": "object",
          "properties": {
            "inviteCode": {
              "type": "string"
            },
            "inviteLink": {
              "type": "string"
            },
            "campaign": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "linkConfig": {
                  "type": "object",
                  "properties": {
                    "title": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "desktopUrl": {
                      "type": "string"
                    },
                    "imageUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "iosUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "androidUrl": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "title",
                    "description",
                    "desktopUrl"
                  ]
                },
                "isActive": {
                  "type": "boolean"
                },
                "tranches": {
                  "type": "array"
                },
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                }
              },
              "required": [
                "name",
                "linkConfig",
                "isActive",
                "id"
              ]
            },
            "referrer": {
              "type": "object",
              "properties": {}
            },
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "inviteCode",
            "inviteLink",
            "campaign",
            "id"
          ]
        }
      },
      "required": [
        "isRestricted",
        "profile",
        "authIdentifier",
        "id",
        "accountNumber",
        "createdAt",
        "updatedAt"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Update active User
PATCH/users/me

Update the details of the currently authenticated user.

👤 User authorization required

Requests to this method must provide a Authorization header containing a valid user token signed as per the tenant authentication configuration. Non-compliant requests will be rejected.


Specific User wallet

GET api.rewards.wlloyalty.net/v1/users/9cb2cc08-e033-4200-86a7-95a03ba09462/wallet
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "points": 0,
    "tier": {
      "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
      "name": "Gold"
    },
    "lifetimeEarn": 0,
    "loyaltyCost": 0,
    "vouchers": [
      {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "redeemedAt": "2018-06-08T08:57:47.198Z",
        "reward": {
          "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
          "createdAt": "2018-06-08T08:57:47.198Z",
          "updatedAt": "2018-06-08T08:57:47.198Z",
          "name": "Free Cup of Coffee",
          "pictureUrl": "https://example.com/pic.jpg",
          "price": 0,
          "priority": 0,
          "availability": {
            "start": "2018-06-08T18:19:10.878Z",
            "end": "2018-06-09T18:19:10.878Z"
          }
        },
        "code": null
      }
    ]
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "points": {
          "type": "number"
        },
        "tier": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "lifetimeEarn": {
          "type": "number"
        },
        "loyaltyCost": {
          "type": "number"
        },
        "vouchers": {
          "type": "array"
        }
      },
      "required": [
        "points",
        "lifetimeEarn",
        "loyaltyCost"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve specific wallet
GET/users/{id}/wallet

Retrieve the loyalty wallet of the user specified by their ID.

Vouchers returned in the response have two timestamps of interest:

  1. createdAt: this timestamp represents when the user purchased or otherwise received the voucher.
  2. redeemedAt: this timestamp represents when the user initiated the redemption flow for the voucher.

The redeemedAt property will be null if the voucher has not yet been redeemed. While the voucher is unredeemed the code property will also be null. Once the voucher is redeemed by the user, subsequent requests to this endpoint will reveal the code object. Once the redemption has expired or has been explicitly validated the voucher will disappear from this endpoint’s response.

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with at least read:users scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the User for whom the wallet should be retrieved.


Active User wallet

GET api.rewards.wlloyalty.net/v1/users/me/wallet
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "points": 0,
    "tier": {
      "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
      "name": "Gold"
    },
    "vouchers": [
      {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "redeemedAt": "2018-06-08T08:57:47.198Z",
        "reward": {
          "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
          "createdAt": "2018-06-08T08:57:47.198Z",
          "updatedAt": "2018-06-08T08:57:47.198Z",
          "name": "Free Cup of Coffee",
          "pictureUrl": "https://example.com/pic.jpg",
          "price": 0,
          "priority": 0,
          "availability": {
            "start": "2018-06-08T18:19:10.878Z",
            "end": "2018-06-09T18:19:10.878Z"
          }
        },
        "code": null
      }
    ]
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "points": {
          "type": "number"
        },
        "tier": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "vouchers": {
          "type": "array"
        }
      },
      "required": [
        "points"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve active wallet
GET/users/me/wallet

Retrieve the loyalty wallet of the currently authenticated user.

👤 User authorization required

Requests to this method must provide a Authorization header containing a valid user token signed as per the tenant authentication configuration. Non-compliant requests will be rejected.


Active User Purchases

POST api.rewards.wlloyalty.net/v1/users/me/purchases
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "resource": {
    "type": "VOUCHER_REWARD",
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
  }
}
Responses201
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "resource": {
      "type": "VOUCHER_REWARD",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "resource": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "VOUCHER_REWARD"
              ]
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "id"
          ]
        }
      },
      "required": [
        "resource"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Trigger Purchase
POST/users/me/purchases

Use this endpoint to trigger a purchase of the provided resource for the currently authenticated user.

👤 User authorization required

Requests to this method must provide a Authorization header containing a valid user token signed as per the tenant authentication configuration. Non-compliant requests will be rejected.


Active User Redemptions

POST api.rewards.wlloyalty.net/v1/users/me/redemptions
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "resource": {
    "type": "VOUCHER",
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
  },
  "position": {
    "longitude": 170.9021,
    "latitude": 80.9021
  }
}
Responses201
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "resource": {
      "type": "VOUCHER",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "position": {
      "longitude": 170.9021,
      "latitude": 80.9021
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "resource": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "VOUCHER"
              ]
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "id"
          ]
        },
        "position": {
          "type": "object",
          "properties": {
            "longitude": {
              "type": "number"
            },
            "latitude": {
              "type": "number"
            }
          },
          "required": [
            "longitude",
            "latitude"
          ]
        }
      },
      "required": [
        "resource"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Trigger Redemption
POST/users/me/redemptions

Use this endpoint to trigger a redemption of the provided resource for the currently authenticated user.

👤 User authorization required

Requests to this method must provide a Authorization header containing a valid user token signed as per the tenant authentication configuration. Non-compliant requests will be rejected.


Referral Campaigns

Specific User Referral Code

POST api.rewards.wlloyalty.net/v1/users/9cb2cc08-e033-4200-86a7-95a03ba09462/referral_code
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "inviteCode": "custom.app.link/XYI123sSD",
    "inviteLink": "custom.app.link/XYI123sSD",
    "campaign": {
      "name": "Holidays Referral Campaign",
      "linkConfig": {
        "title": "Join us!",
        "description": "Your friend has invited you to checkout this app",
        "desktopUrl": "www.custom-domain.com",
        "imageUrl": "imgur.com/12323",
        "iosUrl": "iosappstorelink",
        "androidUrl": "androidplaystorelink"
      },
      "isActive": true,
      "tranches": [],
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
      "createdAt": "2021-05-08T08:57:47.198Z",
      "updatedAt": "2021-05-08T08:57:47.198Z"
    },
    "referrer": {
      "isRestricted": false,
      "profile": {
        "familyName": "Doe",
        "givenName": "Jane",
        "emailAddress": "jane.doe@example.com",
        "telephoneNumber": "01437 522633",
        "gender": "UNKNOWN",
        "birthdate": "1970-01-01",
        "streetAddress": "12 Bedford Street",
        "city": "Leeds",
        "postcode": "LS1 5PZ",
        "region": "West Yorkshire",
        "country": "GB",
        "pictureUrl": "https://example.com/pic.jpg",
        "attributes": {
          "key": "value"
        }
      },
      "externalIdentifier": "any string",
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "linkedVenues": [
        {
          "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
        }
      ],
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      },
      "referralCodeUsedForRegistration": {}
    },
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
    "createdAt": "2021-06-08T08:57:47.198Z",
    "updatedAt": "2021-06-08T08:57:47.198Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "inviteCode": {
          "type": "string"
        },
        "inviteLink": {
          "type": "string"
        },
        "campaign": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "linkConfig": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "desktopUrl": {
                  "type": "string"
                },
                "imageUrl": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "iosUrl": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "androidUrl": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "title",
                "description",
                "desktopUrl"
              ]
            },
            "isActive": {
              "type": "boolean"
            },
            "tranches": {
              "type": "array"
            },
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "linkConfig",
            "isActive",
            "id"
          ]
        },
        "referrer": {
          "type": "object",
          "properties": {
            "isRestricted": {
              "type": "boolean"
            },
            "profile": {
              "type": "object",
              "properties": {
                "familyName": {
                  "type": "string"
                },
                "givenName": {
                  "type": "string"
                },
                "emailAddress": {
                  "type": "string"
                },
                "telephoneNumber": {
                  "type": "string"
                },
                "gender": {
                  "type": "string",
                  "enum": [
                    "UNKNOWN",
                    "MALE",
                    "FEMALE",
                    "OTHER"
                  ]
                },
                "birthdate": {
                  "type": "string"
                },
                "streetAddress": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "postcode": {
                  "type": "string"
                },
                "region": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                },
                "attributes": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string"
                    }
                  }
                }
              },
              "required": [
                "familyName",
                "givenName",
                "emailAddress"
              ]
            },
            "externalIdentifier": {
              "type": "string"
            },
            "authIdentifier": {
              "type": "string"
            },
            "linkedVenues": {
              "type": "array"
            },
            "id": {
              "type": "string"
            },
            "accountNumber": {
              "type": "number"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "flags": {
              "type": "object",
              "properties": {
                "genderProvided": {
                  "type": "boolean"
                }
              }
            },
            "referralCodeUsedForRegistration": {
              "type": "object",
              "properties": {}
            }
          },
          "required": [
            "isRestricted",
            "profile",
            "authIdentifier",
            "id",
            "accountNumber",
            "createdAt",
            "updatedAt"
          ]
        },
        "id": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "inviteCode",
        "inviteLink",
        "campaign",
        "id"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Generate referral code for specific user
POST/users/{id}/referral_code

Use this endpoint to generate a referral code for a specific user. This should ideally be called when the user is ready to share their referral code with their friends.

Referral code data returned in the response has the following keys of interest:

  1. inviteCode: this represents a referral code (eg: REF200) that a new user can manually copy/paste in a referral code field during sign up.
  2. inviteLink: this represents a referral link (eg: custom.app.link/X22TUV) that can simply be clicked to first redirect the new user to an app store and then to automatically pre-fill the referral code field during sign up.

In most cases, the inviteCode and the inviteLink generated would be the same link. The user can copy and paste this link during sign up if needed, and use it like a manually usable referral code. To keep it simple, in such cases where both the values are the same, you can just use the inviteLink for sharing purposes.

The campaign property contains metadata about the referral campaign that was previously setup using WLL’s console. The campaign property itself consists of properties like the name of the campaign for admin purposes, and linkConfig. The data contained in this linkConfig property can be used to construct a message that can be shared by the user along with the referral code. For eg, the title property can be used as the title of the message, and description as the body of the message.

The referrer property simply contains the details of the User this referral code is being generated for.

Once the referral code/link is generated for the user, subsequent requests to this endpoint can either return the existing referral code or generate a new one depending on some factors. One of the factors is whether a new referral campaign was active at the time of generation of the referral code or not.

The referral code/link generated is unique for the referrer user, and a single referrer user can have many referral codes/links generated for them over their lifetime.

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with at least admin:users scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the User for whom the referral code should be generated.


Active User Referral Code

POST api.rewards.wlloyalty.net/v1/users/me/referral_code
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "inviteCode": "custom.app.link/XYI123sSD",
    "inviteLink": "custom.app.link/XYI123sSD",
    "campaign": {
      "name": "Holidays Referral Campaign",
      "linkConfig": {
        "title": "Join us!",
        "description": "Your friend has invited you to checkout this app",
        "desktopUrl": "www.custom-domain.com",
        "imageUrl": "imgur.com/12323",
        "iosUrl": "iosappstorelink",
        "androidUrl": "androidplaystorelink"
      },
      "isActive": true,
      "tranches": [],
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
      "createdAt": "2021-05-08T08:57:47.198Z",
      "updatedAt": "2021-05-08T08:57:47.198Z"
    },
    "referrer": {
      "isRestricted": false,
      "profile": {
        "familyName": "Doe",
        "givenName": "Jane",
        "emailAddress": "jane.doe@example.com",
        "telephoneNumber": "01437 522633",
        "gender": "UNKNOWN",
        "birthdate": "1970-01-01",
        "streetAddress": "12 Bedford Street",
        "city": "Leeds",
        "postcode": "LS1 5PZ",
        "region": "West Yorkshire",
        "country": "GB",
        "pictureUrl": "https://example.com/pic.jpg",
        "attributes": {
          "key": "value"
        }
      },
      "externalIdentifier": "any string",
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "linkedVenues": [
        {
          "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
        }
      ],
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      },
      "referralCodeUsedForRegistration": {}
    },
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
    "createdAt": "2021-06-08T08:57:47.198Z",
    "updatedAt": "2021-06-08T08:57:47.198Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "inviteCode": {
          "type": "string"
        },
        "inviteLink": {
          "type": "string"
        },
        "campaign": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            },
            "linkConfig": {
              "type": "object",
              "properties": {
                "title": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "desktopUrl": {
                  "type": "string"
                },
                "imageUrl": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "iosUrl": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "androidUrl": {
                  "type": [
                    "string",
                    "null"
                  ]
                }
              },
              "required": [
                "title",
                "description",
                "desktopUrl"
              ]
            },
            "isActive": {
              "type": "boolean"
            },
            "tranches": {
              "type": "array"
            },
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          },
          "required": [
            "name",
            "linkConfig",
            "isActive",
            "id"
          ]
        },
        "referrer": {
          "type": "object",
          "properties": {
            "isRestricted": {
              "type": "boolean"
            },
            "profile": {
              "type": "object",
              "properties": {
                "familyName": {
                  "type": "string"
                },
                "givenName": {
                  "type": "string"
                },
                "emailAddress": {
                  "type": "string"
                },
                "telephoneNumber": {
                  "type": "string"
                },
                "gender": {
                  "type": "string",
                  "enum": [
                    "UNKNOWN",
                    "MALE",
                    "FEMALE",
                    "OTHER"
                  ]
                },
                "birthdate": {
                  "type": "string"
                },
                "streetAddress": {
                  "type": "string"
                },
                "city": {
                  "type": "string"
                },
                "postcode": {
                  "type": "string"
                },
                "region": {
                  "type": "string"
                },
                "country": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                },
                "attributes": {
                  "type": "object",
                  "properties": {
                    "key": {
                      "type": "string"
                    }
                  }
                }
              },
              "required": [
                "familyName",
                "givenName",
                "emailAddress"
              ]
            },
            "externalIdentifier": {
              "type": "string"
            },
            "authIdentifier": {
              "type": "string"
            },
            "linkedVenues": {
              "type": "array"
            },
            "id": {
              "type": "string"
            },
            "accountNumber": {
              "type": "number"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "flags": {
              "type": "object",
              "properties": {
                "genderProvided": {
                  "type": "boolean"
                }
              }
            },
            "referralCodeUsedForRegistration": {
              "type": "object",
              "properties": {}
            }
          },
          "required": [
            "isRestricted",
            "profile",
            "authIdentifier",
            "id",
            "accountNumber",
            "createdAt",
            "updatedAt"
          ]
        },
        "id": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "inviteCode",
        "inviteLink",
        "campaign",
        "id"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Generate referral code for active user
POST/users/me/referral_code

Generate a referral code for the currently authenticated user.

👤 User authorization required

Requests to this method must provide a Authorization header containing a valid user token signed as per the tenant authentication configuration. Non-compliant requests will be rejected.


Handle User's Referral Code activity

This can be either a Registration or a Click activity

For more information regarding handling Registration, see Register a new User

Vouchers

Voucher Validations

POST api.rewards.wlloyalty.net/v1/commands/validate_voucher
RequestsFullPartialPercentage DiscountInvalid
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "code": "625735",
  "userIdentifier": "1003607",
  "venueIdentifier": "71231",
  "position": {
    "longitude": 170.9021,
    "latitude": 80.9021
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "userIdentifier": {
      "type": "string"
    },
    "venueIdentifier": {
      "type": "string"
    },
    "position": {
      "type": "object",
      "properties": {
        "longitude": {
          "type": "number"
        },
        "latitude": {
          "type": "number"
        }
      },
      "required": [
        "longitude",
        "latitude"
      ]
    }
  },
  "required": [
    "code",
    "userIdentifier"
  ]
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "isValid": true,
    "voucher": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": "2018-06-08T08:57:47.198Z",
      "validatedAt": "2018-06-08T08:57:47.198Z"
    },
    "reward": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "name": "Free Cup of Coffee",
      "pictureUrl": "https://example.com/pic.jpg",
      "price": 0,
      "priority": 0,
      "availability": {
        "start": "2018-06-08T18:19:10.878Z",
        "end": "2018-06-09T18:19:10.878Z"
      }
    },
    "discounts": [
      {
        "type": "FIXED",
        "value": 1000,
        "sku": "321ZA",
        "productSku": "AZ123"
      }
    ]
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "isValid": {
          "type": "boolean"
        },
        "voucher": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": "string"
            },
            "validatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "createdAt",
            "redeemedAt",
            "validatedAt"
          ]
        },
        "reward": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "price": {
              "type": "number"
            },
            "priority": {
              "type": "number"
            },
            "availability": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "price",
            "priority",
            "availability"
          ]
        },
        "discounts": {
          "type": "array"
        }
      },
      "required": [
        "isValid",
        "voucher",
        "reward"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "code": "625735",
  "userIdentifier": "1003607"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "userIdentifier": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "userIdentifier"
  ]
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "isValid": true,
    "voucher": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": "2018-06-08T08:57:47.198Z",
      "validatedAt": "2018-06-08T08:57:47.198Z"
    },
    "reward": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "name": "Free Cup of Coffee",
      "pictureUrl": "https://example.com/pic.jpg",
      "price": 0,
      "priority": 0,
      "availability": {
        "start": "2018-06-08T18:19:10.878Z",
        "end": "2018-06-09T18:19:10.878Z"
      }
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "isValid": {
          "type": "boolean"
        },
        "voucher": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": "string"
            },
            "validatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "createdAt",
            "redeemedAt",
            "validatedAt"
          ]
        },
        "reward": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "price": {
              "type": "number"
            },
            "priority": {
              "type": "number"
            },
            "availability": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "price",
            "priority",
            "availability"
          ]
        }
      },
      "required": [
        "isValid",
        "voucher",
        "reward"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "code": "625735",
  "userIdentifier": "1003607"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "userIdentifier": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "userIdentifier"
  ]
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "isValid": true,
    "voucher": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": "2018-06-08T08:57:47.198Z",
      "validatedAt": "2018-06-08T08:57:47.198Z"
    },
    "reward": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "name": "Free Cup of Coffee",
      "pictureUrl": "https://example.com/pic.jpg",
      "price": 0,
      "priority": 0,
      "availability": {
        "start": "2018-06-08T18:19:10.878Z",
        "end": "2018-06-09T18:19:10.878Z"
      }
    },
    "discounts": [
      {
        "type": "PERCENTAGE",
        "value": 92
      }
    ]
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "isValid": {
          "type": "boolean"
        },
        "voucher": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": "string"
            },
            "validatedAt": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "createdAt",
            "redeemedAt",
            "validatedAt"
          ]
        },
        "reward": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "price": {
              "type": "number"
            },
            "priority": {
              "type": "number"
            },
            "availability": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "price",
            "priority",
            "availability"
          ]
        },
        "discounts": {
          "type": "array"
        }
      },
      "required": [
        "isValid",
        "voucher",
        "reward"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "code": "625735",
  "userIdentifier": "1003607"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "code": {
      "type": "string"
    },
    "userIdentifier": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "userIdentifier"
  ]
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "isValid": false,
    "reason": "INVALID_VENUE"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "isValid": {
          "type": "boolean"
        },
        "reason": {
          "type": "string",
          "enum": [
            "INVALID_VENUE",
            "REDEMPTION_EXPIRED",
            "ALREADY_VALIDATED",
            "OTHER"
          ]
        }
      },
      "required": [
        "isValid",
        "reason"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Validate voucher code
POST/commands/validate_voucher

Use this endpoint to check whether a voucher redemption code is valid for use by the specified user.

The code and userIdentifier fields are manadatory. The user identifier should be either the user.authIdentifier or the user.accountNumber.

The venueIdentifier and position fields are optional, however at least one should be provided to support validating venue-locked rewards. If neither is provided any validation requests for vouchers of venue-locked rewards will be rejected since the system will not be able to verify if the redemption is occuring at a valid venue.

The venueIdentifier should be either a valid venue.externalIdentifier or venue.id. The position should be the geocoordinates of the venue where the redemption is occuring.

Applying Discounts

The discount objects returned in this response represent how the redeemed voucher should be applied to the basket. Only the discounts relevant to the indicated venue will be returned.

Discount objects may contain sku and productSku fields. These fields are intended to represent the SKU of the discount itself (if any) and the SKU of the product on which the discount should be applied (if any).

Absolute Discounts

A discount with type: 'ABSOLUTE' indicates that the product or basket price should be adjusted relative to the price before discounting. The value is an integer which represents the adjustment amount in the lowest denomination of the currency. For example given a basket price of £1.50, applying an absolute discount of value: 100 would result in a new basket price of £0.50.

Percentage Discounts

A discount with type: 'PERCENTAGE' indicates that the product or basket price should be adjusted by the given percentage of the price before discounting. The value is an integer which represents the percentage 0-100. For example given a basket price of £1.50, applying a percentage discount of value: 10 would result in a new basket price of £1.35.

Fixed Discounts

A discount with type: 'FIXED' indicates that the product or basket price should be set to the given the price. The value is an integer which represents new price to set, in the lowest denomination of the currency. For example given a basket price of £1.50, applying an fixed discount of value: 100 would result in a new basket price of £1.00.

🔒 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with validate:vouchers scope. Non-compliant requests will be rejected.


Venues

Venues Collection

GET api.rewards.wlloyalty.net/v1/venues?limit=10&skip=0&sort=name&order=ASC&filter=createdAt:(gt:'2019-01-01T00:00:00')
RequestsDefault
Headers
X-Api-Key: $api_key
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "externalIdentifier": "anyidentifier123",
      "name": "starbucks",
      "address": "12 Road Street, Leeds, UK",
      "postcode": "LS1 5PZ",
      "coordinates": {
        "longitude": 170.9021,
        "latitude": 80.9021
      },
      "availability": {
        "start": "2018-06-08T18:19:10.878Z",
        "end": "2018-06-09T18:19:10.878Z"
      },
      "category": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "name": "Restaurants",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z"
      },
      "attributes": {
        "key": "value"
      },
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z"
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List all Venues
GET/venues{?limit,skip,sort,order,filter}

Get a list of all venues defined within your tenant.

🔑 No authorization required

Requests to this method do not require any authorization other than a valid API key.

Filtering

It is possible to apply basic filter conditions to the result set using the filter query parameter. This parameter accepts an O-Rison encoded JSON object expressing the set of conditions to be applied.

The general format of this filter object (expressed in JSON) is as follows:

{
  "field1": { "operator": "value" },
  "field2": { "operator": "value" }
}

Where field1 and field2 are field names of this entity, operator is one of [eq, neq, gt, lt, in, has], and "value" is the exact value to compare against. The value need not necessarily be a string, the type appropriate for the field should be used. See the O-Rison documentation for help on how to format other types. Dates and datetimes should be passed as ISO 8601 strings.

The same filter encoded as O-Rison would be as follows:

field1:(operator:'value'),field2:(operator:'value')
URI Parameters
HideShow
limit
number (optional) Example: 10

The number of items to retrieve.

skip
number (optional) Example: 0

The number of items to skip before selecting.

sort
string (optional) Example: name

The property to use for sorting.

Choices: name address externalId createdAt updatedAt

order
string (optional) Example: ASC

The order to sort items.

Choices: ASC DESC

filter
string (optional) Example: createdAt:(gt:'2019-01-01T00:00:00')

O-Rison encoded filter string


POST api.rewards.wlloyalty.net/v1/venues
RequestsDefault
Headers
Content-Type: application/json
Body
{
  "name": "starbucks",
  "address": "12 Road Street, Leeds, UK",
  "postcode": "LS1 5PZ",
  "coordinates": {
    "longitude": 170.9021,
    "latitude": 80.9021
  },
  "availability": {
    "start": "2018-06-08T18:19:10.878Z",
    "end": "2018-06-09T18:19:10.878Z"
  }
}
Responses201
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "externalIdentifier": "anyidentifier123",
    "name": "starbucks",
    "address": "12 Road Street, Leeds, UK",
    "postcode": "LS1 5PZ",
    "coordinates": {
      "longitude": 170.9021,
      "latitude": 80.9021
    },
    "availability": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "category": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "name": "Restaurants",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z"
    },
    "attributes": {
      "key": "value"
    },
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "externalIdentifier": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "postcode": {
          "type": "string"
        },
        "coordinates": {
          "type": "object",
          "properties": {
            "longitude": {
              "type": "number"
            },
            "latitude": {
              "type": "number"
            }
          },
          "required": [
            "longitude",
            "latitude"
          ]
        },
        "availability": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "category": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          }
        },
        "attributes": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string"
            }
          }
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Create a Venue
POST/venues

Create a new Venue.

🔒 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:venues scope. Non-compliant requests will be rejected.


Individual Venue

GET api.rewards.wlloyalty.net/v1/venues/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
X-Api-Key: $api_key
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "externalIdentifier": "anyidentifier123",
    "name": "starbucks",
    "address": "12 Road Street, Leeds, UK",
    "postcode": "LS1 5PZ",
    "coordinates": {
      "longitude": 170.9021,
      "latitude": 80.9021
    },
    "availability": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "category": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "name": "Restaurants",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z"
    },
    "attributes": {
      "key": "value"
    },
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "externalIdentifier": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "postcode": {
          "type": "string"
        },
        "coordinates": {
          "type": "object",
          "properties": {
            "longitude": {
              "type": "number"
            },
            "latitude": {
              "type": "number"
            }
          },
          "required": [
            "longitude",
            "latitude"
          ]
        },
        "availability": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "category": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          }
        },
        "attributes": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string"
            }
          }
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve a Venue
GET/venues/{id}

Retrieve the details of a single Venue.

🔑 No authorization required

Requests to this method do not require any authorization other than a valid API key.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the Venue to Retrieve.


PATCH api.rewards.wlloyalty.net/v1/venues/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
Content-Type: application/json
Body
{
  "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "externalIdentifier": "anyidentifier123",
  "name": "starbucks",
  "address": "12 Road Street, Leeds, UK",
  "postcode": "LS1 5PZ",
  "coordinates": {
    "longitude": 170.9021,
    "latitude": 80.9021
  },
  "availability": {
    "start": "2018-06-08T18:19:10.878Z",
    "end": "2018-06-09T18:19:10.878Z"
  },
  "category": {
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "name": "Restaurants",
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z"
  },
  "attributes": {
    "key": "value"
  },
  "shouldCalculateCoordinates": false
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "externalIdentifier": "anyidentifier123",
    "name": "starbucks",
    "address": "12 Road Street, Leeds, UK",
    "postcode": "LS1 5PZ",
    "coordinates": {
      "longitude": 170.9021,
      "latitude": 80.9021
    },
    "availability": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "category": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "name": "Restaurants",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z"
    },
    "attributes": {
      "key": "value"
    },
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "externalIdentifier": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "postcode": {
          "type": "string"
        },
        "coordinates": {
          "type": "object",
          "properties": {
            "longitude": {
              "type": "number"
            },
            "latitude": {
              "type": "number"
            }
          },
          "required": [
            "longitude",
            "latitude"
          ]
        },
        "availability": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "category": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          }
        },
        "attributes": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string"
            }
          }
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Update a Venue
PATCH/venues/{id}

Update the details of a single Venue.

If you are updating the address of the venue and you want the system to automatically calculate new coordinates based on the address you can pass shouldCalculateCoordinates: true. This behaviour is opt-in.

🔒 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:venues scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the Venue to update.


DELETE api.rewards.wlloyalty.net/v1/venues/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
Content-Type: application/json
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "externalIdentifier": "anyidentifier123",
    "name": "starbucks",
    "address": "12 Road Street, Leeds, UK",
    "postcode": "LS1 5PZ",
    "coordinates": {
      "longitude": 170.9021,
      "latitude": 80.9021
    },
    "availability": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "category": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "name": "Restaurants",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z"
    },
    "attributes": {
      "key": "value"
    },
    "createdAt": "2018-06-08T08:57:47.198Z",
    "updatedAt": "2018-06-08T08:57:47.198Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "externalIdentifier": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "address": {
          "type": "string"
        },
        "postcode": {
          "type": "string"
        },
        "coordinates": {
          "type": "object",
          "properties": {
            "longitude": {
              "type": "number"
            },
            "latitude": {
              "type": "number"
            }
          },
          "required": [
            "longitude",
            "latitude"
          ]
        },
        "availability": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "category": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            }
          }
        },
        "attributes": {
          "type": "object",
          "properties": {
            "key": {
              "type": "string"
            }
          }
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Delete a Venue
DELETE/venues/{id}

Delete a Venue. Note that the venue will be marked as no longer available, rather than being fully removed from the platform and will remain accessible via the WLL Console.

🔒 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:venues scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the Venue to delete.


Venue Rewards

GET api.rewards.wlloyalty.net/v1/venues/9cb2cc08-e033-4200-86a7-95a03ba09462/rewards?limit=10&skip=0&sort=name&order=ASC&filter=createdAt:(gt:'2019-01-01T00:00:00')
RequestsDefault
Headers
X-Api-Key: $api_key
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "name": "Free Cup of Coffee",
      "pictureUrl": "https://example.com/pic.jpg",
      "price": 0,
      "priority": 0,
      "availability": {
        "start": "2018-06-08T18:19:10.878Z",
        "end": "2018-06-09T18:19:10.878Z"
      },
      "purchasable": false,
      "description": "Redeem this reward for a free cup of coffee",
      "terms": "",
      "value": 0,
      "discounts": [
        {
          "type": "FIXED",
          "value": 1000,
          "sku": "321ZA",
          "productSku": "AZ123"
        }
      ],
      "tier": {
        "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
        "name": "Gold",
        "priority": 0
      },
      "venues": [
        {
          "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
          "externalIdentifier": "anyidentifier123",
          "name": "starbucks"
        }
      ]
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List Venue Rewards
GET/venues/{id}/rewards{?limit,skip,sort,order,filter}

Get a list of any rewards which have been explicitly assigned to this venue.

🔑 No authorization required

Requests to this method do not require any authorization other than a valid API key.

Filtering

It is possible to apply basic filter conditions to the result set using the filter query parameter. This parameter accepts an O-Rison encoded JSON object expressing the set of conditions to be applied.

The general format of this filter object (expressed in JSON) is as follows:

{
  "field1": { "operator": "value" },
  "field2": { "operator": "value" }
}

Where field1 and field2 are field names of this entity, operator is one of [eq, neq, gt, lt, in, has], and "value" is the exact value to compare against. The value need not necessarily be a string, the type appropriate for the field should be used. See the O-Rison documentation for help on how to format other types. Dates and datetimes should be passed as ISO 8601 strings.

The same filter encoded as O-Rison would be as follows:

field1:(operator:'value'),field2:(operator:'value')
URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the Venue for which rewards should be retrieved.

limit
number (optional) Example: 10

The number of items to retrieve.

skip
number (optional) Example: 0

The number of items to skip before selecting.

sort
string (optional) Example: name

The property to use for sorting.

Choices: priority price value name

order
string (optional) Example: ASC

The order to sort items.

Choices: ASC DESC

filter
string (optional) Example: createdAt:(gt:'2019-01-01T00:00:00')

O-Rison encoded filter string


Venue Users

GET api.rewards.wlloyalty.net/v1/venues/9cb2cc08-e033-4200-86a7-95a03ba09462/users?limit=10&skip=0&sort=id&order=ASC&filter=createdAt:(gt:'2019-01-01T00:00:00')
RequestsDefault
Headers
X-Api-Key: $api_key
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "isRestricted": false,
      "profile": {
        "familyName": "Doe",
        "givenName": "Jane",
        "emailAddress": "jane.doe@example.com",
        "telephoneNumber": "01437 522633",
        "gender": "UNKNOWN",
        "birthdate": "1970-01-01",
        "streetAddress": "12 Bedford Street",
        "city": "Leeds",
        "postcode": "LS1 5PZ",
        "region": "West Yorkshire",
        "country": "GB",
        "pictureUrl": "https://example.com/pic.jpg",
        "attributes": {
          "key": "value"
        }
      },
      "externalIdentifier": "any string",
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "linkedVenues": [
        {
          "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
        }
      ],
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      },
      "referralCodeUsedForRegistration": {
        "inviteCode": "custom.app.link/XYI123sSD",
        "inviteLink": "custom.app.link/XYI123sSD",
        "campaign": {
          "name": "Holidays Referral Campaign",
          "linkConfig": {
            "title": "Join us!",
            "description": "Your friend has invited you to checkout this app",
            "desktopUrl": "www.custom-domain.com",
            "imageUrl": "imgur.com/12323",
            "iosUrl": "iosappstorelink",
            "androidUrl": "androidplaystorelink"
          },
          "isActive": true,
          "tranches": [],
          "id": "9cb2cc08-e033-4200-86a7-95a03ba09400",
          "createdAt": "2021-05-08T08:57:47.198Z",
          "updatedAt": "2021-05-08T08:57:47.198Z"
        },
        "referrer": {},
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
        "createdAt": "2021-06-08T08:57:47.198Z",
        "updatedAt": "2021-06-08T08:57:47.198Z"
      }
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List Venue Users
GET/venues/{id}/users{?limit,skip,sort,order,filter}

Get a list of any users which have been explicitly linked to this venue.

🔒 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:tiers scope. Non-compliant requests will be rejected.

Filtering

It is possible to apply basic filter conditions to the result set using the filter query parameter. This parameter accepts an O-Rison encoded JSON object expressing the set of conditions to be applied.

The general format of this filter object (expressed in JSON) is as follows:

{
  "field1": { "operator": "value" },
  "field2": { "operator": "value" }
}

Where field1 and field2 are field names of this entity, operator is one of [eq, neq, gt, lt, in, has], and "value" is the exact value to compare against. The value need not necessarily be a string, the type appropriate for the field should be used. See the O-Rison documentation for help on how to format other types. Dates and datetimes should be passed as ISO 8601 strings.

The same filter encoded as O-Rison would be as follows:

field1:(operator:'value'),field2:(operator:'value')
URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the Venue for which rewards should be retrieved.

limit
number (optional) Example: 10

The number of items to retrieve.

skip
number (optional) Example: 0

The number of items to skip before selecting.

sort
string (optional) Example: id

The property to use for sorting.

Choices: id givenName familyName emailAddress externalId createdAt updatedAt

order
string (optional) Example: ASC

The order to sort items.

Choices: ASC DESC

filter
string (optional) Example: createdAt:(gt:'2019-01-01T00:00:00')

O-Rison encoded filter string


Tiers

Tiers Collection

GET api.rewards.wlloyalty.net/v1/tiers?limit=10&skip=0&sort=name&order=ASC&filter=createdAt:(gt:'2019-01-01T00:00:00')
RequestsStandard UserAdmin
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
      "name": "Gold",
      "priority": 0,
      "pointsRequirement": 1000,
      "calculation": "LIFETIME_EARN",
      "accumulationPeriod": "P1Y",
      "effectivity": {
        "start": "2018-06-08T18:19:10.878Z",
        "end": "2018-06-09T18:19:10.878Z"
      },
      "createdAt": "2019-04-09T10:02:37.515Z",
      "updatedAt": "2019-04-09T10:02:37.515Z",
      "earnedPoints": 87,
      "attained": false
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
      "name": "Gold",
      "priority": 0,
      "pointsRequirement": 1000,
      "calculation": "LIFETIME_EARN",
      "accumulationPeriod": "P1Y",
      "effectivity": {
        "start": "2018-06-08T18:19:10.878Z",
        "end": "2018-06-09T18:19:10.878Z"
      },
      "createdAt": "2019-04-09T10:02:37.515Z",
      "updatedAt": "2019-04-09T10:02:37.515Z"
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List all Tiers
GET/tiers{?limit,skip,sort,order,filter}

Get a list of all tiers defined within your tenant. If this method is called with standard user authorization the tier response will include the number of points the user has earned towards this tier plus a simple boolean of whether or not the user has attained the tier.

You can see the different response data by switching between the two defined requests on the right.

🔐 Multiple authorization modes

Requests to this method require either:

👤 User Authorization

🔒 Admin Authorization with admin:tiers scope

Details are explained above. Non-compliant requests will be rejected.

Filtering

It is possible to apply basic filter conditions to the result set using the filter query parameter. This parameter accepts an O-Rison encoded JSON object expressing the set of conditions to be applied.

The general format of this filter object (expressed in JSON) is as follows:

{
  "field1": { "operator": "value" },
  "field2": { "operator": "value" }
}

Where field1 and field2 are field names of this entity, operator is one of [eq, neq, gt, lt, in, has], and "value" is the exact value to compare against. The value need not necessarily be a string, the type appropriate for the field should be used. See the O-Rison documentation for help on how to format other types. Dates and datetimes should be passed as ISO 8601 strings.

The same filter encoded as O-Rison would be as follows:

field1:(operator:'value'),field2:(operator:'value')
URI Parameters
HideShow
limit
number (optional) Example: 10

The number of items to retrieve.

skip
number (optional) Example: 0

The number of items to skip before selecting.

sort
string (optional) Example: name

The property to use for sorting.

Choices: name points createdAt updatedAt

order
string (optional) Example: ASC

The order to sort items.

Choices: ASC DESC

filter
string (optional) Example: createdAt:(gt:'2019-01-01T00:00:00')

O-Rison encoded filter string


POST api.rewards.wlloyalty.net/v1/tiers
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "name": "Gold",
  "priority": 0,
  "pointsRequirement": 1000,
  "calculation": "LIFETIME_EARN",
  "accumulationPeriod": "P1Y"
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
    "name": "Gold",
    "priority": 0,
    "pointsRequirement": 1000,
    "calculation": "LIFETIME_EARN",
    "accumulationPeriod": "P1Y",
    "effectivity": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "createdAt": "2019-04-09T10:02:37.515Z",
    "updatedAt": "2019-04-09T10:02:37.515Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "priority": {
          "type": "number"
        },
        "pointsRequirement": {
          "type": "number"
        },
        "calculation": {
          "type": "string",
          "enum": [
            "LIFETIME_EARN",
            "CALENDAR_PERIOD"
          ]
        },
        "accumulationPeriod": {
          "type": "string",
          "enum": [
            "P1Y",
            "P1M"
          ]
        },
        "effectivity": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "priority",
        "pointsRequirement",
        "calculation"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Create a Tier
POST/tiers

Create a new Tier.

🔒 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:tiers scope. Non-compliant requests will be rejected.


Individual Tier

GET api.rewards.wlloyalty.net/v1/tiers/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
    "name": "Gold",
    "priority": 0,
    "pointsRequirement": 1000,
    "calculation": "LIFETIME_EARN",
    "accumulationPeriod": "P1Y",
    "effectivity": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "createdAt": "2019-04-09T10:02:37.515Z",
    "updatedAt": "2019-04-09T10:02:37.515Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "priority": {
          "type": "number"
        },
        "pointsRequirement": {
          "type": "number"
        },
        "calculation": {
          "type": "string",
          "enum": [
            "LIFETIME_EARN",
            "CALENDAR_PERIOD"
          ]
        },
        "accumulationPeriod": {
          "type": "string",
          "enum": [
            "P1Y",
            "P1M"
          ]
        },
        "effectivity": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "priority",
        "pointsRequirement",
        "calculation"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve a Tier
GET/tiers/{id}

Retrieve the details of a single Tier.

🔒 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:tiers scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the Tier to Retrieve.


PATCH api.rewards.wlloyalty.net/v1/tiers/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "name": "gold",
  "pointsRequirement": 1000
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
    "name": "Gold",
    "priority": 0,
    "pointsRequirement": 1000,
    "calculation": "LIFETIME_EARN",
    "accumulationPeriod": "P1Y",
    "effectivity": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "createdAt": "2019-04-09T10:02:37.515Z",
    "updatedAt": "2019-04-09T10:02:37.515Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "priority": {
          "type": "number"
        },
        "pointsRequirement": {
          "type": "number"
        },
        "calculation": {
          "type": "string",
          "enum": [
            "LIFETIME_EARN",
            "CALENDAR_PERIOD"
          ]
        },
        "accumulationPeriod": {
          "type": "string",
          "enum": [
            "P1Y",
            "P1M"
          ]
        },
        "effectivity": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "priority",
        "pointsRequirement",
        "calculation"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Update a Tier
PATCH/tiers/{id}

Update the details of a single Tier.

🔒 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:tiers scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the Tier to update.


DELETE api.rewards.wlloyalty.net/v1/tiers/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
    "name": "Gold",
    "priority": 0,
    "pointsRequirement": 1000,
    "calculation": "LIFETIME_EARN",
    "accumulationPeriod": "P1Y",
    "effectivity": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "createdAt": "2019-04-09T10:02:37.515Z",
    "updatedAt": "2019-04-09T10:02:37.515Z"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "priority": {
          "type": "number"
        },
        "pointsRequirement": {
          "type": "number"
        },
        "calculation": {
          "type": "string",
          "enum": [
            "LIFETIME_EARN",
            "CALENDAR_PERIOD"
          ]
        },
        "accumulationPeriod": {
          "type": "string",
          "enum": [
            "P1Y",
            "P1M"
          ]
        },
        "effectivity": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "priority",
        "pointsRequirement",
        "calculation"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Delete a Tier
DELETE/tiers/{id}

Delete a Tier. Note that the tier will be marked as no longer available, rather than being fully removed from the platform and will remain accessible via the WLL Console.

🔒 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with admin:tiers scope. Non-compliant requests will be rejected.

URI Parameters
HideShow
id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the Tier to delete.


Generated by aglio on 19 Jul 2021