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 Loyalty Console. This can be any RS256 or HS256 JWT signing configuration (more info), WLL can supply the requisite OAuth infrastructure or your pre-existing authentication system can be used seamlessly.

Your API key applies some rate-limiting by default, specifically 100 requests per second with burst provision for 400 requests. We find this tends to be adequate for normal usage but speak to your account manager if you would like to discuss an adjustment.

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.

Generating End-user Auth Tokens

The WLL API can be configured to recognize and validate the user auth tokens your customer-facing website or app already generates. This allows your customer-facing interfaces to query the WLL API directly as the specific logged-in user and only receive back data which the user is authorized to access.

WLL currently supports validating end-user auth tokens which conform to the following specification:

  • JWT structure per IETF RFC 7519

  • Algorithm value RS256 (RSASSA-PKCS1-v1_5 with SHA-256) or HS256 (HMAC SHA-256)

  • Mandatory payload claims: sub, iss, iat, exp.

  • If using RS256 algorithm the kid (Key ID) token header must be set to reference a public key accessible in your JSON Web Key Set (JWKS)

JWTs generated by any OIDC compliant authorization server is likely to meet this specification automatically. We have verified specifically that tokens generated by Auth0 and Firebase Auth work correctly.

If you wish to use this functionality please inform your success manager and provide the following details for configuration:

  • Algorithm: HS256 or RS256.

  • Issuer: the value of the iss claim to expect.

  • Shared Key: the symmetric key used to sign/validate the tokens if using HS256

  • JWKS URL: the URL where your JWKS can be accessed from if using RS256.

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

Transaction Completed

When a transaction is completed, 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": "TRANSACTION_COMPLETED",
  "subject": "$user_id",
  "payload": {
    "transactionId": "12345",
    "totalAmount": 100,
    "purchaseChannel": "Online"
    "itemsPurchased": [
        {
            "sku": "12345",
            "quantity": 2
        },
        {
            "sku": "67890",
            "quantity": 1
        }
    ]
  }
}
Completed Survey

When a survey is completed, 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": "COMPLETED_SURVEY",
  "subject": "$user_id",
  "payload": {
    "surveyId": "ABC123",
    "questionsAnswered": 4,
    "completionScore": 80
  }
}

Events

Test Reaction

POST api.rewards.wlloyalty.net/v1/events/test_reaction
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "type": "VISITED_VENUE",
  "payload": {},
  "subject": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "occurredAt": "2018-06-08T08:57:47.198Z"
}
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."
    },
    "occurredAt": {
      "type": "string"
    }
  },
  "required": [
    "type"
  ]
}
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": "12"
            }
          ]
        }
      }
    ],
    "activatedReactors": [
      {
        "name": "Example Reactor Name",
        "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": {
        "totalPoints": {
          "type": "number"
        },
        "reactions": {
          "type": "array"
        },
        "activatedReactors": {
          "type": "array"
        }
      },
      "required": [
        "totalPoints",
        "reactions",
        "activatedReactors"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Test Reaction
POST/events/test_reaction

Use this endpoint to test what reactions would be triggered if some data was reported as an event.

The request body is identical to the request for reporting an event, the primary difference is that this request must be made with normal admin authentication and the only way to test the reaction for a specific user is by including the subject key explicitly.

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

🔐 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.


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",
      "omitFromUserActivity": false
    },
    "subject": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "externalIdentifier": "any string",
      "isRestricted": false,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      }
    },
    "reportedAt": "2018-06-08T08:57:47.198Z",
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "reactedAt": "2018-06-08T08:57:47.198Z",
    "occurredAt": "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"
            },
            "omitFromUserActivity": {
              "type": "boolean"
            },
            "isActive": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "isPrivate"
          ]
        },
        "subject": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "accountNumber": {
              "type": "number"
            },
            "authIdentifier": {
              "type": "string"
            },
            "externalIdentifier": {
              "type": "string"
            },
            "isRestricted": {
              "type": "boolean"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "flags": {
              "type": "object",
              "properties": {
                "genderProvided": {
                  "type": "boolean"
                }
              }
            }
          },
          "required": [
            "id",
            "accountNumber",
            "authIdentifier",
            "isRestricted",
            "createdAt",
            "updatedAt"
          ]
        },
        "reportedAt": {
          "type": "string"
        },
        "registeredAt": {
          "type": "string"
        },
        "reactedAt": {
          "type": "string"
        },
        "occurredAt": {
          "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": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "occurredAt": "2018-06-08T08:57:47.198Z"
}
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."
    },
    "occurredAt": {
      "type": "string"
    }
  },
  "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",
      "omitFromUserActivity": false
    },
    "subject": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "externalIdentifier": "any string",
      "isRestricted": false,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      }
    },
    "reportedAt": "2018-06-08T08:57:47.198Z",
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "reactedAt": "2018-06-08T08:57:47.198Z",
    "occurredAt": "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"
            },
            "omitFromUserActivity": {
              "type": "boolean"
            },
            "isActive": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "isPrivate"
          ]
        },
        "subject": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "accountNumber": {
              "type": "number"
            },
            "authIdentifier": {
              "type": "string"
            },
            "externalIdentifier": {
              "type": "string"
            },
            "isRestricted": {
              "type": "boolean"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "flags": {
              "type": "object",
              "properties": {
                "genderProvided": {
                  "type": "boolean"
                }
              }
            }
          },
          "required": [
            "id",
            "accountNumber",
            "authIdentifier",
            "isRestricted",
            "createdAt",
            "updatedAt"
          ]
        },
        "reportedAt": {
          "type": "string"
        },
        "registeredAt": {
          "type": "string"
        },
        "reactedAt": {
          "type": "string"
        },
        "occurredAt": {
          "type": "string"
        },
        "payload": {
          "type": "object",
          "properties": {}
        }
      },
      "required": [
        "id",
        "type",
        "subject",
        "reportedAt",
        "payload"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Report an Event
POST/events

Use this endpoint to pass back information about the interactions between end-users and the business. To understand more about what events are, see the “Codifying Events” section of the documentation.

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.

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

You may optionally also include an additional timestamp property occurredAt in your request to represent when this event actually occurred in the real world. This is useful in cases where you are reporting events after some delay.

Authenticating the request

Private Event-types

To submit a private event the event-type’s own specific secret must be included as a bearer token in the Authorization header. This secret is generated when the event-type is created and can be retrieved via the WLL Admin Console. It is also possible to retrieve programmatically if required.

When reporting events in this manner you must pass the subject field which corresponds to the loyalty actor who is the subject of this event. The subject value may be any one of:

  • user.authIdentifier

  • user.id

  • user.accountNumber

  • team.id

  • team.accountNumber

externalIdentifier is not supported for this since it is not guaranteed to be unique.

Public Event-types

To submit a public event the authenticated user’s personal access token should be included in the Authorization header instead.

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.

Duplicate Detection

This endpoint will return a 409 “Event already exists” error if an identical event has already been reported in the past 60 seconds. An event is considered identical if it has the same type, subject, and payload.

🔐 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
RequestsDefault
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Content-Range: event 0-1/2
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",
        "omitFromUserActivity": false
      },
      "subject": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      },
      "reportedAt": "2018-06-08T08:57:47.198Z",
      "registeredAt": "2018-06-08T08:57:47.198Z",
      "reactedAt": "2018-06-08T08:57:47.198Z",
      "occurredAt": "2018-06-08T08:57:47.198Z",
      "payload": {}
    },
    {
      "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",
        "omitFromUserActivity": false
      },
      "subject": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      },
      "reportedAt": "2018-06-08T08:57:47.198Z",
      "registeredAt": "2018-06-08T08:57:47.198Z",
      "reactedAt": "2018-06-08T08:57:47.198Z",
      "occurredAt": "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

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, like], and "value" is the exact value to compare against. The like operator accepts a wild card % which means it will accept any value in place of it e.g %App% will find Web App, the like operator also isn’t case sensitive. 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')

When using the in operator the value should be an array. Arrays are expressed by enclosing a comma separated list of elements within !(). For example:

field3:(in:!('value1','value2'))
  • Parameters + limit: 10 (number, optional) The number of items to retrieve, defaults to 10 unless otherwise specified. Maximum: 1000. + skip: 0 (number, optional) The number of items to skip before selecting. + sort: id (enum[string], optional) The property to use for sorting. + Members + id + occurredAt + reportedAt + registeredAt + reactedAt + order: ASC (enum[string], optional) The order to sort items. + Members + ASC + DESC + filter: reportedAt:(gt:'2019-01-01T00:00:00Z') (optional) 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",
      "omitFromUserActivity": false
    },
    "subject": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "externalIdentifier": "any string",
      "isRestricted": false,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      }
    },
    "reportedAt": "2018-06-08T08:57:47.198Z",
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "reactedAt": "2018-06-08T08:57:47.198Z",
    "occurredAt": "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"
            },
            "omitFromUserActivity": {
              "type": "boolean"
            },
            "isActive": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "name",
            "description",
            "isPrivate"
          ]
        },
        "subject": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "accountNumber": {
              "type": "number"
            },
            "authIdentifier": {
              "type": "string"
            },
            "externalIdentifier": {
              "type": "string"
            },
            "isRestricted": {
              "type": "boolean"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "flags": {
              "type": "object",
              "properties": {
                "genderProvided": {
                  "type": "boolean"
                }
              }
            }
          },
          "required": [
            "id",
            "accountNumber",
            "authIdentifier",
            "isRestricted",
            "createdAt",
            "updatedAt"
          ]
        },
        "reportedAt": {
          "type": "string"
        },
        "registeredAt": {
          "type": "string"
        },
        "reactedAt": {
          "type": "string"
        },
        "occurredAt": {
          "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.

There are four timestamps recorded on each event, the purpose of each is described below:

  • occurredAt: when did this event actually take place in reality? This will only contain a value if it was provided when the event was reported.

  • reportedAt: when was this event initially reported to WLL.

  • registeredAt: when was this event stored in WLL’s database, in effect this means when were points (if any) granted for this event.

  • reactedAt: when were asynchronous reactions such as webhooks processed for this 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
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": "12"
            }
          ]
        },
        "reactorName": "Example Reactor Name"
      }
    ]
  }
}
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 occurred for a given event.

🔑 No authorization required

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

URI Parameters
HideShow
id
number (required) Example: 16389

ID of the Event.


Event Types

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",
      "omitFromUserActivity": false
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List All Event Types
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 Loyalty console.

Properties

  • omitFromUserActivity : false (boolean):

    When authorized as an admin this field is ignored, when authorized as a user however this field decides whether an event with this event-type is shown in the user activity.


Individual Event-Type

GET api.rewards.wlloyalty.net/v1/event_types/EXAMPLE_NAME
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": "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",
    "omitFromUserActivity": false
  }
}
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"
        },
        "omitFromUserActivity": {
          "type": "boolean"
        },
        "isActive": {
          "type": "boolean"
        }
      },
      "required": [
        "id",
        "name",
        "description",
        "isPrivate"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve an Event Type
GET/event_types/{identifier}

Retrieve the details of a single EventType.

You specify either the UUID of the event-type or the name of the event-type in the URL.

Properties

  • omitFromUserActivity : false (boolean):

    When authorized as an admin this field is ignored, when authorized as a user however this field decides whether an event with this event-type is shown in the user activity.

🔐 Admin authorization required

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

URI Parameters
HideShow
identifier
string (required) Example: EXAMPLE_NAME

name or ID of the event-type to retrieve.


Users

Users Collection

POST api.rewards.wlloyalty.net/v1/users?locale=en
RequestsDefaultConsentReferral
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"
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "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"
    }
  },
  "required": [
    "isRestricted",
    "profile"
  ]
}
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",
                "null"
              ],
              "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"
  ]
}
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"
    }
  ],
  "consentsDefinition": [
    {
      "type": {
        "id": "8d68cb91-202a-4c62-a867-8f9a8a1e2f50"
      },
      "checked": true
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "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"
    },
    "consentsDefinition": {
      "type": "array"
    }
  },
  "required": [
    "isRestricted",
    "profile"
  ]
}
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",
                "null"
              ],
              "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"
  ]
}
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"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "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"
    },
    "referralInviteCode": {
      "type": "string"
    },
    "referralActivity": {
      "type": "object",
      "properties": {
        "source": {
          "type": "string",
          "enum": [
            "EMAIL",
            "FACEBOOK",
            "TWITTER",
            "LINKEDIN",
            "OTHER"
          ]
        },
        "sourceUserId": {
          "type": "string"
        },
        "userAgent": {
          "type": "string",
          "enum": [
            "IOS",
            "ANDROID",
            "WEB",
            "UNKNOWN"
          ]
        },
        "ipAddress": {
          "type": "string"
        },
        "activityType": {
          "type": "string",
          "enum": [
            "REGISTER",
            "CLICK"
          ]
        }
      },
      "required": [
        "source",
        "sourceUserId",
        "activityType"
      ]
    }
  },
  "required": [
    "isRestricted",
    "profile"
  ]
}
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",
                "null"
              ],
              "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{?locale}

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 separate 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 default to UNKNOWN: 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 arbitrary map of keys and values: Optional; object; Any JSON key-values.

consentsDefinition array of consents given by user: Optional; array of consent objects

Consent objects take the following form:

{
  "type": { "id": "9cb2cc08-e033-4200-86a7-95a03ba09462" },
  "checked": true
}

The type.id refers to the specific pre-configured consent type which the user has given. checked is a boolean value to specify whether the user has given this type of consent.

Handling Referrals

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.

URI Parameters
HideShow
locale
string (optional) Example: en

The active locale of the user - used to capture the releavant consent description.


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, like], and "value" is the exact value to compare against. The like operator accepts a wild card % which means it will accept any value in place of it e.g %App% will find Web App, the like operator also isn’t case sensitive. 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')

When using the in operator the value should be an array. Arrays are expressed by enclosing a comma separated list of elements within !(). For example:

field3:(in:!('value1','value2'))
URI Parameters
HideShow
limit
number (optional) Example: 10

The number of items to retrieve, defaults to 10 unless otherwise specified. Maximum: 1000.

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

The ID parameter can be any one of: id, authIdentifier, or accountNumber.

🔐 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",
                "null"
              ],
              "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.

The ID parameter can be any one of: id, authIdentifier, or accountNumber.

🔐 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

The ID parameter can be any one of: id, authIdentifier, or accountNumber.

🔐 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",
                "null"
              ],
              "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",
                "null"
              ],
              "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",
        "type": "VOUCHER",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "redeemedAt": null,
        "expiresAt": "2019-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",
          "purchasable": false,
          "summary": "Example summary",
          "isLocked": true
        },
        "owner": {
          "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
          "accountNumber": 1000001,
          "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
          "externalIdentifier": "any string",
          "isRestricted": false,
          "createdAt": "2018-06-08T08:57:47.198Z",
          "updatedAt": "2018-06-08T08:57:47.198Z",
          "flags": {
            "genderProvided": false
          }
        }
      }
    ]
  }
}
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.

The ID parameter can be any one of: id, authIdentifier, or accountNumber.

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",
        "type": "VOUCHER",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "redeemedAt": null,
        "expiresAt": "2019-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",
          "purchasable": false,
          "summary": "Example summary",
          "isLocked": true
        },
        "owner": {
          "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
          "accountNumber": 1000001,
          "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
          "externalIdentifier": "any string",
          "isRestricted": false,
          "createdAt": "2018-06-08T08:57:47.198Z",
          "updatedAt": "2018-06-08T08:57:47.198Z",
          "flags": {
            "genderProvided": false
          }
        }
      }
    ]
  }
}
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
RequestsVoucher RewardGift Card - XoxoGift Card - WeGift
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "resource": {
    "type": "REWARD",
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
  }
}
Responses201400400400400
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "resource": {
      "type": "REWARD",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "benefit": {
      "type": "VOUCHER",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "completedAt": "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": {
        "resource": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "REWARD",
                "WEGIFT_PRODUCT"
              ]
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "id"
          ]
        },
        "benefit": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "id"
          ]
        },
        "completedAt": {
          "type": "string"
        }
      },
      "required": [
        "resource",
        "completedAt"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Voucher code pool has run out of codes.",
  "data": {
    "name": "VoucherCodePoolExhaustedError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not purchasable",
  "data": {
    "name": "RewardNotPurchasableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not available",
  "data": {
    "name": "RewardUnavailableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "User has insufficient points to perform this operation",
  "data": {
    "name": "InsufficientPointsError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "resource": {
    "type": "REWARD",
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
  }
}
Responses201400400400
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "resource": {
      "type": "REWARD",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "benefit": {
      "type": "XOXO_PRODUCT",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "orderId": "ABC123",
    "delayed": false
  }
}
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": [
                "REWARD",
                "WEGIFT_PRODUCT"
              ]
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "id"
          ]
        },
        "benefit": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "id"
          ]
        },
        "registeredAt": {
          "type": "string"
        },
        "orderId": {
          "type": "string"
        },
        "delayed": {
          "type": "boolean"
        }
      },
      "required": [
        "resource",
        "registeredAt",
        "orderId",
        "delayed"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not purchasable",
  "data": {
    "name": "RewardNotPurchasableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not available",
  "data": {
    "name": "RewardUnavailableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "User has insufficient points to perform this operation",
  "data": {
    "name": "InsufficientPointsError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "resource": {
    "type": "REWARD",
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
  }
}
Responses201400400400
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "resource": {
      "type": "REWARD",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "benefit": {
      "type": "WEGIFT_PRODUCT",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "orderId": "ABC123"
  }
}
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": [
                "REWARD",
                "WEGIFT_PRODUCT"
              ]
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "id"
          ]
        },
        "benefit": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "id"
          ]
        },
        "registeredAt": {
          "type": "string"
        },
        "orderId": {
          "type": "string"
        }
      },
      "required": [
        "resource",
        "registeredAt",
        "orderId"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not purchasable",
  "data": {
    "name": "RewardNotPurchasableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not available",
  "data": {
    "name": "RewardUnavailableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "User has insufficient points to perform this operation",
  "data": {
    "name": "InsufficientPointsError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}

Active User Purchase
POST/users/me/purchases

❌ This API is Deprecated

This API is deprecated and will be removed in the future. Use /commands/purchase_reward/ instead.

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

In the request body you should specify the ID of the reward which the user wishes to purchase. The response will vary according to the type of resource granted by the purchase.

👤 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 Purchases

POST api.rewards.wlloyalty.net/v1/users/9cb2cc08-e033-4200-86a7-95a03ba09462/purchases
RequestsVoucher RewardGift Card - XoxoGift Card - WeGift
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "resource": {
    "type": "REWARD",
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
  }
}
Responses201400400400400
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "resource": {
      "type": "REWARD",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "benefit": {
      "type": "VOUCHER",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "completedAt": "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": {
        "resource": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "REWARD",
                "WEGIFT_PRODUCT"
              ]
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "id"
          ]
        },
        "benefit": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "id"
          ]
        },
        "completedAt": {
          "type": "string"
        }
      },
      "required": [
        "resource",
        "completedAt"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Voucher code pool has run out of codes.",
  "data": {
    "name": "VoucherCodePoolExhaustedError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not purchasable",
  "data": {
    "name": "RewardNotPurchasableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not available",
  "data": {
    "name": "RewardUnavailableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "User has insufficient points to perform this operation",
  "data": {
    "name": "InsufficientPointsError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "resource": {
    "type": "REWARD",
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
  }
}
Responses201400400400
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "resource": {
      "type": "REWARD",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "benefit": {
      "type": "XOXO_PRODUCT",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "orderId": "ABC123",
    "delayed": false
  }
}
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": [
                "REWARD",
                "WEGIFT_PRODUCT"
              ]
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "id"
          ]
        },
        "benefit": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "id"
          ]
        },
        "registeredAt": {
          "type": "string"
        },
        "orderId": {
          "type": "string"
        },
        "delayed": {
          "type": "boolean"
        }
      },
      "required": [
        "resource",
        "registeredAt",
        "orderId",
        "delayed"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not purchasable",
  "data": {
    "name": "RewardNotPurchasableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not available",
  "data": {
    "name": "RewardUnavailableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "User has insufficient points to perform this operation",
  "data": {
    "name": "InsufficientPointsError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "resource": {
    "type": "REWARD",
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
  }
}
Responses201400400400
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "resource": {
      "type": "REWARD",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "benefit": {
      "type": "WEGIFT_PRODUCT",
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462"
    },
    "registeredAt": "2018-06-08T08:57:47.198Z",
    "orderId": "ABC123"
  }
}
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": [
                "REWARD",
                "WEGIFT_PRODUCT"
              ]
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "type",
            "id"
          ]
        },
        "benefit": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string"
            },
            "id": {
              "type": "string"
            }
          },
          "required": [
            "id"
          ]
        },
        "registeredAt": {
          "type": "string"
        },
        "orderId": {
          "type": "string"
        }
      },
      "required": [
        "resource",
        "registeredAt",
        "orderId"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not purchasable",
  "data": {
    "name": "RewardNotPurchasableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "Reward is not available",
  "data": {
    "name": "RewardUnavailableError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "fail",
  "message": "User has insufficient points to perform this operation",
  "data": {
    "name": "InsufficientPointsError"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "message"
  ]
}

Specific User Purchase
POST/users/{id}/purchases

❌ This API is Deprecated

This API is deprecated and will be removed in the future. Use /commands/purchase_reward/ instead.

Use this endpoint to trigger a purchase of the provided resource for the specific user with the provided ID.

In the request body you should specify the ID of the reward which the user wishes to purchase. The response will vary according to the type of resource granted by the purchase.

🔒 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 for whom the wallet should be retrieved.


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

The position property is optional, if it is provided it will be used to calculate any defined Venues within a 1km radius of the position and include that information in the resulting redemption event payload.

👤 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.


Bulk User Summary

GET api.rewards.wlloyalty.net/v1/users/summary
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses201
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": [
    {
      "id": "2096817f-2d8f-4690-bbcc-71868ad1f3c9",
      "wallet": {
        "userLifetimePoints": 3100,
        "currentYearPoints": 1900,
        "lastYearPoints": 1200,
        "currentMonthPoints": 900,
        "lastMonthPoints": 1900,
        "last24HoursPoints": 0,
        "points": 1900,
        "correctAsOf": "2024-11-16T05:57:33.500Z"
      },
      "pointsExpiryPrediction": {
        "overallSummary": {
          "type": "EXPIRY",
          "summary": [
            {
              "pointsDueToExpire": 0,
              "timePeriod": 1
            }
          ]
        }
      },
      "pointsSpendPrediction": {
        "overallSummary": {
          "type": "MAX_POINTS",
          "summary": {
            "pointsCap": 1000,
            "remainingPoints": 900,
            "percentageUsed": 10
          }
        }
      },
      "pointsEarnPrediction": {
        "overallSummary": {
          "type": "EXPIRY",
          "summary": [
            {
              "pointsDueToExpire": 0,
              "timePeriod": 7
            }
          ]
        }
      },
      "audiences": [
        {
          "id": "ec9706be-6000-4968-9ce5-bedc73f05a12",
          "name": "Users with over 200 points."
        }
      ],
      "tier": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "name": ""
      }
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Bulk User Summary
GET/users/summary

Use this endpoint to fetch a list of users summaries.

🔐 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, like], and "value" is the exact value to compare against. The like operator accepts a wild card % which means it will accept any value in place of it e.g %App% will find Web App, the like operator also isn’t case sensitive. 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')

When using the in operator the value should be an array. Arrays are expressed by enclosing a comma separated list of elements within !(). For example:

field3:(in:!('value1','value2'))

Audiences

Audience Results

GET api.rewards.wlloyalty.net/v1/audiences/9cb2cc08-e033-4200-86a7-95a03ba09462/results
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 Audience Results
GET/audiences/{id}/results

Retrieve a list of users who met the criteria of this audience when last calculated.

🔐 Multiple authorization modes

Requests to this method require either:

👤 User Authorization

🔒 Admin Authorization with read:audiences and read:users scopes

Non-compliant requests will be rejected.

If a user token is provided rather than an admin token (or if the impersonate header is sent with an admin token), this endpoint will only return results which this user should have visibility of – namely their own result. This behaviour can be used from the client-side to check if the current user is a member of a specific audience.

Note: this request does not invoke a synchronous calculation of audience membership, it returns the results of async audience calculations. The timing of the last calculation depends on the configured frequency of this audience. This endpoint should be used where eventual consistency is appropriate.

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

ID of the audience.


Rewards

Understanding Rewards and Benefits

In the terminology of the WLL platform a “Reward” is a description of some real-world value which a end-user could get. It has two main functions:

  1. providing a container for marketing assets such as images, descriptions, terms and conditions.
  2. specifying the requirements for an end-user to get it, e.g. points cost, tier status, audience membership.

There are multiple types of reward which reflect the various methods for delivering value to end-users. All rewards (except static offers) support the purchase method which ensures the user meets the requirements for the reward and deducts any points necessary from the user’s balance.

Some types of reward generate a “Benefit” as a result of purchasing the reward. Benefits are uniquely linked to the purchasing user, they provide a means for the user to actually get some real-world value. An analogy which may be helpful for readers familiar with software: a Reward is similar to a “class”, and a Benefit is an instance of that class.

There is a different type of benefit corresponding to each different type of reward which generates benefits. Broadly the types of benefit can be categorized into Vouchers and Gift Cards.

Reward and benefit flow

Voucher benefits are fulfilled by a system external to WLL, typically a ePOS, eCommerce, or shop staff member. They function by assigning a voucher code with an expiry date to that user during the purchase which can only be accessed by calling the “redemption” method.

With Gift Card benefits, WLL handles fulfilment on your behalf, there are three options for fulfilment: direct email, URL, or raw text code. Some brands only support one or the other of those options, but there’s plenty of choice so you can choose the delivery method that works best for you and then just select the brands which support that method.

Rewards Collection

GET api.rewards.wlloyalty.net/v1/rewards?limit=10&skip=0&sort=priority&order=ASC&filter=price:(gt:10)
RequestsAnonymousUser AuthAdmin AuthUser Impersonation
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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true,
      "type": "VOUCHER",
      "price": 0,
      "priority": 0,
      "tier": {
        "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
        "name": "Gold",
        "description": "This is an example",
        "artworkUrl": "https://google.com/logo.gif",
        "priority": 0
      },
      "value": 0,
      "category": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "name": "Category Name",
        "description": "This is an example description",
        "priority": 1,
        "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "pictureUrl": ""
      },
      "discounts": [
        {
          "type": "FIXED",
          "value": 1000,
          "sku": "321ZA",
          "productSku": "AZ123"
        }
      ],
      "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"
  ]
}
Headers
Authorization: Bearer $user_token
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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true,
      "type": "VOUCHER",
      "price": 0,
      "priority": 0,
      "tier": {
        "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
        "name": "Gold",
        "description": "This is an example",
        "artworkUrl": "https://google.com/logo.gif",
        "priority": 0
      },
      "value": 0,
      "category": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "name": "Category Name",
        "description": "This is an example description",
        "priority": 1,
        "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "pictureUrl": ""
      },
      "discounts": [
        {
          "type": "FIXED",
          "value": 1000,
          "sku": "321ZA",
          "productSku": "AZ123"
        }
      ],
      "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"
  ]
}
Headers
Authorization: Bearer $admin_token
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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true,
      "type": "VOUCHER",
      "price": 0,
      "priority": 0,
      "tier": {
        "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
        "name": "Gold",
        "description": "This is an example",
        "artworkUrl": "https://google.com/logo.gif",
        "priority": 0
      },
      "value": 0,
      "category": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "name": "Category Name",
        "description": "This is an example description",
        "priority": 1,
        "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "pictureUrl": ""
      },
      "discounts": [
        {
          "type": "FIXED",
          "value": 1000,
          "sku": "321ZA",
          "productSku": "AZ123"
        }
      ],
      "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"
  ]
}
Headers
Authorization: Bearer $admin_token
X-Impersonate: $wll_user_id
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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true,
      "type": "VOUCHER",
      "price": 0,
      "priority": 0,
      "tier": {
        "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
        "name": "Gold",
        "description": "This is an example",
        "artworkUrl": "https://google.com/logo.gif",
        "priority": 0
      },
      "value": 0,
      "category": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "name": "Category Name",
        "description": "This is an example description",
        "priority": 1,
        "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "pictureUrl": ""
      },
      "discounts": [
        {
          "type": "FIXED",
          "value": 1000,
          "sku": "321ZA",
          "productSku": "AZ123"
        }
      ],
      "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 the request.

Importantly that means it will not exclude the rewards which have been marked as “unpurchasable”. To exclude such rewards you can supply the following query ?filter=purchasable:(eq:!t).

The exact list of rewards returned also depends on who is making the request, since rewards can be configured to only be visible to certain users. Rewards may also have a isLocked boolean property which indicates whether the reward is locked for purchasing for the active user.

Visibility skip mode

As mentioned above, if the request is from an end-user’s perspective, some of the rewards may be configured to be invisible for that user. By default, invisible rewards will still count towards the requested limit even though they won’t be included in the response body. This behaviour may not be desirable if you are expecting a consistent number of items in the response body.

To support that use case there is an optional query parameter you can pass in the request to change the behaviour: completelySkipInvisible. If you pass this parameter only visible rewards (i.e. ones returned in the response body) will count towards the limit. This behaviour is an opt in because it is less performant than the default and so may result in increased latency.

Content-Range and pagination

As with all WLL API list endpoints the response Content-Range header indicates what range of the whole set of items were returned in the response body.

Given ?skip=0&limit=10 request parameters the response range will look like:

reward 0-9/100

Where

  • 0 is the index of the first item considered for inclusion in the response body,

  • 9 is the index of the last item considered for inclusion in the response body,

  • 100 is the total number of items in the entire set.

These indices do not always indicate the total number of items returned in the body, merely what range of items was considered for inclusion.

Whereas, given ?skip=0&limit=10&completelySkipInvisible the response range may look like:

reward 0-13/*

The obvious difference is that in this case the total number of items in the entire set is not given to indicate that you cannot know definitively how many further pages of items are available since it’s not known how many items will be visible to the user.

The other difference demonstrated here is the range is not determined by the limit value because we have asked to automatically skip any invisible items so as to fill the requested limit. In this example, 4 of the first 10 rewards considered for inclusion were invisible to the user, so to fill the requested limit the API had to move on to items 10, 11, 12, and 13.

Summary: Content-Range specifies what range of the overall set was considered for inclusion in the response – it does not specify the number of items returned.

In either case, to request the next page of rewards you should specify skip based on the last index given in the previous response’s Content-Range, plus one.

For example, to request the second page of the first example above you would request ?skip=10&limit=10. To request the second page of the second example above you would request ?skip=14&limit=10.

Requesting rewards as an end-user

There are two ways to retrieve the list of rewards which are available to a specific user:

Passing the User’s auth token

You can simply pass the user’s auth token in the Authorization header of the request. This approach is ideal when the request is coming directly from a user’s device and they have an active auth session. See this section of documentation for more information about user auth tokens.

User impersonation with an admin token

You can alternatively pass the X-Impersonate header in the request with the relevant user’s WLL ID. You can only use this impersonation header when authorizing the request with an admin token which has read:users permission.

Non-venue rewards

To return 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).

🔐 Multiple authorization modes

Requests to this method can use any of the following:

🔑 Anonymous (API key only)

👤 User Authorization

🔒 Admin Authorization

If using admin authorization the token must have at least read:rewards permission; read:users permission is also required if applying user impersonation. The behaviour of this method will vary based on the authorization method, please see main description above for more information.

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, like], and "value" is the exact value to compare against. The like operator accepts a wild card % which means it will accept any value in place of it e.g %App% will find Web App, the like operator also isn’t case sensitive. 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')

When using the in operator the value should be an array. Arrays are expressed by enclosing a comma separated list of elements within !(). For example:

field3:(in:!('value1','value2'))
URI Parameters
HideShow
completelySkipInvisible
string (optional) 

Opt in to special mode described here.

Parameter values below are allowed but not required, merely including the param name will enable the mode.

Choices: 1 0

limit
number (optional) Example: 10

The number of items to retrieve, defaults to 10 unless otherwise specified. Maximum: 1000.

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",
    "purchasable": false,
    "summary": "Example summary",
    "isLocked": true,
    "type": "VOUCHER",
    "price": 0,
    "priority": 0,
    "tier": {
      "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
      "name": "Gold",
      "description": "This is an example",
      "artworkUrl": "https://google.com/logo.gif",
      "priority": 0
    },
    "value": 0,
    "category": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "name": "Category Name",
      "description": "This is an example description",
      "priority": 1,
      "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "pictureUrl": ""
    },
    "discounts": [
      {
        "type": "FIXED",
        "value": 1000,
        "sku": "321ZA",
        "productSku": "AZ123"
      }
    ],
    "availability": {
      "start": "2018-06-08T18:19:10.878Z",
      "end": "2018-06-09T18:19:10.878Z"
    },
    "description": "Redeem this reward for a free cup of coffee",
    "terms": "",
    "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"
        },
        "purchasable": {
          "type": "boolean"
        },
        "summary": {
          "type": "string"
        },
        "isLocked": {
          "type": "boolean"
        },
        "type": {
          "type": "string",
          "enum": [
            "VOUCHER",
            "GENERIC_OFFER",
            "AWIN_PROGRAMME",
            "FIDEL_OFFER",
            "OLIVE_OFFER",
            "WEGIFT_PRODUCT",
            "XOXO_PRODUCT"
          ]
        },
        "price": {
          "type": "number"
        },
        "priority": {
          "type": "number"
        },
        "tier": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "artworkUrl": {
              "type": "string"
            },
            "priority": {
              "type": "number"
            }
          },
          "required": [
            "id",
            "name",
            "priority"
          ]
        },
        "value": {
          "type": "number"
        },
        "category": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "description": {
              "type": "string"
            },
            "priority": {
              "type": "number"
            },
            "parent": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            }
          }
        },
        "discounts": {
          "type": "array"
        },
        "availability": {
          "type": "object",
          "properties": {
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            }
          }
        },
        "description": {
          "type": "string"
        },
        "terms": {
          "type": "string"
        },
        "venues": {
          "type": "array"
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "name",
        "pictureUrl",
        "purchasable",
        "type",
        "price",
        "priority",
        "value",
        "discounts",
        "availability",
        "description",
        "terms"
      ]
    }
  },
  "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.


Rewards Categories

GET api.rewards.wlloyalty.net/v1/reward_categories?limit=10&skip=0&sort=priority&order=ASC&filter=priority:(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": "Category Name",
      "description": "This is an example description",
      "priority": 1,
      "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "pictureUrl": ""
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List all Reward Categories
GET/reward_categories{?limit,skip,sort,order,filter}

Get a list of all defined reward categories.

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, like], and "value" is the exact value to compare against. The like operator accepts a wild card % which means it will accept any value in place of it e.g %App% will find Web App, the like operator also isn’t case sensitive. 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')

When using the in operator the value should be an array. Arrays are expressed by enclosing a comma separated list of elements within !(). For example:

field3:(in:!('value1','value2'))
URI Parameters
HideShow
limit
number (optional) Example: 10

The number of items to retrieve, defaults to 10 unless otherwise specified. Maximum: 1000.

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: id createdAt updatedAt name priority

order
string (optional) Example: ASC

The order to sort items.

Choices: ASC DESC

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

O-Rison encoded filter string


POST api.rewards.wlloyalty.net/v1/reward_categories
RequestsDefault
Headers
X-Api-Key: $api_key
Body
{
  "name": "Winter Offers",
  "description": "Check out our exciting winter offers!",
  "priority": 1,
  "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "defaultLocale": "en",
  "details": [
    {
      "locale": "en",
      "name": "High Earners",
      "description": "This is a description",
      "pictureUrl": "https://google.com/logo.gif"
    }
  ]
}
Schema
HideShow
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "priority": {
      "type": "number"
    },
    "parent": {
      "type": "string"
    },
    "defaultLocale": {
      "enum": [
        "en",
        "fr",
        "de",
        "it",
        "es",
        "nl",
        "ar",
        "tr"
      ]
    },
    "details": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "locale": {
            "enum": [
              "en",
              "fr",
              "de",
              "it",
              "es",
              "nl",
              "ar",
              "tr"
            ]
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "pictureUrl": {
            "type": "string"
          }
        },
        "required": [
          "locale",
          "name"
        ]
      }
    }
  },
  "required": [
    "defaultLocale",
    "details"
  ],
  "$schema": "http://json-schema.org/draft-04/schema#"
}
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": "Category Name",
    "description": "This is an example description",
    "priority": 1,
    "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "pictureUrl": ""
  }
}
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"
        },
        "description": {
          "type": "string"
        },
        "priority": {
          "type": "number"
        },
        "parent": {
          "type": "string"
        },
        "pictureUrl": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Creating Reward Categories
POST/reward_categories

API to create a Reward Category


Specific Reward Category

PATCH api.rewards.wlloyalty.net/v1/reward_categories/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "name": "Winter Offers",
  "description": "Check out our exciting winter offers!",
  "priority": 1,
  "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "defaultLocale": "en",
  "details": [
    {
      "locale": "en",
      "name": "High Earners",
      "description": "This is a description",
      "pictureUrl": "https://google.com/logo.gif"
    }
  ]
}
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": "Category Name",
    "description": "This is an example description",
    "priority": 1,
    "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "pictureUrl": ""
  }
}
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"
        },
        "description": {
          "type": "string"
        },
        "priority": {
          "type": "number"
        },
        "parent": {
          "type": "string"
        },
        "pictureUrl": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Update a Reward Category
PATCH/reward_categories/{id}

Update the details of the reward category specified by their ID.

🔐 Admin authorization required

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

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

ID of the Reward Category to update.


DELETE api.rewards.wlloyalty.net/v1/reward_categories/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsDefault
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
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": "Category Name",
    "description": "This is an example description",
    "priority": 1,
    "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "pictureUrl": ""
  }
}
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"
        },
        "description": {
          "type": "string"
        },
        "priority": {
          "type": "number"
        },
        "parent": {
          "type": "string"
        },
        "pictureUrl": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Delete a Reward Category
DELETE/reward_categories/{id}

The reward category will be deleted. Once deleted the reward category is not accessible. (It is not archived)

Note. Before the category can be deleted all associated rewards must be unlinked first.

🔒 Admin authorization required

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

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

ID of the Reward Category to delete.


Benefits

Benefits Collection

GET api.rewards.wlloyalty.net/v1/benefits?limit=10&skip=0&sort=createdAt&order=ASC&filter=createdAt:(gt:'2019-01-01T00:00:00Z')
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": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "type": "VOUCHER",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": null,
      "expiresAt": "2019-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",
        "purchasable": false,
        "summary": "Example summary",
        "isLocked": true
      },
      "owner": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      }
    },
    {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "type": "VOUCHER",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": "2018-06-10T21:07:01.219Z",
      "expiresAt": "2019-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",
        "purchasable": false,
        "summary": "Example summary",
        "isLocked": true
      },
      "owner": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      }
    },
    {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "type": "XOXO_PRODUCT",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": null,
      "expiresAt": "2019-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",
        "purchasable": false,
        "summary": "Example summary",
        "isLocked": true
      },
      "owner": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      },
      "orderId": "123456",
      "pin": "123ABC",
      "url": "https://docs.whitelabel-loyalty.com/assets/gift-card-redemption.html",
      "activationKey": "JS9Y-4TVB",
      "isDelayed": false
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array"
    }
  },
  "required": [
    "status",
    "data"
  ]
}

List all Benefits
GET/benefits{?limit,skip,sort,order,filter}

Get a list of all benefits within your tenant. Benefits are the output of a reward purchase. There are different types of benefits each corresponding to a different type of reward as explained here.

🔐 Multiple authorization modes

Requests to this method require either:

👤 User Authorization

🔒 Admin Authorization

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, like], and "value" is the exact value to compare against. The like operator accepts a wild card % which means it will accept any value in place of it e.g %App% will find Web App, the like operator also isn’t case sensitive. 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')

When using the in operator the value should be an array. Arrays are expressed by enclosing a comma separated list of elements within !(). For example:

field3:(in:!('value1','value2'))
URI Parameters
HideShow
limit
number (optional) Example: 10

The number of items to retrieve, defaults to 10 unless otherwise specified. Maximum: 1000.

skip
number (optional) Example: 0

The number of items to skip before selecting.

sort
string (optional) Example: createdAt

The property to use for sorting.

Choices: createdAt redeemedAt expiresAt reward.* owner.*

order
string (optional) Example: ASC

The order to sort items.

Choices: ASC DESC

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

O-Rison encoded filter string


Individual Benefit

GET api.rewards.wlloyalty.net/v1/benefits/9cb2cc08-e033-4200-86a7-95a03ba09462
RequestsUnredeemed VoucherRedeemed VoucherGift Card - XoxoGift Card - WeGift
Headers
X-Api-Key: $api_key
Authorization: Bearer $access_token
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "type": "VOUCHER",
    "createdAt": "2018-06-08T08:57:47.198Z",
    "redeemedAt": null,
    "expiresAt": "2019-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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true
    },
    "owner": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "externalIdentifier": "any string",
      "isRestricted": false,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      }
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "redeemedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reward": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "purchasable": {
              "type": "boolean"
            },
            "summary": {
              "type": "string"
            },
            "isLocked": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "purchasable"
          ]
        },
        "owner": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "accountNumber": {
              "type": "number"
            },
            "authIdentifier": {
              "type": "string"
            },
            "externalIdentifier": {
              "type": "string"
            },
            "isRestricted": {
              "type": "boolean"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "flags": {
              "type": "object",
              "properties": {
                "genderProvided": {
                  "type": "boolean"
                }
              }
            }
          },
          "required": [
            "id",
            "accountNumber",
            "authIdentifier",
            "isRestricted",
            "createdAt",
            "updatedAt"
          ]
        }
      },
      "required": [
        "id",
        "type",
        "reward"
      ]
    }
  },
  "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": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "type": "VOUCHER",
    "createdAt": "2018-06-08T08:57:47.198Z",
    "redeemedAt": "2018-06-10T21:07:01.219Z",
    "expiresAt": "2019-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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true
    },
    "owner": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "externalIdentifier": "any string",
      "isRestricted": false,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      }
    },
    "code": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": "2018-06-08T08:57:47.198Z",
      "validatedAt": "2018-06-08T08:57:47.198Z",
      "value": "123ABC"
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "redeemedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reward": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "purchasable": {
              "type": "boolean"
            },
            "summary": {
              "type": "string"
            },
            "isLocked": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "purchasable"
          ]
        },
        "owner": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "accountNumber": {
              "type": "number"
            },
            "authIdentifier": {
              "type": "string"
            },
            "externalIdentifier": {
              "type": "string"
            },
            "isRestricted": {
              "type": "boolean"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "flags": {
              "type": "object",
              "properties": {
                "genderProvided": {
                  "type": "boolean"
                }
              }
            }
          },
          "required": [
            "id",
            "accountNumber",
            "authIdentifier",
            "isRestricted",
            "createdAt",
            "updatedAt"
          ]
        },
        "code": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "validatedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "value": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "value"
          ]
        }
      },
      "required": [
        "id",
        "type",
        "reward"
      ]
    }
  },
  "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": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "type": "XOXO_PRODUCT",
    "createdAt": "2018-06-08T08:57:47.198Z",
    "redeemedAt": null,
    "expiresAt": "2019-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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true
    },
    "owner": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "externalIdentifier": "any string",
      "isRestricted": false,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      }
    },
    "orderId": "123456",
    "pin": "123ABC",
    "url": "https://docs.whitelabel-loyalty.com/assets/gift-card-redemption.html",
    "activationKey": "JS9Y-4TVB",
    "isDelayed": false
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "redeemedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reward": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "purchasable": {
              "type": "boolean"
            },
            "summary": {
              "type": "string"
            },
            "isLocked": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "purchasable"
          ]
        },
        "owner": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "accountNumber": {
              "type": "number"
            },
            "authIdentifier": {
              "type": "string"
            },
            "externalIdentifier": {
              "type": "string"
            },
            "isRestricted": {
              "type": "boolean"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "flags": {
              "type": "object",
              "properties": {
                "genderProvided": {
                  "type": "boolean"
                }
              }
            }
          },
          "required": [
            "id",
            "accountNumber",
            "authIdentifier",
            "isRestricted",
            "createdAt",
            "updatedAt"
          ]
        },
        "orderId": {
          "type": "string"
        },
        "pin": {
          "type": [
            "string",
            "null"
          ]
        },
        "url": {
          "type": [
            "string",
            "null"
          ]
        },
        "activationKey": {
          "type": [
            "string",
            "null"
          ]
        },
        "isDelayed": {
          "type": "boolean"
        }
      },
      "required": [
        "id",
        "type",
        "reward",
        "orderId"
      ]
    }
  },
  "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": "9cb2cc08-e033-4200-86a7-95a03ba09462",
    "type": "WEGIFT_PRODUCT",
    "createdAt": "2018-06-08T08:57:47.198Z",
    "redeemedAt": null,
    "expiresAt": "2019-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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true
    },
    "owner": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "accountNumber": 1000001,
      "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "externalIdentifier": "any string",
      "isRestricted": false,
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "flags": {
        "genderProvided": false
      }
    },
    "orderId": "O-8KAM7MXK",
    "url": "https://docs.whitelabel-loyalty.com/assets/gift-card-redemption.html"
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "redeemedAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "expiresAt": {
          "type": [
            "string",
            "null"
          ]
        },
        "reward": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "pictureUrl": {
              "type": "string"
            },
            "purchasable": {
              "type": "boolean"
            },
            "summary": {
              "type": "string"
            },
            "isLocked": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "purchasable"
          ]
        },
        "owner": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "accountNumber": {
              "type": "number"
            },
            "authIdentifier": {
              "type": "string"
            },
            "externalIdentifier": {
              "type": "string"
            },
            "isRestricted": {
              "type": "boolean"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "flags": {
              "type": "object",
              "properties": {
                "genderProvided": {
                  "type": "boolean"
                }
              }
            }
          },
          "required": [
            "id",
            "accountNumber",
            "authIdentifier",
            "isRestricted",
            "createdAt",
            "updatedAt"
          ]
        },
        "orderId": {
          "type": "string"
        },
        "url": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "type",
        "reward",
        "orderId"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve a Benefit
GET/benefits/{id}

Retrieve the details of a specific Benefit by its ID.

The core data structure for all Benefits is the same, but each type of benefit extends the core data structure with its own specific properties. Additionally for some types of Benefit, confidential information will not be returned in the response until it has been redeemed. For example, a Voucher benefit will not give it’s code until it has been redeemed.

Types of Benefit

Voucher

Vouchers provide a mechanism for you to issue codes to users which can be used outside of the WLL platform to gain real-world value of some kind. In addition to the core data structure, Vouchers add a code property. This will be null initially until you redeem it, after which any further requests to retrieve the benefit will include the full code object (check out the “Redeemed Voucher” request on the right to see this data structure).

Gift Card (Xoxo Product)

Gift Cards provide a mechanism for users to get real world value out of the loyalty programme without any fulfilment considerations for yourself as a business. As soon as a user purchases a gift card reward the Benefit contains the details of how to make use of it. Since gift cards are a closed-loop system you are not able to know when a user has fully made use of the whole value initially added to the gift card. For this reason WLL recommends you present UI for the user to call the redeem method for any gift card benefit at a time of their choosing, this will set the redeemedAt timestamp on the benefit and allow you to consider the benefit “closed” and no longer present it to the user.

In addition to the core data structure, Xoxo Products add the following properties:

  • url: most gift cards will return a redemption URL which provides a ready-made UI explaining to the user how to make use of their gift card.

  • pin: some gift cards will return the unique PIN of the card directly, this will need to be presented to the user within your own UI.

  • activationCode: some gift cards require this separate secret code to activate and make use of it.

For an overview of the various reward and benefit flows please see this section of documentation.

🔐 Multiple authorization modes

Requests to this method require either:

👤 User Authorization

🔒 Admin Authorization

Non-compliant requests will be rejected.

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

ID of the Benefit to retrieve.


Commands

Reward Purchases

POST api.rewards.wlloyalty.net/v1/commands/purchase_reward
RequestsAdmin for UserUser for SelfUser for TeamAdmin for Team
Headers
Content-Type: application/json
X-Api-Key: $api_key
X-Impersonate: $user_id
Authorization: Bearer $access_token
Body
{
  "rewardId": "9cb2cc08-e033-4200-86a7-95a03ba09462"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "rewardId": {
      "type": "string"
    }
  },
  "required": [
    "rewardId"
  ]
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "benefit": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "type": "VOUCHER",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": null,
      "expiresAt": "2019-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",
        "purchasable": false,
        "summary": "Example summary",
        "isLocked": true
      },
      "owner": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      }
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "benefit": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "expiresAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "reward": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                },
                "purchasable": {
                  "type": "boolean"
                },
                "summary": {
                  "type": "string"
                },
                "isLocked": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "createdAt",
                "updatedAt",
                "name",
                "pictureUrl",
                "purchasable"
              ]
            },
            "owner": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "accountNumber": {
                  "type": "number"
                },
                "authIdentifier": {
                  "type": "string"
                },
                "externalIdentifier": {
                  "type": "string"
                },
                "isRestricted": {
                  "type": "boolean"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "flags": {
                  "type": "object",
                  "properties": {
                    "genderProvided": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "required": [
                "id",
                "accountNumber",
                "authIdentifier",
                "isRestricted",
                "createdAt",
                "updatedAt"
              ]
            }
          },
          "required": [
            "id",
            "type",
            "reward"
          ]
        }
      }
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "rewardId": "9cb2cc08-e033-4200-86a7-95a03ba09462"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "rewardId": {
      "type": "string"
    }
  },
  "required": [
    "rewardId"
  ]
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "benefit": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "type": "VOUCHER",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": null,
      "expiresAt": "2019-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",
        "purchasable": false,
        "summary": "Example summary",
        "isLocked": true
      },
      "owner": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      }
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "benefit": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "expiresAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "reward": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                },
                "purchasable": {
                  "type": "boolean"
                },
                "summary": {
                  "type": "string"
                },
                "isLocked": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "createdAt",
                "updatedAt",
                "name",
                "pictureUrl",
                "purchasable"
              ]
            },
            "owner": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "accountNumber": {
                  "type": "number"
                },
                "authIdentifier": {
                  "type": "string"
                },
                "externalIdentifier": {
                  "type": "string"
                },
                "isRestricted": {
                  "type": "boolean"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "flags": {
                  "type": "object",
                  "properties": {
                    "genderProvided": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "required": [
                "id",
                "accountNumber",
                "authIdentifier",
                "isRestricted",
                "createdAt",
                "updatedAt"
              ]
            }
          },
          "required": [
            "id",
            "type",
            "reward"
          ]
        }
      }
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "rewardId": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "beneficiaryId": "8cb2cc08-e033-4200-86a7-95a03ba09462"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "rewardId": {
      "type": "string"
    },
    "beneficiaryId": {
      "type": "string"
    }
  },
  "required": [
    "rewardId",
    "beneficiaryId"
  ]
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "benefit": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "type": "VOUCHER",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": null,
      "expiresAt": "2019-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",
        "purchasable": false,
        "summary": "Example summary",
        "isLocked": true
      },
      "owner": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      }
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "benefit": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "expiresAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "reward": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                },
                "purchasable": {
                  "type": "boolean"
                },
                "summary": {
                  "type": "string"
                },
                "isLocked": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "createdAt",
                "updatedAt",
                "name",
                "pictureUrl",
                "purchasable"
              ]
            },
            "owner": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "accountNumber": {
                  "type": "number"
                },
                "authIdentifier": {
                  "type": "string"
                },
                "externalIdentifier": {
                  "type": "string"
                },
                "isRestricted": {
                  "type": "boolean"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "flags": {
                  "type": "object",
                  "properties": {
                    "genderProvided": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "required": [
                "id",
                "accountNumber",
                "authIdentifier",
                "isRestricted",
                "createdAt",
                "updatedAt"
              ]
            }
          },
          "required": [
            "id",
            "type",
            "reward"
          ]
        }
      }
    }
  },
  "required": [
    "status",
    "data"
  ]
}
Headers
Content-Type: application/json
X-Api-Key: $api_key
X-Impersonate: $user_id
Authorization: Bearer $access_token
Body
{
  "rewardId": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "beneficiaryId": "8cb2cc08-e033-4200-86a7-95a03ba09462"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "rewardId": {
      "type": "string"
    },
    "beneficiaryId": {
      "type": "string"
    }
  },
  "required": [
    "rewardId",
    "beneficiaryId"
  ]
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "benefit": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "type": "VOUCHER",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": null,
      "expiresAt": "2019-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",
        "purchasable": false,
        "summary": "Example summary",
        "isLocked": true
      },
      "owner": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      }
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "benefit": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "expiresAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "reward": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                },
                "purchasable": {
                  "type": "boolean"
                },
                "summary": {
                  "type": "string"
                },
                "isLocked": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "createdAt",
                "updatedAt",
                "name",
                "pictureUrl",
                "purchasable"
              ]
            },
            "owner": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "accountNumber": {
                  "type": "number"
                },
                "authIdentifier": {
                  "type": "string"
                },
                "externalIdentifier": {
                  "type": "string"
                },
                "isRestricted": {
                  "type": "boolean"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "flags": {
                  "type": "object",
                  "properties": {
                    "genderProvided": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "required": [
                "id",
                "accountNumber",
                "authIdentifier",
                "isRestricted",
                "createdAt",
                "updatedAt"
              ]
            }
          },
          "required": [
            "id",
            "type",
            "reward"
          ]
        }
      }
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Purchase a Reward
POST/commands/purchase_reward

Use this endpoint to purchase a Reward defined within White Label Loyalty.

The concept of “purchasing” is used to represent the flow where a user chooses a specific reward. If the chosen reward defines a points “cost” then the user will only be able to complete the purchase if they have sufficient points and that point value will be deducted from their wallet.

See the Understanding Rewards and Benefits for more information.

This endpoint can either be invoked with a privileged administrative access token or with a user’s own access token.

If using an admin token, you must specify the X-Impersonate header with the ID of the user you wish to execute the purchase as.

If using a user token, the purchase will naturally be considered executed by the user linked to the enclosed token.

If you wish to purchase a reward on behalf of a team you can use the beneficiaryId property to provide the ID of the team that should receive the benefit of this purchase.

🔐 Multiple authorization modes

Requests to this method require either:

👤 User Authorization

🔒 Admin Authorization with update:users scope

Non-compliant requests will be rejected.


Benefit Redemptions

POST api.rewards.wlloyalty.net/v1/commands/redeem_benefit
RequestsFull
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "benefitId": "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": {
    "benefitId": {
      "type": "string"
    },
    "position": {
      "type": "object",
      "properties": {
        "longitude": {
          "type": "number"
        },
        "latitude": {
          "type": "number"
        }
      },
      "required": [
        "longitude",
        "latitude"
      ]
    }
  },
  "required": [
    "benefitId"
  ]
}
Responses200
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "status": "success",
  "data": {
    "benefit": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "type": "VOUCHER",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": "2018-06-10T21:07:01.219Z",
      "expiresAt": "2019-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",
        "purchasable": false,
        "summary": "Example summary",
        "isLocked": true
      },
      "owner": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "accountNumber": 1000001,
        "authIdentifier": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "externalIdentifier": "any string",
        "isRestricted": false,
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "flags": {
          "genderProvided": false
        }
      }
    },
    "code": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "redeemedAt": "2018-06-08T08:57:47.198Z",
      "validatedAt": "2018-06-08T08:57:47.198Z",
      "value": "123ABC"
    }
  }
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "properties": {
        "benefit": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "type": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "expiresAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "reward": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                },
                "purchasable": {
                  "type": "boolean"
                },
                "summary": {
                  "type": "string"
                },
                "isLocked": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "createdAt",
                "updatedAt",
                "name",
                "pictureUrl",
                "purchasable"
              ]
            },
            "owner": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "accountNumber": {
                  "type": "number"
                },
                "authIdentifier": {
                  "type": "string"
                },
                "externalIdentifier": {
                  "type": "string"
                },
                "isRestricted": {
                  "type": "boolean"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "flags": {
                  "type": "object",
                  "properties": {
                    "genderProvided": {
                      "type": "boolean"
                    }
                  }
                }
              },
              "required": [
                "id",
                "accountNumber",
                "authIdentifier",
                "isRestricted",
                "createdAt",
                "updatedAt"
              ]
            }
          },
          "required": [
            "id",
            "type",
            "reward"
          ]
        },
        "code": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "redeemedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "validatedAt": {
              "type": [
                "string",
                "null"
              ]
            },
            "value": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "value"
          ]
        }
      }
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Redeem a Benefit
POST/commands/redeem_benefit

Use this endpoint to redeem a benefit. See the Understanding rewards and benefits for more information.

The position property is an optional property. You can pass the beneficiary user’s current position geo-coordinates to enable integration with the venues module.

🔐 Multiple authorization modes

Requests to this method require either:

👤 User Authorization

🔒 Admin Authorization with update:users scope

Non-compliant requests will be rejected.


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"
  ]
}
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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true,
      "type": "VOUCHER",
      "price": 0,
      "priority": 0,
      "tier": {
        "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
        "name": "Gold",
        "description": "This is an example",
        "artworkUrl": "https://google.com/logo.gif",
        "priority": 0
      },
      "value": 0,
      "category": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "name": "Category Name",
        "description": "This is an example description",
        "priority": 1,
        "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "pictureUrl": ""
      },
      "discounts": [
        {
          "type": "FIXED",
          "value": 1000,
          "sku": "321ZA",
          "productSku": "AZ123"
        }
      ],
      "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"
            },
            "purchasable": {
              "type": "boolean"
            },
            "summary": {
              "type": "string"
            },
            "isLocked": {
              "type": "boolean"
            },
            "type": {
              "type": "string",
              "enum": [
                "VOUCHER",
                "GENERIC_OFFER",
                "AWIN_PROGRAMME",
                "FIDEL_OFFER",
                "OLIVE_OFFER",
                "WEGIFT_PRODUCT",
                "XOXO_PRODUCT"
              ]
            },
            "price": {
              "type": "number"
            },
            "priority": {
              "type": "number"
            },
            "tier": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "artworkUrl": {
                  "type": "string"
                },
                "priority": {
                  "type": "number"
                }
              },
              "required": [
                "id",
                "name",
                "priority"
              ]
            },
            "value": {
              "type": "number"
            },
            "category": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "priority": {
                  "type": "number"
                },
                "parent": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                }
              }
            },
            "discounts": {
              "type": "array"
            },
            "availability": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "purchasable",
            "type",
            "price",
            "priority",
            "value",
            "discounts",
            "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"
  ]
}
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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true,
      "type": "VOUCHER",
      "price": 0,
      "priority": 0,
      "tier": {
        "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
        "name": "Gold",
        "description": "This is an example",
        "artworkUrl": "https://google.com/logo.gif",
        "priority": 0
      },
      "value": 0,
      "category": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "name": "Category Name",
        "description": "This is an example description",
        "priority": 1,
        "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "pictureUrl": ""
      },
      "discounts": [
        {
          "type": "FIXED",
          "value": 1000,
          "sku": "321ZA",
          "productSku": "AZ123"
        }
      ],
      "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"
            },
            "purchasable": {
              "type": "boolean"
            },
            "summary": {
              "type": "string"
            },
            "isLocked": {
              "type": "boolean"
            },
            "type": {
              "type": "string",
              "enum": [
                "VOUCHER",
                "GENERIC_OFFER",
                "AWIN_PROGRAMME",
                "FIDEL_OFFER",
                "OLIVE_OFFER",
                "WEGIFT_PRODUCT",
                "XOXO_PRODUCT"
              ]
            },
            "price": {
              "type": "number"
            },
            "priority": {
              "type": "number"
            },
            "tier": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "artworkUrl": {
                  "type": "string"
                },
                "priority": {
                  "type": "number"
                }
              },
              "required": [
                "id",
                "name",
                "priority"
              ]
            },
            "value": {
              "type": "number"
            },
            "category": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "priority": {
                  "type": "number"
                },
                "parent": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                }
              }
            },
            "discounts": {
              "type": "array"
            },
            "availability": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "purchasable",
            "type",
            "price",
            "priority",
            "value",
            "discounts",
            "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"
  ]
}
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",
      "purchasable": false,
      "summary": "Example summary",
      "isLocked": true,
      "type": "VOUCHER",
      "price": 0,
      "priority": 0,
      "tier": {
        "id": "7fbfb45b-4ee0-471a-a464-67ca580eed7c",
        "name": "Gold",
        "description": "This is an example",
        "artworkUrl": "https://google.com/logo.gif",
        "priority": 0
      },
      "value": 0,
      "category": {
        "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "createdAt": "2018-06-08T08:57:47.198Z",
        "updatedAt": "2018-06-08T08:57:47.198Z",
        "name": "Category Name",
        "description": "This is an example description",
        "priority": 1,
        "parent": "9cb2cc08-e033-4200-86a7-95a03ba09462",
        "pictureUrl": ""
      },
      "discounts": [
        {
          "type": "FIXED",
          "value": 1000,
          "sku": "321ZA",
          "productSku": "AZ123"
        }
      ],
      "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"
            },
            "purchasable": {
              "type": "boolean"
            },
            "summary": {
              "type": "string"
            },
            "isLocked": {
              "type": "boolean"
            },
            "type": {
              "type": "string",
              "enum": [
                "VOUCHER",
                "GENERIC_OFFER",
                "AWIN_PROGRAMME",
                "FIDEL_OFFER",
                "OLIVE_OFFER",
                "WEGIFT_PRODUCT",
                "XOXO_PRODUCT"
              ]
            },
            "price": {
              "type": "number"
            },
            "priority": {
              "type": "number"
            },
            "tier": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "artworkUrl": {
                  "type": "string"
                },
                "priority": {
                  "type": "number"
                }
              },
              "required": [
                "id",
                "name",
                "priority"
              ]
            },
            "value": {
              "type": "number"
            },
            "category": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "priority": {
                  "type": "number"
                },
                "parent": {
                  "type": "string"
                },
                "pictureUrl": {
                  "type": "string"
                }
              }
            },
            "discounts": {
              "type": "array"
            },
            "availability": {
              "type": "object",
              "properties": {
                "start": {
                  "type": "string"
                },
                "end": {
                  "type": "string"
                }
              }
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "name",
            "pictureUrl",
            "purchasable",
            "type",
            "price",
            "priority",
            "value",
            "discounts",
            "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"
  ]
}
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 a 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 field is mandatory, the userIdentifier field is optional but recommended where possible since it allows validating that the code also belongs to the specified user. 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 occurring.

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.


Badge Awards

POST api.rewards.wlloyalty.net/v1/commands/award_badge
RequestsAdmin for User
Headers
Content-Type: application/json
X-Api-Key: $api_key
Authorization: Bearer $access_token
Body
{
  "badgeId": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "beneficiaryId": "9cb2cc08-e033-4200-86a7-95a03ba09462",
  "comment": "Great work!"
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "badgeId": {
      "type": "string"
    },
    "beneficiaryId": {
      "type": "string"
    },
    "comment": {
      "type": "string"
    }
  },
  "required": [
    "badgeId",
    "beneficiaryId"
  ]
}
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",
    "badge": {
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
      "createdAt": "2018-06-08T08:57:47.198Z",
      "updatedAt": "2018-06-08T08:57:47.198Z",
      "internalName": "Example Badge",
      "priority": 0,
      "status": "ACTIVE",
      "details": [
        {
          "name": "Great Work Badge",
          "locale": "en",
          "description": "A badge for people doing some great work",
          "artworkUrl": "https://picsum.photos/50",
          "id": "9cb2cc08-e033-4200-86a7-95a03ba09462",
          "createdAt": "2018-06-08T08:57:47.198Z",
          "updatedAt": "2018-06-08T08:57:47.198Z"
        }
      ]
    },
    "comment": "Great work!"
  }
}
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"
        },
        "badge": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "createdAt": {
              "type": "string"
            },
            "updatedAt": {
              "type": "string"
            },
            "internalName": {
              "type": "string"
            },
            "priority": {
              "type": "number"
            },
            "status": {
              "type": "string",
              "enum": [
                "ACTIVE",
                "INACTIVE",
                "ARCHIVED"
              ]
            },
            "details": {
              "type": "array"
            }
          },
          "required": [
            "id",
            "createdAt",
            "updatedAt",
            "internalName",
            "priority",
            "details"
          ]
        },
        "comment": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "badge"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Award a badge
POST/commands/award_badge

Use this endpoint to award a Badge to a specific user.

🔐 Admin authorization required

Requests to this method must provide an Authorization header containing a valid administrative token with at least update:users OR update:teams scope depending on whether you’re targeting a User or a Team. 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",
            "null"
          ],
          "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",
            "null"
          ],
          "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.

See the Specific User Referral Code documentation for more information.

👤 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

List Referral Codes

GET api.rewards.wlloyalty.net/v1/campaigns/9cb2cc08-e033-4200-86a7-95a03ba09462/referral_codes
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": {
          "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"
        }
      },
      "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
      "createdAt": "2021-06-08T08:57:47.198Z",
      "updatedAt": "2021-06-08T08:57:47.198Z",
      "referrals": [
        {
          "sourceUserId": "9cb2cc08-e033-4200-86a7-95a03ba04875",
          "source": "EMAIL",
          "userAgent": "IOS",
          "referralCode": {
            "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"
          },
          "registeredUser": {
            "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"
            }
          },
          "referralTrancheStatuses": [
            {
              "trancheId": "9cb2cc08-e033-4200-86a7-95a03ba06845",
              "activations": 0,
              "isCompleted": false
            }
          ]
        }
      ]
    }
  ]
}
Schema
HideShow
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "data": {
      "type": "array",
      "items": {
        "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",
              "null"
            ],
            "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",
                      "null"
                    ],
                    "properties": {}
                  },
                  "id": {
                    "type": "string"
                  },
                  "createdAt": {
                    "type": "string"
                  },
                  "updatedAt": {
                    "type": "string"
                  }
                },
                "required": [
                  "inviteCode",
                  "inviteLink",
                  "campaign",
                  "id"
                ]
              }
            },
            "required": [
              "isRestricted",
              "profile",
              "authIdentifier",
              "id",
              "accountNumber",
              "createdAt",
              "updatedAt"
            ]
          },
          "id": {
            "type": "string"
          },
          "createdAt": {
            "type": "string"
          },
          "updatedAt": {
            "type": "string"
          },
          "referrals": {
            "type": "array"
          }
        },
        "required": [
          "inviteCode",
          "inviteLink",
          "campaign",
          "id"
        ]
      }
    }
  },
  "required": [
    "status"
  ]
}

List all Referral Codes for a campaign
GET/campaigns/{campaign_id}/referral_codes

Get a list of all referral codes for a specific campaign.

🔒 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
campaign_id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the campaign to query.


Referral Codes

GET api.rewards.wlloyalty.net/v1/campaigns/9cb2cc08-e033-4200-86a7-95a03ba09462/referral_codes/9cb2cc08-e033-4200-86a7-95a03ba09786
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": {
        "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"
      }
    },
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
    "createdAt": "2021-06-08T08:57:47.198Z",
    "updatedAt": "2021-06-08T08:57:47.198Z",
    "referrals": [
      {
        "sourceUserId": "9cb2cc08-e033-4200-86a7-95a03ba04875",
        "source": "EMAIL",
        "userAgent": "IOS",
        "referralCode": {
          "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"
        },
        "registeredUser": {
          "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"
          }
        },
        "referralTrancheStatuses": [
          {
            "trancheId": "9cb2cc08-e033-4200-86a7-95a03ba06845",
            "activations": 0,
            "isCompleted": false
          }
        ]
      }
    ]
  }
}
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",
            "null"
          ],
          "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",
                    "null"
                  ],
                  "properties": {}
                },
                "id": {
                  "type": "string"
                },
                "createdAt": {
                  "type": "string"
                },
                "updatedAt": {
                  "type": "string"
                }
              },
              "required": [
                "inviteCode",
                "inviteLink",
                "campaign",
                "id"
              ]
            }
          },
          "required": [
            "isRestricted",
            "profile",
            "authIdentifier",
            "id",
            "accountNumber",
            "createdAt",
            "updatedAt"
          ]
        },
        "id": {
          "type": "string"
        },
        "createdAt": {
          "type": "string"
        },
        "updatedAt": {
          "type": "string"
        },
        "referrals": {
          "type": "array"
        }
      },
      "required": [
        "inviteCode",
        "inviteLink",
        "campaign",
        "id"
      ]
    }
  },
  "required": [
    "status",
    "data"
  ]
}

Retrieve a Referral Code
GET/campaigns/{campaign_id}/referral_codes/{referral_code}

Retrieve a referral code

🔒 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
campaign_id
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09462

ID of the campaign the referral code belongs to.

referral_code
uuid (required) Example: 9cb2cc08-e033-4200-86a7-95a03ba09786

ID of the referral code to retrieve.


PATCH api.rewards.wlloyalty.net/v1/campaigns/9cb2cc08-e033-4200-86a7-95a03ba09462/referral_codes/9cb2cc08-e033-4200-86a7-95a03ba09786
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": {
        "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"
      }
    },
    "id": "9cb2cc08-e033-4200-86a7-95a03ba09461",
    "createdAt": "2021-06-08T08:57:47.198Z",
    "updatedAt": "2021-06-08T08:57:47.198Z",
    "referrals": [
      {
        "sourceUserId": "9cb2cc08-e033-4200-86a7-95a03ba04875",
        "source": "EMAIL",
        "userAgent": "IOS",
        "referralCode": {
          "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