Skip to main content
API docs by Redocly

Platform API (1.0.0)

Download OpenAPI specification:Download

PepperHQ: info@pepperhq.com URL: https://www.pepperhq.com

Actions

Use the actions endpoints to post and retrieve actions

Get Actions for User

Retrieve the Actions for a specific User.

This path is versioned via the x-api-version header, which should be '9' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Actions for.

query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

when.timestamp[.gt | .lte | .eq | .neq]
string <date-time>

Filter the response using action when.timestamp in comparison to this iso date value. Valid values of comparison are 'gt' (for greater than), 'lte', 'eq', 'neq'. The comparison defaults to 'eq' when not provided

type[.in | .nin]
string

Filter the response using action 'type' in comparison this list of comma separated types. Valid values of comparison are 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided

paymentType[.in | .nin]
string
Example: paymentType[.in | .nin]=CARDHOLDER_PRESENT,APPLEPAY

Filter transactions by payment type. Accepts comma-separated list of OrderPaymentType enum values. Valid values: CASH_AT_POS, CARD_AT_POS, GIFT_CARD_AT_POS, OTHER_AT_POS, APPLEPAY, GOOGLEPAY, CARD_ON_FILE, CARD_TENDERED, GIFT_CARD, CARDHOLDER_PRESENT, CASH, CARD, OTHER, APP, PAY_BY_BANK. Use 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '7': deprecated behaviour (default)
  • '8' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ]
}

Get Actions for Location

Retrieves the Actions for a specific Location

This path is versioned via the x-api-version header, which should be '9' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location to retrieve the Actions for.

query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

when.timestamp[.gt | .lte | .eq | .neq]
string <date-time>

Filter the response using action when.timestamp in comparison to this iso date value. Valid values of comparison are 'gt' (for greater than), 'lte', 'eq', 'neq'. The comparison defaults to 'eq' when not provided

type[.in | .nin]
string

Filter the response using action 'type' in comparison this list of comma separated types. Valid values of comparison are 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided

paymentType[.in | .nin]
string
Example: paymentType[.in | .nin]=CARDHOLDER_PRESENT,APPLEPAY

Filter transactions by payment type. Accepts comma-separated list of OrderPaymentType enum values. Valid values: CASH_AT_POS, CARD_AT_POS, GIFT_CARD_AT_POS, OTHER_AT_POS, APPLEPAY, GOOGLEPAY, CARD_ON_FILE, CARD_TENDERED, GIFT_CARD, CARDHOLDER_PRESENT, CASH, CARD, OTHER, APP, PAY_BY_BANK. Use 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '8': deprecated behaviour (default)
  • '9' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ]
}

Get Actions

Retrieve the Actions for the Tenant.

Get all of the Actions for the Tenant, sorted in reverse chronological order.

For an overview of the Action construct, please see the Overview of Actions guide. This includes a link to the JSON Schema the defines the structure of an Action in detail.

This path is versioned via the x-api-version header, which should be '9' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

when.timestamp[.gt | .lte | .eq | .neq]
string <date-time>

Filter the response using action when.timestamp in comparison to this iso date value. Valid values of comparison are 'gt' (for greater than), 'lte', 'eq', 'neq'. The comparison defaults to 'eq' when not provided

type[.in | .nin]
string

Filter the response using action 'type' in comparison this list of comma separated types. Valid values of comparison are 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided

locationId
string

Filter the response using action 'locationId'. This is a list of comma separated locationIds.

credentialId
string

Filter the response using a user's full credential (email or phone number)

paymentType[.in | .nin]
string
Example: paymentType[.in | .nin]=CARDHOLDER_PRESENT,APPLEPAY

Filter transactions by payment type. Accepts comma-separated list of OrderPaymentType enum values. Valid values: CASH_AT_POS, CARD_AT_POS, GIFT_CARD_AT_POS, OTHER_AT_POS, APPLEPAY, GOOGLEPAY, CARD_ON_FILE, CARD_TENDERED, GIFT_CARD, CARDHOLDER_PRESENT, CASH, CARD, OTHER, APP, PAY_BY_BANK. Use 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '7': deprecated behaviour (default)
  • '8' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ]
}

Get an Action

Retrieve a specific Action

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
actionId
required
string

The ID of the Action to retrieve

Create an actions export

Generate a csv export of actions

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
limit
number

The maximum number of actions to be exported

from
required
string

Only export actions from this date

to
required
string

Only export actions up to this date

maxFileSizeMB
number

Maximum size of a single csv file

locationIds
Array of strings

Only export actions at these locations

types
required
Array of strings

Only export actions matching these types

Responses

Request samples

Content type
application/json
{
  • "limit": 0,
  • "from": "string",
  • "to": "string",
  • "maxFileSizeMB": 0,
  • "locationIds": [
    ],
  • "types": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Download an actions export

Download a csv export of actions.

The full path including fileId is retrieved from the import operation's href.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Addresses

Address-related operations

Create Addresses for User

Create one address for a specific user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the user to create the address for.

Request Body schema: application/json
name
string
required
object
coordinates
required
Array of numbers[ items = 2 items ]

[Longitude, Latitude]

note
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": {
    },
  • "coordinates": [
    ],
  • "note": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Update Addresses for User

Update one address for a specific user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the user to create the address for.

addressId
required
string

The unique ID of the address to update.

Request Body schema: application/json
name
string
required
object
coordinates
required
Array of numbers[ items = 2 items ]

[Longitude, Latitude]

note
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": {
    },
  • "coordinates": [
    ],
  • "note": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete Addresses from User

Delete one address for a specific user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the user to delete the address from.

addressId
required
string

The unique ID of the address to delete.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Suggest addresses based on a query string

Suggest addresses based on a text query or a set of coordinates.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
One of
address
required
string
position
Array of numbers[ items = 2 items ]

[Longitude, Latitude]

Responses

Request samples

Content type
application/json
Example
{
  • "address": "string",
  • "position": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get an addresses' coordinates

Get an addresses' coordinates based on a partial or full address.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
line1
required
string
line2
string
city
required
string
region
string
postalCode
string
country
required
string

Responses

Request samples

Content type
application/json
{
  • "line1": "string",
  • "line2": "string",
  • "city": "string",
  • "region": "string",
  • "postalCode": "string",
  • "country": "string"
}

Response samples

Content type
application/json
{
  • "position": [
    ]
}

Awards

An 'award' records whether or not a user has accrued loyalty points for a particular 'perk'. A perk is the definition of an award type and defines how the award is earnt and redeemed.

When a user has sufficient points in the award points.available field, the award can be redeemed in exchange for something of value, such as a discount on an order.

In the past, Pepper had two loyalty schemas: Perks and 'PointPerk'. All perks are now stored as 'PointPerks', and we are now in the process of refactoring the endpoints to remove the distinctions between the two schemes.

Get Awards

Gets all Awards for the merchant or user.

The response is paged. Use limit and startKey to control the page returned.

When called by a normal User, this returns all the user's awards. When called by authenticated Admin user, this returns all the merchant's awards. An admin user can specify a userId query parameter to return that user's awards only.

Note: when the merchant is connected to an external loyalty system rather than the PEPPER loyalty system, getting all merchant's awards is not supported.

A caller can select specific fields to be returned by setting the fields query parameter.

This path is versioned via the x-api-version header, which should be '9' or higher. When x-api-version header is not present, the legacy resource is returned.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

userId
string

Retrieve awards for this user. Admin only.

includeUnvisualisedAwards
string

if true, it will include awards that have not been visualised in the response.

includeDisabled
string

if true, it will include awards linked to disabled perks in the response.

locationId
string

if supported by merchant's setup, it will only return the list of awards valid for the location ID provided.

fields
string

Limit the response to specific fields. Valid fields are: _id, tenantId, userId, loyaltyProvider, perkId, points, and updatedAt

updatedAt[.gt | .lte | .eq | .neq]
string <date-time>

Filter the response using award updatedAt in comparison to this RFC 3339 date value. Valid values of comparison are 'gt' (for greater than), 'lte', 'eq', 'neq'. The comparison defaults to 'eq' when not provided.

Filtering using updateAt when the merchant is connected to an external loyalty system rather than the PEPPER loyalty system.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '7': deprecated behaviour (default)
  • '8' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Start Bulk Grant Awards Import

Upload and process file to grant awards perks and award points to users. The response is an operation resource.

Use the response's operation _id to poll GET /operations/:operationId in order to monitor progress.
When complete, the operation will contain a result.href field providing a link to download a file of results.

Use the dryRun=true to test processing your file and validating userIds before running the award granting for real.

Use the dryRun=false to process the file and grant awards.
Warning: If you repeat the import, extra award points will be granted. The import is NOT idempotent.

The import file format should be a plain text file with comma separated values, and the first row as column headings. The possible column formats are:

With perk_id column:

user_id, perk_id
60f7e53e944a60af2caa9977, 60f7e54b3438386d4b09719a
60f7e55550f30ab39776b834, 60f7e55d04d203c77d7f54d9

With perk_id and points column:

user_id, perk_id, points
60f7e53e944a60af2caa9977, 60f7e54b3438386d4b09719a, 5
60f7e55550f30ab39776b834, 60f7e55d04d203c77d7f54d9, 3

With one or more perk_XXXXX and columns, where XXXX is the perk id to award, and the column contains the points to award

user_id, perk_60f7e54b3438386d4b09719a, perk_60f7e55d04d203c77d7f54d9
60f7e53e944a60af2caa9977, 5, 0
60f7e55550f30ab39776b834, 3, 1
Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
dryRun
string

Set dryRun to false in order to perform the import. Otherwise, the import file will be processed to check for errors, but no awards will be granted.

suppressEvents
string

Set suppressEvents to false to cause all events to be emitted on award granting.

header Parameters
x-pepper-req-nonce
string

This call requires a nonce in this header to prevent duplicate processing of calls. The nonce value represents an individual call. It should be set to a guid. Each new call should have a new guid. In the rare occasion you want to repeat a call, use the original guid value.

Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "namespace": "string",
  • "entityId": "string",
  • "nonce": "string",
  • "name": "string",
  • "status": "DONE",
  • "result": {
    },
  • "error": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "endedAt": "string"
}

Get Bulk Grant Awards Import Result

Download a file of award grant import results.

The full path including fileId is retrieved from the import operation's href.

Example Result File:

user_id,perk_id,points,result,perk_awarded_1,award_awarded_1,points_available_1,error
5bc074a3bd07b10d8684773e,60f02ff1cbe10f0ecca644a9,1,ok,60f02ff1cbe10f0ecca644a9,63a099fe6f0b6d0eca2fbcaa,1,
5bd09db25fe1810d99862192,60f02ff1cbe10f0ecca644a9,1,fail,,,,user not found
Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
fileId
required
string

The ID of the file to download.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Update Award (PointAward)

Update an award for a user.

Use this method to change the points fields associated with an award.

Unlike grant, redeem or refund award, no actions are emitted on this call.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
awardId
required
string

The Id of the award to update.

Request Body schema: application/json
object
available
number

The user's current points balance on this award

Responses

Request samples

Content type
application/json
{
  • "points": {
    }
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Award a Perk Deprecated

Grant an award based on the specified perk to a user or segment.

Note: this endpoint returns the old Perks schema and will be changed in a future version. Use the endpoint POST /pointperks/:perkId/awards in the meantime.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The Id of the perk to award.

Request Body schema: application/json
userId
required
string

Responses

Request samples

Content type
application/json
{
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Award a Perk (PointPerk)

Grant an award based on the specified perk to a user.

Note: this endpoint will be deprecated in an upcoming release and be replaced by the endpoint POST /perks/:perkId/awards.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The Id of the perk to award.

Request Body schema: application/json
userId
required
string
points
number

The value to award the user. If not specified, the default value of the perk will be used.

locationId
string

The id of the location associated with this grant, if any

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "points": 0,
  • "locationId": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "template": "STAMP_CARD",
  • "title": "string",
  • "terms": "string",
  • "priority": 0,
  • "redemptionMethod": "AUTO",
  • "auto": true,
  • "token": "string",
  • "maximumPointCashValue": 0,
  • "discount": {
    },
  • "dateTimeRestriction": {
    },
  • "basketQualification": {
    },
  • "visualisation": {
    },
  • "isDonatable": true,
  • "isGlobal": true,
  • "isTier": true,
  • "updatedAt": "string",
  • "locationIds": [
    ],
  • "points": {
    }
}

Get a User's Awards Deprecated

Get all Awards for a specific User

Note: this endpoint returns the old Perks schema and will be changed in a future version. Use the endpoint GET /users/:userId/pointawards in the meantime.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Awards for.

query Parameters
includeUnvisualisedAwards
string

if true, it will include awards that have not been visualised in the response.

includeDisabled
string

if true, it will include awards linked to disabled perks in the response.

locationId
string

if supported by merchant's setup, it will only return the list of awards valid for the location ID provided.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Get a User's Awards (PointPerk)

Get all awards for a specific user

This endpoint will be deprecated in an upcoming release and be replaced by GET /user/:userId/awards

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Awards for.

query Parameters
includeUnvisualisedAwards
string

if true, it will include awards that have not been visualised in the response.

includeDisabled
string

if true, it will include awards linked to disabled perks in the response.

locationId
string

if supported by merchant's setup, it will only return the list of awards valid for the location ID provided.

Responses

Response samples

Content type
application/json
{
  • "awards": [
    ]
}

Redeem an Award Deprecated

Redeem a specific award for a specific user.

Note: this endpoint affects the old Perks schema and will be changed in a future version. Use the endpoint GET /users/:userId/pointawards/:awardId in the meantime.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The Id of the user

awardId
required
string

The Id of the award.

Request Body schema: application/json
valueToRedeem
required
number

The number of points to deduct from award

Responses

Request samples

Content type
application/json
{
  • "valueToRedeem": 0
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Redeem an Award (PointPerk)

Redeem a specific award for a specific user.

This endpoint will be deprecated in an upcoming release and be replaced by PUT users/:userId/awards/:awardId (TBD)

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The Id of the user

awardId
required
string

The Id of the award.

Request Body schema: application/json
valueToRedeem
required
number

The number of points to deduct from award points.available

locationId
string

The id of the location where the award was redeemed

Responses

Request samples

Content type
application/json
{
  • "valueToRedeem": 0,
  • "locationId": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Refund an Award Redemption (PointPerk)

Refund a redeemption of a specific award for a specific user.

This endpoint will be deprecated in an upcoming release and be replaced by PUT users/:userId/awards/:awardId (TBD)

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The Id of the user

awardId
required
string

The Id of the award.

Request Body schema: application/json
value
required
number

The number of points to refund to award points.available

Responses

Request samples

Content type
application/json
{
  • "value": 0
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Checkins

A 'checkin' records when a user has arrived at a particular location.

It is used by the platform to

  • provide custom content to the user tailored for that location
  • allow the location's POS to see who is in the location so that the sales assistant can easily select a customer to add to an open basket.

Create a Checkin for a User

If a Checkin is created for a User that does not already have a profile photo associated with their account, a status of 422 will be returned and the Checkin will not be created.

If the User for which a Checkin is being created is already checked in at another Location, the other Checkins will be deleted automatically for them. A User may only be checked in at a single Location at a time.

If the User is already checked in at the Location, an HTTP status code of 409 (Conflict) will be returned by the API.

Checkins will be automatically deleted after 30 minutes.

If the POS associated with the Merchant supports it, a notification will be delivered to the Location’s POS when a new Checkin is created.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The Id of the User to create the Checkin for.

Request Body schema: application/json
locationId
string

Location where the user checked in

type
string
Enum: "AUTO" "MANUAL" "CFD" "OFFLINE" "UNKNOWN"
trigger
string
Enum: "GEO" "BEACON" "CODE" "POS" "UNKNOWN"

What triggered the checkin to occur

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "type": "AUTO",
  • "trigger": "GEO"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "userId": "string",
  • "locationTitle": "string",
  • "userFullName": "string",
  • "type": "AUTO",
  • "updated": "string",
  • "created": "string",
  • "locationId": "string",
  • "trigger": "GEO"
}

Get Checkins for a User

Retrieves the Checkins for a specific User.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Checkins for.

query Parameters
per_page
string
Default: 20

Set the response to be paged by this number of results per page.

page
string
Default: 1

Request a specific page of results in the response. The first page is page 1

Responses

Response samples

Content type
application/json
{
  • "checkins": [
    ],
  • "summary": {
    }
}

Get all Checkins

Retrieves the Checkins for the authenticated User.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
per_page
integer <int32>
Default: "20"

How many results to return.

page
integer <int32>
Default: "1"

Which page of results to return.

Create a Checkin

Create a Checkin for the authenticated User

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Update a Checkin

Updates a specific Checkin

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
checkinId
required
string

The unique ID of the Checkin to update.

Credentials

Credentials gives access to users' login details as well as secondary email and phone details.

Get user credentials

Retrieves the Credentials for a specific User.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Credentials for.

Get credentials

Get credentials, filtering by matching arguments such as id

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
id
string

Find credentials matching a specified email or mobile number.

provider
string

Find credentials matching the provider (email, mobile)

sort
string

The names of the fields to sort the results by, in decreasing order of precendence. Allowed values are _id, id, provider. Separate each field by a comma. Prepend the field name with - sign to sort that field in descending order.

limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "id": "string",
  • "provider": "EMAIL",
  • "isVerified": "string",
  • "isPrimary": "string"
}

Create a secondary credential for a user

Create a secondary unverified passwordless (user will not be able to log in with) credential for a user. Triggers a verification code to be sent to the user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
id
required
string

username of the new credential

provider
required
string
Enum: "EMAIL" "MOBILE"

type of credential

skipVerification
boolean

Indicates whether verification should be skipped for this credential

Responses

Request samples

Content type
application/json
{
  • "id": "user@pepperhq.com",
  • "provider": "EMAIL"
}

Response samples

Content type
application/json
{
  • "_id": "5d3098a0ee2cb3561b704de3",
  • "id": "user@pepperhq.com",
  • "provider": "EMAIL",
  • "isVerified": false,
  • "isPrimary": false
}

Verifies a secondary credential for a user

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
credentialId
required
string

The unique ID of the Credential to verify.

Request Body schema: application/json
verificationCode
required
string

verification code associated with the credential

Responses

Request samples

Content type
application/json
{
  • "verificationCode": "1234"
}

Response samples

Content type
application/json
{
  • "_id": "5d3098a0ee2cb3561b704de3",
  • "id": "user@pepperhq.com",
  • "provider": "EMAIL",
  • "isVerified": true,
  • "isPrimary": false
}

Guests

Guests endpoint provides temporary user accounts, credentials and sessions for guest actions like ordering.

Guest users, credentials and sessions are automatically removed after 1 hour, unless they have been converted into a full USER acount

Create a Guest Session

Create a guest user, credential and session for allowing guest actions like ordering.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
header Parameters
x-client-platform
string
Enum: "ANDROID" "IOS"

Identifies the platform type of the caller.

Request Body schema: application/json
firstName
string
lastName
string
fullName
string
Array of objects
hasAgreedToShareData
boolean

The user has accepted sharing his/her data for the purposes of using the Tenant's application (GDPR).

hasAgreedToReceiveMarketing
boolean

The user has accepted receiving marketing messages from or on behalf of the Tenant (GDPR).

birthdate
string

Birthdate in ISO format - eg 1997-12-25

gender
string
Enum: "FEMALE" "MALE"

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "fullName": "string",
  • "credentials": [
    ],
  • "hasAgreedToShareData": true,
  • "hasAgreedToReceiveMarketing": true,
  • "birthdate": "string",
  • "gender": "FEMALE"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "userId": "string",
  • "tenantId": "string",
  • "tenantTitle": "string",
  • "permanent": true,
  • "lastName": "string",
  • "fullName": "string",
  • "state": "ACTIVE",
  • "isGuest": true,
  • "isPrimary": true,
  • "roles": [
    ],
  • "user": {
    }
}

Locations

Locations gives access to a merchant's locations for defining location specific details such as:

  • opening hours
  • available services
  • promotional material and branding for display in the App

Get Locations

Gets locations for a Tenant filtering based on query parameters

This path is versioned via the x-api-version header. The current version is '9' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
state
string

A comma separated list of location states to filter by. Possible states are 'PENDING', 'ACTIVE', 'RETIRED'

lat
number <double>

The latitude of the search centre

long
number <double>

The longitude of the search centre

search
string

Filter to those locations whose title includes the search term, in a comma separated list. The match may be a substring.

title
string

Title of the location to search for

favourites
boolean

Filter to the user's favourite locations

tags
string

Filter locations by tags, in a comma separated list.

services
boolean

Filter to the locations which have all the listed services, in a comma separated list.

include
Array of strings
Items Enum: "created" "updated" "state" "mainImageUrl" "alternativeOpeningHoursText" "buttons" "links" "description" "ordering" "VATnumber" "regions" "address" "tags" "zones"

Specify which optional fields to return in the response.

limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Create a Location

Create a Location

This path is versioned via the x-api-version header. The current version is '9' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '5': deprecated behaviour (default)
  • '6' or higher: current behaviour as described here
Request Body schema: application/json
title
required
string

Name of the location

description
string

Description of the location

state
any
Enum: "PENDING" "ACTIVE" "RETIRED"
mainImageUrl
string

URL to an image resource

listingImageUrl
string

URL to an image resource

object
alternativeOpeningHoursText
string

An HTML snippet that overrides how opening hours are displayed in the app. However, the standard opening hours will still be used to determine when the location is open for ordering. This will replace your standard defined opening hours.

facilities
Array of strings
object

Enable or disable different ordering services for the location

Array of objects
object

Enable or disable different social media and third party services for the location

VATnumber
string

VAT / sales tax number

object
object

Contact details for the location

Array of objects
object
geo
required
Array of numbers = 2 items

An array of 2 numbers for longitude, latitude

regions
Array of strings
tags
Array of strings
mapPinImageUrl
string

Optional image url of pin to display to users on map

timezone
string

Timezone of the location eg Europe/London

object

List of zones (keyed by the zone name) in the location that describes a set of tables e.g Garden, Indoors.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "state": "PENDING",
  • "mainImageUrl": "string",
  • "listingImageUrl": "string",
  • "openingHours": {
    },
  • "alternativeOpeningHoursText": "string",
  • "facilities": [
    ],
  • "services": {
    },
  • "buttons": [
    ],
  • "links": {
    },
  • "VATnumber": "string",
  • "address": {
    },
  • "contacts": {
    },
  • "beacons": [
    ],
  • "ordering": {
    },
  • "geo": [
    ],
  • "regions": [
    ],
  • "tags": [
    ],
  • "mapPinImageUrl": "string",
  • "timezone": "string",
  • "zones": { }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "created": "string",
  • "updated": "string",
  • "title": "string",
  • "description": "string",
  • "state": "PENDING",
  • "mainImageUrl": "string",
  • "listingImageUrl": "string",
  • "openingHours": {
    },
  • "alternativeOpeningHoursText": "string",
  • "facilities": [
    ],
  • "services": {
    },
  • "buttons": [
    ],
  • "links": {
    },
  • "VATnumber": "string",
  • "address": {
    },
  • "contacts": {
    },
  • "beacons": [
    ],
  • "ordering": {
    },
  • "geo": [
    ],
  • "regions": [
    ],
  • "tags": [
    ],
  • "mapPinImageUrl": "string",
  • "timezone": "string",
  • "zones": { }
}

Start Bulk Location Import

Upload a CSV file of locations to create or update.

The response is an operation resource that can be polled to monitor progress. When complete, the operation will contain a result.href field providing a link to download a file of results.

Required columns:

  • title, geo_longitude (-180 to 180), geo_latitude (-90 to 90)

Optional columns:

  • _id - MongoDB ObjectId for updates
  • state, description, timezone, VATnumber, mainImageUrl, listingImageUrl, mapPinImageUrl, alternativeOpeningHoursText
  • facilities, regions, tags - Pipe-delimited lists (e.g., "wifi|parking")

Nested fields using dot notation:

  • address.* - line1, line2, city, region, postalCode, country
  • contacts.* - phone, email
  • services.* - checkins, pre_order, book_table, book_room, delivery, dine_in, tab, order_to_table, pay_at_table (boolean)
  • openingHours.* - monday, tuesday, etc. (e.g., "9am-5pm")
  • zones.N.* - Indexed array notation: zones.0.name, zones.0.tables, zones.1.name, etc.
  • links.PROVIDER.* - facebook, twitter, instagram, etc.: enabled (boolean), parameters (e.g., "@handle")

Advanced fields (JSON strings for rare use):

  • ordering_json, buttons_json, extended_json, beacons_json, deliveryBoundaries_json

Upsert behavior: Matches by _id → title (deterministic) → creates new location

Example CSV:

title,geo_longitude,geo_latitude,address.line1,address.city,openingHours.monday,zones.0.name,zones.0.tables
Test Cafe,-0.1276,51.5074,123 Main St,London,9am-5pm,Ground Floor,[[1,10]]
Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
dryRun
string

Set dryRun to false in order to perform the import. Otherwise, the import file will be processed to check for errors, but no locations will be created or updated.

suppressEvents
string

Set suppressEvents to false to cause all events to be emitted during processing.

header Parameters
x-pepper-req-nonce
string

This call requires a nonce in this header to prevent duplicate processing of calls. The nonce value represents an individual call. It should be set to a guid. Each new call should have a new guid. In the rare occasion you want to repeat a call, use the original guid value.

Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "namespace": "string",
  • "entityId": "string",
  • "nonce": "string",
  • "name": "string",
  • "status": "DONE",
  • "result": {
    },
  • "error": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "endedAt": "string"
}

Get Bulk Location Import Result

Download a CSV file of location import results. The full path including fileId is retrieved from the operation's result.href field.

Result file contains all input columns plus: locationId (MongoDB ObjectId), action (created|updated), error (pipe-delimited messages if any).

Example:

title,geo_longitude,geo_latitude,locationId,action,error
Test Cafe,-0.1276,51.5074,507f1f77bcf86cd799439011,created,
Bad Location,invalid,-100,,,geo_longitude invalid or missing | geo_latitude must be between -90 and 90
Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
fileId
required
string

The ID of the file to download (from operation result.href)

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Create a locations export

Generate a CSV export of locations in the same format as the import endpoint.

The response is an operation resource that can be polled to monitor progress. When complete, the operation will contain a result.href field providing a link to download the CSV file.

The exported CSV uses dot notation for nested fields (address.city, services.checkins, etc.) and indexed array notation for zones (zones.0.name, zones.1.name), ensuring compatibility with the import endpoint.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
header Parameters
x-pepper-req-nonce
string

This call requires a nonce in this header to prevent duplicate processing of calls. The nonce value represents an individual call. It should be set to a guid. Each new call should have a new guid. In the rare occasion you want to repeat a call, use the original guid value.

Request Body schema: application/json
limit
number

Maximum number of locations to export

object

Optional filters to apply

Responses

Request samples

Content type
application/json
{
  • "limit": 0,
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "namespace": "string",
  • "entityId": "string",
  • "nonce": "string",
  • "name": "string",
  • "status": "DONE",
  • "metadata": null,
  • "result": null,
  • "error": null,
  • "isRetryable": true,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "endedAt": "string"
}

Download a locations export

Download a CSV export of locations.

The full path including fileId is retrieved from the export operation's result.href field.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
fileId
required
string

The ID of the file to download (from operation result.href)

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Get Location by Id

Retrieve a specific Location by Id

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location to retrieve.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "created": "string",
  • "updated": "string",
  • "title": "string",
  • "description": "string",
  • "state": "PENDING",
  • "mainImageUrl": "string",
  • "listingImageUrl": "string",
  • "openingHours": {
    },
  • "alternativeOpeningHoursText": "string",
  • "facilities": [
    ],
  • "services": {
    },
  • "buttons": [
    ],
  • "links": {
    },
  • "VATnumber": "string",
  • "address": {
    },
  • "contacts": {
    },
  • "beacons": [
    ],
  • "ordering": {
    },
  • "geo": [
    ],
  • "regions": [
    ],
  • "tags": [
    ],
  • "mapPinImageUrl": "string",
  • "timezone": "string",
  • "zones": { }
}

Update a Location

Updates a specific Location with new values.

Any unspecified fields will be left unchanged.

When updating an array or map field, the whole field should be replaced even if just updating one part of it.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location to update.

Request Body schema: application/json
title
string

Name of the location

description
string

Description of the location

state
any
Enum: "PENDING" "ACTIVE" "RETIRED"
mainImageUrl
string

URL to an image resource

listingImageUrl
string

URL to an image resource

object
alternativeOpeningHoursText
string

An HTML snippet that overrides how opening hours are displayed in the app. However, the standard opening hours will still be used to determine when the location is open for ordering. This will replace your standard defined opening hours.

facilities
Array of strings
object

Enable or disable different ordering services for the location

Array of objects
object

Enable or disable different social media and third party services for the location

VATnumber
string

VAT / sales tax number

object
object

Contact details for the location

Array of objects
object
geo
Array of numbers = 2 items

An array of 2 numbers for longitude, latitude

regions
Array of strings
tags
Array of strings
mapPinImageUrl
string

Optional image url of pin to display to users on map

timezone
string

Timezone of the location eg Europe/London

object

List of zones (keyed by the zone name) in the location that describes a set of tables e.g Garden, Indoors.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "state": "PENDING",
  • "mainImageUrl": "string",
  • "listingImageUrl": "string",
  • "openingHours": {
    },
  • "alternativeOpeningHoursText": "string",
  • "facilities": [
    ],
  • "services": {
    },
  • "buttons": [
    ],
  • "links": {
    },
  • "VATnumber": "string",
  • "address": {
    },
  • "contacts": {
    },
  • "beacons": [
    ],
  • "ordering": {
    },
  • "geo": [
    ],
  • "regions": [
    ],
  • "tags": [
    ],
  • "mapPinImageUrl": "string",
  • "timezone": "string",
  • "zones": { }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "created": "string",
  • "updated": "string",
  • "title": "string",
  • "description": "string",
  • "state": "PENDING",
  • "mainImageUrl": "string",
  • "listingImageUrl": "string",
  • "openingHours": {
    },
  • "alternativeOpeningHoursText": "string",
  • "facilities": [
    ],
  • "services": {
    },
  • "buttons": [
    ],
  • "links": {
    },
  • "VATnumber": "string",
  • "address": {
    },
  • "contacts": {
    },
  • "beacons": [
    ],
  • "ordering": {
    },
  • "geo": [
    ],
  • "regions": [
    ],
  • "tags": [
    ],
  • "mapPinImageUrl": "string",
  • "timezone": "string",
  • "zones": { }
}

Delete a Location

Deletes a specific Location

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location to delete.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Create a Register

Create a Register for a Location

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
title
required
string

The title to create the register with

Request samples

Content type
application/json
{
  • "title": "string"
}

Get Registers for a Location

Retrieve the Registers for a specific Location

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location to retrieve Registers for.

Get Checkins for a Location

Retrieve the Checkins for a specific Location

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location to retrieve the Checkins for.

query Parameters
per_page
string
Default: "20"

How many results to return.

page
string
Default: "1"

Which page of results to return.

Get Actions for Location

Retrieves the Actions for a specific Location

This path is versioned via the x-api-version header, which should be '9' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location to retrieve the Actions for.

query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

when.timestamp[.gt | .lte | .eq | .neq]
string <date-time>

Filter the response using action when.timestamp in comparison to this iso date value. Valid values of comparison are 'gt' (for greater than), 'lte', 'eq', 'neq'. The comparison defaults to 'eq' when not provided

type[.in | .nin]
string

Filter the response using action 'type' in comparison this list of comma separated types. Valid values of comparison are 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided

paymentType[.in | .nin]
string
Example: paymentType[.in | .nin]=CARDHOLDER_PRESENT,APPLEPAY

Filter transactions by payment type. Accepts comma-separated list of OrderPaymentType enum values. Valid values: CASH_AT_POS, CARD_AT_POS, GIFT_CARD_AT_POS, OTHER_AT_POS, APPLEPAY, GOOGLEPAY, CARD_ON_FILE, CARD_TENDERED, GIFT_CARD, CARDHOLDER_PRESENT, CASH, CARD, OTHER, APP, PAY_BY_BANK. Use 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '8': deprecated behaviour (default)
  • '9' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ]
}

Delete a Register

Delete a specific Register at a Location

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location.

registerId
required
string

The unique ID of the Register

Get a Register

Retrieves a specific Register at a Location

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location.

registerId
required
string

The unique ID of the Register at the Location.

Update a Register

Update a specific Register at a Location

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the Location.

registerId
required
string

The unique ID of the Register.

Get Location Tag Groups

Get location tag groups

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Upsert a Location Tag Group

Upsert a location tag group

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
id
required
string

The unique id of the tag group

title
required
string

The title of the tag group to be displayed to users

sort
number
matchAll
required
boolean

Set to true if filtering locations by multiple tags in this group should require all relevant tags to be present on the location. As opposed to requiring at least one tag to be present on the location

required
object

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "sort": 0,
  • "matchAll": true,
  • "tags": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "title": "string",
  • "sort": 0,
  • "matchAll": true,
  • "tags": {
    }
}

Delete a Tag Group

Remove a location tag group

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationTagGroupId
required
string

The unique ID of the location tag group to remove.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Create Delivery Boundaries for Location

Create one delivery boundary for a specific location.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the location to create the delivery boundary for.

Request Body schema: application/json
required
Polygon Boundary (object) or Circle Boundary (object) (Delivery Boundary)

Fields for creating and updating a Delivery Boundary

filter
required
string
Enum: "include" "exclude"

Location will only be available if delivery coordinates are within an include boundary AND outside of any exclude boundaries.

Responses

Request samples

Content type
application/json
{
  • "deliveryBoundary": {
    },
  • "filter": "include"
}

Response samples

Content type
application/json
{
  • "include": [
    ],
  • "exlude": [
    ]
}

Update Delivery Boundaries for Location

Update one delivery boundary for a specific location.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the location to update the delivery boundary for.

Request Body schema: application/json
required
Polygon Boundary (object) or Circle Boundary (object) (Delivery Boundary)

Fields for creating and updating a Delivery Boundary

filter
required
string
Enum: "include" "exclude"

Location will only be available if delivery coordinates are within an include boundary AND outside of any exclude boundaries.

Responses

Request samples

Content type
application/json
{
  • "deliveryBoundary": {
    },
  • "filter": "include"
}

Response samples

Content type
application/json
{
  • "include": [
    ],
  • "exlude": [
    ]
}

Delete Delivery Boundaries from Location

Delete one delivery boundary for a specific location.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the location to delete the delivery boundary from.

deliveryBoundaryId
required
string

The unique ID of the deliveryBoundary to delete.

Responses

Response samples

Content type
application/json
{
  • "include": [
    ],
  • "exlude": [ ]
}

Get Locations for Delivery

Retrieve the locations that are available for delivery for a given pair of co-ordinates.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
lat
required
number

Latitude of the delivery location.

long
required
number

Longitude of the delivery location.

include
Array of strings
Items Enum: "created" "updated" "state" "mainImageUrl" "alternativeOpeningHoursText" "buttons" "links" "description" "ordering" "VATnumber" "regions" "address" "tags" "zones"

Specify which optional fields to return in the response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Loyalty

Loyalty gives access to a user's loyalty account balance

Get Loyalty Balance

Gets the loyalty balance of the user

The loyalty provider used is the loyalty provider from the merchant settings, if a provider does not exist, or the user does not have a loyalty account Id, then this endpoint will throw an error.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
balanceId
string

A specific balance to get, if the loyalty provider supports multiple balances at once, this is not required if the provider only supports a single balance

Responses

Response samples

Content type
application/json
{
  • "balance": 0,
  • "type": "POINTS"
}

Notifications

Use the Notifications endpoints to send App notification messages to App users.

Get Notifications

Gets a paged list of push notification messages.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Create a Notification

Creates a push Notification Message, and schedules it for immediate delivery.

The destination can be specified as

  • a list of users, specified by their Ids
  • users that are members of segments, specified by a list of the segment Ids
  • users with locations set a favourites, specified by a list of the location Ids
  • all users of the app

Only one of the destination options can be set at a time; currently they cannot be combined.

The request will return immediately with a notification message _id. Poll the GET /notifications/:notificationId endpoint using the Id to track the result of the delivery.

This path is versioned via the x-api-version header, which should be '9' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1': not supported any longer
  • '2' or higher: current behaviour as described here

If missing, the default value is '1' which is no longer support by this endpoint. You must set the header to '2' or higher.

Request Body schema: application/json
title
string

The title of the notification message

message
required
string

The text of the notification message

imageUrl
string
object
buttonText
string

The text of the button

type
required
string
Value: "alert"

Reserved for future use.

value
required
string

Reserved for future use.

isProcessingMessage
required
boolean

Set this to false if the message is a marketing message, or true if it is a message that should be sent even if the user has opted out of receiving marketing. Misusing this flag could cause penalties under the GDPR regulations.

userIds
Array of strings

List of Ids of users to send the message to.

locationIds
Array of strings

List of Ids of locations. All users with those locations as a favourite will be sent the message.

segmentIds
Array of strings

List of Ids of segments. All the segment user members will be sent the message.

global
boolean

Set this to true to send the message to every user of the App.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "message": "string",
  • "imageUrl": "string",
  • "deepLink": {
    },
  • "buttonText": "string",
  • "type": "alert",
  • "value": "string",
  • "isProcessingMessage": true,
  • "userIds": [
    ],
  • "locationIds": [
    ],
  • "segmentIds": [
    ],
  • "global": true
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "title": "string",
  • "message": "string",
  • "imageUrl": "string",
  • "deepLink": {
    },
  • "buttonText": "string",
  • "type": "alert",
  • "value": "string",
  • "isProcessingMessage": true,
  • "userIds": [
    ],
  • "locationIds": [
    ],
  • "segmentIds": [
    ],
  • "global": true,
  • "createdAt": "string",
  • "completedAt": "string",
  • "status": "PENDING",
  • "sent": 0,
  • "failures": 0,
  • "skipped": 0,
  • "errorMessage": "string"
}

Get a Notification

Gets a push notification message by Id

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
notificationMessageId
required
string

The specific ID of the Notification Message to retrieve.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "title": "string",
  • "message": "string",
  • "imageUrl": "string",
  • "deepLink": {
    },
  • "buttonText": "string",
  • "type": "alert",
  • "value": "string",
  • "isProcessingMessage": true,
  • "userIds": [
    ],
  • "locationIds": [
    ],
  • "segmentIds": [
    ],
  • "global": true,
  • "createdAt": "string",
  • "completedAt": "string",
  • "status": "PENDING",
  • "sent": 0,
  • "failures": 0,
  • "skipped": 0,
  • "errorMessage": "string"
}

Get Notification Message Receipts

Gets a paged list of the user receipts for notifications.

User receipts are only retained for 45 days

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
notificationMessageId
required
string

The specific ID of the Notification Message to retrieve.

query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Create a Notification for a User

Creates a push Notification Message for a specific user, and schedules it for immediate delivery.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to create the Notifications for.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1': not supported any longer
  • '2' or higher: current behaviour as described here

If missing, the default value is '1' which is no longer support by this endpoint. You must set the header to '2' or higher.

Request Body schema: application/json
title
string

The title of the notification message

message
required
string

The text of the notification message

imageUrl
string
object
buttonText
string

The text of the button

type
required
string
Value: "alert"

Reserved for future use.

value
required
string

Reserved for future use.

isProcessingMessage
required
boolean

Set this to false if the message is a marketing message, or true if it is a message that should be sent even if the user has opted out of receiving marketing. Misusing this flag could cause penalties under the GDPR regulations.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "message": "string",
  • "imageUrl": "string",
  • "deepLink": {
    },
  • "buttonText": "string",
  • "type": "alert",
  • "value": "string",
  • "isProcessingMessage": true
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "title": "string",
  • "message": "string",
  • "imageUrl": "string",
  • "deepLink": {
    },
  • "buttonText": "string",
  • "type": "alert",
  • "value": "string",
  • "isProcessingMessage": true,
  • "userIds": [
    ],
  • "locationIds": [
    ],
  • "segmentIds": [
    ],
  • "global": true,
  • "createdAt": "string",
  • "completedAt": "string",
  • "status": "PENDING",
  • "sent": 0,
  • "failures": 0,
  • "skipped": 0,
  • "errorMessage": "string"
}

Get a User's Notification Message Receipts

Gets a paged list of the receipts for Notification Message for a specific User.

User receipts are only retained for 45 days

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The User ID to use for retrieving the Notification Message Receipts.

query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1': not supported any longer
  • '2' or higher: current behaviour as described here

If missing, the default value is '1' which is no longer support by this endpoint. You must set the header to '2' or higher.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Create a Notification by Location

Creates a push Notification Message for all the users with this Location set as a favourite

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the Location to create the Notifications for.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1': not supported any longer
  • '2' or higher: current behaviour as described here

If missing, the default value is '1' which is no longer support by this endpoint. You must set the header to '2' or higher.

Request Body schema: application/json
title
string

The title of the notification message

message
required
string

The text of the notification message

imageUrl
string
object
buttonText
string

The text of the button

type
required
string
Value: "alert"

Reserved for future use.

value
required
string

Reserved for future use.

isProcessingMessage
required
boolean

Set this to false if the message is a marketing message, or true if it is a message that should be sent even if the user has opted out of receiving marketing. Misusing this flag could cause penalties under the GDPR regulations.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "message": "string",
  • "imageUrl": "string",
  • "deepLink": {
    },
  • "buttonText": "string",
  • "type": "alert",
  • "value": "string",
  • "isProcessingMessage": true
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "title": "string",
  • "message": "string",
  • "imageUrl": "string",
  • "deepLink": {
    },
  • "buttonText": "string",
  • "type": "alert",
  • "value": "string",
  • "isProcessingMessage": true,
  • "userIds": [
    ],
  • "locationIds": [
    ],
  • "segmentIds": [
    ],
  • "global": true,
  • "createdAt": "string",
  • "completedAt": "string",
  • "status": "PENDING",
  • "sent": 0,
  • "failures": 0,
  • "skipped": 0,
  • "errorMessage": "string"
}

Create a Notification by Segment

Creates a push Notification Message for all the users who are members of this segment.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the Segment to create the Notifications for.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1': not supported any longer
  • '2' or higher: current behaviour as described here

If missing, the default value is '1' which is no longer support by this endpoint. You must set the header to '2' or higher.

Request Body schema: application/json
title
string

The title of the notification message

message
required
string

The text of the notification message

imageUrl
string
object
buttonText
string

The text of the button

type
required
string
Value: "alert"

Reserved for future use.

value
required
string

Reserved for future use.

isProcessingMessage
required
boolean

Set this to false if the message is a marketing message, or true if it is a message that should be sent even if the user has opted out of receiving marketing. Misusing this flag could cause penalties under the GDPR regulations.

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "message": "string",
  • "imageUrl": "string",
  • "deepLink": {
    },
  • "buttonText": "string",
  • "type": "alert",
  • "value": "string",
  • "isProcessingMessage": true
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "title": "string",
  • "message": "string",
  • "imageUrl": "string",
  • "deepLink": {
    },
  • "buttonText": "string",
  • "type": "alert",
  • "value": "string",
  • "isProcessingMessage": true,
  • "userIds": [
    ],
  • "locationIds": [
    ],
  • "segmentIds": [
    ],
  • "global": true,
  • "createdAt": "string",
  • "completedAt": "string",
  • "status": "PENDING",
  • "sent": 0,
  • "failures": 0,
  • "skipped": 0,
  • "errorMessage": "string"
}

Operations

Bulk operations on users, segments, etc

Get Operations

Gets a paged list of operations.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    },
  • "links": {
    }
}

Get an Operation

Retrieves a specific operation

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
operationId
required
string

The ID of the Operation to retrieve.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "namespace": "string",
  • "entityId": "string",
  • "nonce": "string",
  • "name": "string",
  • "status": "DONE",
  • "metadata": null,
  • "result": null,
  • "error": null,
  • "isRetryable": true,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "endedAt": "string"
}

Get Sub Operations

Gets a paged list of sub operations associated with an operation id.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    },
  • "links": {
    }
}

Payment Cards

Manage details of users' payment cards in tokenized form

Get all Payment Cards

If the user is an admin user, this call gets all the payment cards for the tenant. CAUTION this call is not currently paged and so could give a huge result.

If the user is not an admin user, this call gets all the cards for the current user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
{
  • "cards": [
    ]
}

Add a Payment Card

Add a tokenized payment card for the authenticated user. Or, add a card via a one use token. Or, request a token to add a card for BRAINTREE.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
One of
cardType
string
Enum: "STRIPE" "JUDOPAY" "BRAINTREE" "SQUARE"

Payment gateway type

methodType
string
Default: "CARD"
Enum: "CARD" "PAYPAL"
consumerId
string

Consumer Id (for JUDOPAY)

consumerReference
string

consumerReference (for JUDOPAY)

gatewayId
string

The tokenized card id generated by the payment gateway. If this is omitted, the call will attempt to retrieve a token and return it

last4
string

The last 4 digits of the payment card.

expires
string

The month and year the card expires, format MMYY

token
string

An optional client-generated token encapsulating 3DS information.

Responses

Request samples

Content type
application/json
Example
{
  • "cardType": "STRIPE",
  • "methodType": "CARD",
  • "consumerId": "string",
  • "consumerReference": "string",
  • "gatewayId": "string",
  • "last4": "string",
  • "expires": "string",
  • "token": "string"
}

Response samples

Content type
application/json
Example
{
  • "_id": "string",
  • "created": "string",
  • "updated": "string",
  • "userId": "string",
  • "cardType": "STRIPE",
  • "gatewayId": "string",
  • "cardId": "string",
  • "methodType": "CARD",
  • "type": "string",
  • "email": "string",
  • "last4": "string",
  • "expires": "string",
  • "autoTopUp": {
    }
}

Pre-Create a Payment Card

Perform the precreation setup with the payment provider to support adding a new payment card to the user.

This is required for the following PaymentProviders: Stripe: To create a SetupIntent, returning the data required to Create a Card in Stripe.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
{
  • "stripe": {
    }
}

Get a Payment Card

Retrieve a specific card for the authenticated user

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
cardId
required
string

The unique Id of the payment card to retrieve

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created": "string",
  • "updated": "string",
  • "userId": "string",
  • "cardType": "STRIPE",
  • "gatewayId": "string",
  • "cardId": "string",
  • "methodType": "CARD",
  • "type": "string",
  • "email": "string",
  • "last4": "string",
  • "expires": "string",
  • "autoTopUp": {
    }
}

Update a Payment Card

Updates an existing payment ../schemas/card.json

Only the deprecated auto topup fields can be changed.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
cardId
required
string

The unique Id of the payment card to update

Request Body schema: application/json
object

User's auto balance topup settings. These fields are deprecated

enabled
boolean
amount
number
Default: 10

The topup amount

trigger
number
Default: 10

The balance amount below which a topup is triggered

Responses

Request samples

Content type
application/json
{
  • "autoTopUp": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created": "string",
  • "updated": "string",
  • "userId": "string",
  • "cardType": "STRIPE",
  • "gatewayId": "string",
  • "cardId": "string",
  • "methodType": "CARD",
  • "type": "string",
  • "email": "string",
  • "last4": "string",
  • "expires": "string",
  • "autoTopUp": {
    }
}

Delete a Payment Card

Removes a payment card specifid by Id from the database and the payment gateway

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
cardId
required
string

The unique Id of the card to remove

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Get Payment Cards for a User

Retrieves the payment cards for a specific user. Only admin users can retrieve cards for other users.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Cards for.

Responses

Response samples

Content type
application/json
{
  • "cards": [
    ]
}

Get the Active Payment Card for a User

Retrieves the payment cards for a specific user. Only admin users can retrieve cards for other users.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the active payment card

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created": "string",
  • "updated": "string",
  • "userId": "string",
  • "cardType": "STRIPE",
  • "gatewayId": "string",
  • "cardId": "string",
  • "methodType": "CARD",
  • "type": "string",
  • "email": "string",
  • "last4": "string",
  • "expires": "string",
  • "autoTopUp": {
    }
}

Perks

Use the Perk endpoints to create, retrieve and edit perks.

Perks and awards, while closely related, are not one and the same thing. A perk describes the parameters of the overall Rewards Programme (e.g. ‘Stamp Card Loyalty’), whereas an award is a user’s instance of a perk (e.g. ‘Andrew’s Stamp Cards’). An award is derived from a perk and captures a single user’s relationship with that perk.

An award is created for a user by ‘granting’ a perk to them. A perk can be granted in any one of the following three ways:

  • manually via an appropriate call to the Pepper API,
  • automatically as the result of a set of rules being matched,
  • automatically if the isGlobal property is true.

If a user already has an award when a perk is granted to them, the appropriate properties of the award are updated accordingly (eg by updating points.available).

There are several types of perk:

STAMP_CARD perks reward a user with a free item when they have earned enough 'stamps' via qualifying purchases.

PSEUDO_CURRENCY perks are a points based perk. They can be redeemed for money off an order using a fixed point to money ratio: for example: 1 penny off per point redeemed.

AD_HOC perks are rewards that can be granted to users on an ad hoc basis for promotional purposes - for example, a free Gin and Tonic on the user's birthday.

CLUB and LEVEL perks reward a User whilst they are members of a specific Audience. The act of being added to, or removed from, an Audience will grant or revoke the Perk as appropriate. Examples of Membership based Perks include:

  • Club membership
  • Corporate Discount
  • VIP Customers (i.e. non-level based activity driven rewards)

Additionally, a ‘Level Based Loyalty’ programme (e.g. Bronze, Silver, Gold) can be modelled using the Membership scheme. If the isTier property of a Perk is set to true, then it will be assumed to be a tier in a Level Based Loyalty programme (in conjunction with other Perks with the value set). The priority of the Perk determines which should be presented if the User is in multiple tiers. e.g. if the User has each of the Bronze, Silver and Gold Perks then the Gold Perk will be the only one viable (assuming of course it has the highest priority).

Create a Perk

Creates a perk for a tenant.

A Perk defines an award that can be granted to or earned by a user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
template
required
string
Enum: "STAMP_CARD" "LEVEL" "AD_HOC" "PSEUDO_CURRENCY" "CLUB"

The discount model used by the perk

title
required
string

The name of the perk

internalTitle
string

A more convenient, business-friendly title for easy reference in the console. Use this to distinguish between many perks with similar names.

terms
required
string

The terms and conditions of an award of this perk type

priority
required
number

For LEVEL type perk awards, controls which award is active (the highest priority) and suppresses any others. Also used to order the awards in the app awards carousel.

redemptionMethod
any
Enum: "AUTO" "CODE_PDF417" "CODE_QR" "VOUCHER"

How an award of this perk is communicated to the POS.

  • AUTO - Can be redeemed via integration with the POS and without the need for the User to show the Award in the app.
  • CODE_PDF417 - Will be displayed in the App as a PDF 417 format of barcode.
  • CODE_QR - Will be displayed in the App as a QR code.
  • VOUCHER - Will be displayed in the App as a plain text string - e.g. '1234567890' ready for manual POS entry.
auto
required
boolean

If true, the pos automatically redeems the awards of this perk for qualifying baskets

token
string

The code that the POS uses to match to a discount or adjustment known by the POS, and apply to a basket if appropriate. This will be the value that is displayed according to redemptionMethod above.

maximumPointCashValue
number

The maximum absolute discount that can be applied as the result of redeeming an award of this perk

locationIds
Array of strings
required
object

Defines how points are earned and redeemed against an award

object

Used to describe rules around how a perk discount is calculated

object

Controls when a perk is redeemable based on the time and date

object

What conditions must be met in the basket for an award to be redeemable

required
object

Used by apps to display the award in an award carousel

isDonatable
boolean
isGlobal
required
boolean

If true, all users will be granted an award of this perk

isTier
boolean
enabled
boolean

If true, the perk is active and can be earned and redeemed

physicalStampsEnabled
boolean

If true, this perk supports physical stamp functionality

Responses

Request samples

Content type
application/json
{
  • "template": "STAMP_CARD",
  • "title": "string",
  • "internalTitle": "string",
  • "terms": "string",
  • "priority": 0,
  • "redemptionMethod": "AUTO",
  • "auto": true,
  • "token": "string",
  • "maximumPointCashValue": 0,
  • "locationIds": [
    ],
  • "points": {
    },
  • "discount": {
    },
  • "dateTimeRestriction": {
    },
  • "basketQualification": {
    },
  • "visualisation": {
    },
  • "isDonatable": true,
  • "isGlobal": true,
  • "isTier": true,
  • "enabled": true,
  • "physicalStampsEnabled": true
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "template": "STAMP_CARD",
  • "title": "string",
  • "internalTitle": "string",
  • "terms": "string",
  • "priority": 0,
  • "redemptionMethod": "AUTO",
  • "auto": true,
  • "token": "string",
  • "maximumPointCashValue": 0,
  • "locationIds": [
    ],
  • "points": {
    },
  • "discount": {
    },
  • "dateTimeRestriction": {
    },
  • "basketQualification": {
    },
  • "visualisation": {
    },
  • "isDonatable": true,
  • "isGlobal": true,
  • "isTier": true,
  • "enabled": true,
  • "physicalStampsEnabled": true
}

Get all Perks

Retrieves all the perks for a tenant.

A Perk defines an award that can be granted to or earned by a User.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '4': deprecated behaviour (default)
  • '5' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Get a Perk

Retrieves a perk for a tenant by Id

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The Id of the perk to retrieve.

query Parameters
include
string

Specify which additional optional fields to return in the response. Optional fields are: awardCount

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "template": "STAMP_CARD",
  • "title": "string",
  • "internalTitle": "string",
  • "terms": "string",
  • "priority": 0,
  • "redemptionMethod": "AUTO",
  • "auto": true,
  • "token": "string",
  • "maximumPointCashValue": 0,
  • "locationIds": [
    ],
  • "points": {
    },
  • "discount": {
    },
  • "dateTimeRestriction": {
    },
  • "basketQualification": {
    },
  • "visualisation": {
    },
  • "isDonatable": true,
  • "isGlobal": true,
  • "isTier": true,
  • "enabled": true,
  • "physicalStampsEnabled": true
}

Delete a Perk Deprecated

Removes a specific perk for a tenant

Note: this endpoint affects the old Perks schema and will be changed in a future version. Use the endpoint DELETE /pointperks/:perkId in the meantime

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The unique Id of the perk to remove.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Update a Perk Deprecated

Update a perk for a tenant.

Note: this endpoint affects the old Perks schema and will be changed in a future version. Use the endpoint PUT /pointperks/:perkId in the meantime.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The Id of the perk to update.

Request Body schema: application/json
template
string
Enum: "STAMP_CARD" "LEVEL" "AD_HOC" "PSEUDO_CURRENCY" "CLUB"

The discount model used by the perk

title
string

The name of the perk

internalTitle
string

A more convenient, business-friendly title for easy reference in the console. Use this to distinguish between many perks with similar names.

terms
string

The terms and conditions of an award of this perk type

priority
number

For LEVEL type perk awards, controls which award is active (the highest priority) and suppresses any others. Also used to order the awards in the app awards carousel.

redemptionMethod
any
Enum: "AUTO" "CODE_PDF417" "CODE_QR" "VOUCHER"

How an award of this perk is communicated to the POS.

  • AUTO - Can be redeemed via integration with the POS and without the need for the User to show the Award in the app.
  • CODE_PDF417 - Will be displayed in the App as a PDF 417 format of barcode.
  • CODE_QR - Will be displayed in the App as a QR code.
  • VOUCHER - Will be displayed in the App as a plain text string - e.g. '1234567890' ready for manual POS entry.
auto
boolean

If true, the pos automatically redeems the awards of this perk for qualifying baskets

token
string

The code that the POS uses to match to a discount or adjustment known by the POS, and apply to a basket if appropriate. This will be the value that is displayed according to redemptionMethod above.

maximumPointCashValue
number

The maximum absolute discount that can be applied as the result of redeeming an award of this perk

locationIds
Array of strings
object

Defines how points are earned and redeemed against an award

object

Used to describe rules around how a perk discount is calculated

object

Controls when a perk is redeemable based on the time and date

object

What conditions must be met in the basket for an award to be redeemable

object

Used by apps to display the award in an award carousel

isDonatable
boolean
isGlobal
boolean

If true, all users will be granted an award of this perk

isTier
boolean
enabled
boolean

If true, the perk is active and can be earned and redeemed

physicalStampsEnabled
boolean

If true, this perk supports physical stamp functionality

Responses

Request samples

Content type
application/json
{
  • "template": "STAMP_CARD",
  • "title": "string",
  • "internalTitle": "string",
  • "terms": "string",
  • "priority": 0,
  • "redemptionMethod": "AUTO",
  • "auto": true,
  • "token": "string",
  • "maximumPointCashValue": 0,
  • "locationIds": [
    ],
  • "points": {
    },
  • "discount": {
    },
  • "dateTimeRestriction": {
    },
  • "basketQualification": {
    },
  • "visualisation": {
    },
  • "isDonatable": true,
  • "isGlobal": true,
  • "isTier": true,
  • "enabled": true,
  • "physicalStampsEnabled": true
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Delete a Perk (PointPerk)

Removes a specific perk for a tenant.

This endpoint will be deprecated in an upcoming release and be replaced by DELETE /perks/:perkId

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The unique Id of the perk to remove.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Update a Perk (PointPerk)

Update an existing perk for a tenant.

This endpoint will be deprecated in an upcoming release and be replaced by PUT /perks/:perkId

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The Id of the perk to update.

Request Body schema: application/json
template
string
Enum: "STAMP_CARD" "LEVEL" "AD_HOC" "PSEUDO_CURRENCY" "CLUB"

The discount model used by the perk

title
string

The name of the perk

internalTitle
string

A more convenient, business-friendly title for easy reference in the console. Use this to distinguish between many perks with similar names.

terms
string

The terms and conditions of an award of this perk type

priority
number

For LEVEL type perk awards, controls which award is active (the highest priority) and suppresses any others. Also used to order the awards in the app awards carousel.

redemptionMethod
any
Enum: "AUTO" "CODE_PDF417" "CODE_QR" "VOUCHER"

How an award of this perk is communicated to the POS.

  • AUTO - Can be redeemed via integration with the POS and without the need for the User to show the Award in the app.
  • CODE_PDF417 - Will be displayed in the App as a PDF 417 format of barcode.
  • CODE_QR - Will be displayed in the App as a QR code.
  • VOUCHER - Will be displayed in the App as a plain text string - e.g. '1234567890' ready for manual POS entry.
auto
boolean

If true, the pos automatically redeems the awards of this perk for qualifying baskets

token
string

The code that the POS uses to match to a discount or adjustment known by the POS, and apply to a basket if appropriate. This will be the value that is displayed according to redemptionMethod above.

maximumPointCashValue
number

The maximum absolute discount that can be applied as the result of redeeming an award of this perk

locationIds
Array of strings
object

Defines how points are earned and redeemed against an award

object

Used to describe rules around how a perk discount is calculated

object

Controls when a perk is redeemable based on the time and date

object

What conditions must be met in the basket for an award to be redeemable

object

Used by apps to display the award in an award carousel

isDonatable
boolean
isGlobal
boolean

If true, all users will be granted an award of this perk

isTier
boolean
enabled
boolean

If true, the perk is active and can be earned and redeemed

physicalStampsEnabled
boolean

If true, this perk supports physical stamp functionality

Responses

Request samples

Content type
application/json
{
  • "template": "STAMP_CARD",
  • "title": "string",
  • "internalTitle": "string",
  • "terms": "string",
  • "priority": 0,
  • "redemptionMethod": "AUTO",
  • "auto": true,
  • "token": "string",
  • "maximumPointCashValue": 0,
  • "locationIds": [
    ],
  • "points": {
    },
  • "discount": {
    },
  • "dateTimeRestriction": {
    },
  • "basketQualification": {
    },
  • "visualisation": {
    },
  • "isDonatable": true,
  • "isGlobal": true,
  • "isTier": true,
  • "enabled": true,
  • "physicalStampsEnabled": true
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "template": "STAMP_CARD",
  • "title": "string",
  • "internalTitle": "string",
  • "terms": "string",
  • "priority": 0,
  • "redemptionMethod": "AUTO",
  • "auto": true,
  • "token": "string",
  • "maximumPointCashValue": 0,
  • "locationIds": [
    ],
  • "points": {
    },
  • "discount": {
    },
  • "dateTimeRestriction": {
    },
  • "basketQualification": {
    },
  • "visualisation": {
    },
  • "isDonatable": true,
  • "isGlobal": true,
  • "isTier": true,
  • "enabled": true,
  • "physicalStampsEnabled": true
}

Award a Perk Deprecated

Grant an award based on the specified perk to a user or segment.

Note: this endpoint returns the old Perks schema and will be changed in a future version. Use the endpoint POST /pointperks/:perkId/awards in the meantime.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The Id of the perk to award.

Request Body schema: application/json
userId
required
string

Responses

Request samples

Content type
application/json
{
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Award a Perk (PointPerk)

Grant an award based on the specified perk to a user.

Note: this endpoint will be deprecated in an upcoming release and be replaced by the endpoint POST /perks/:perkId/awards.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The Id of the perk to award.

Request Body schema: application/json
userId
required
string
points
number

The value to award the user. If not specified, the default value of the perk will be used.

locationId
string

The id of the location associated with this grant, if any

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "points": 0,
  • "locationId": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "template": "STAMP_CARD",
  • "title": "string",
  • "terms": "string",
  • "priority": 0,
  • "redemptionMethod": "AUTO",
  • "auto": true,
  • "token": "string",
  • "maximumPointCashValue": 0,
  • "discount": {
    },
  • "dateTimeRestriction": {
    },
  • "basketQualification": {
    },
  • "visualisation": {
    },
  • "isDonatable": true,
  • "isGlobal": true,
  • "isTier": true,
  • "updatedAt": "string",
  • "locationIds": [
    ],
  • "points": {
    }
}

Referrals

A user sends a referral to a introduce a new user to the App. When the new user signs up, they can claim the code and both they and the referrer will receive a configurable award

Create a Referral

Creates a Referral with a unique code for the authenticated User.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "code": 0,
  • "refererId": "string",
  • "refereeId": "string",
  • "expires": "string",
  • "created": "string",
  • "state": "CREATED"
}

Claim a Referral

Claims a Referral code for the authenticated User.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
code
required
string

The referral code to claim.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "code": 0,
  • "refererId": "string",
  • "refereeId": "string",
  • "expires": "string",
  • "created": "string",
  • "state": "CREATED"
}

Rules

A rule describes

  • an effect to be triggered
  • when a new event (eg ORDER_COMPLETED) event matches the rule's conditions

Rules are used for example to add users to segments (audiences) or automatically grant awards

Create a Rule

Create a rule for a tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
object
matchType
required
string
Enum: "TYPE" "TIME"
required
Array of strings subjects (object) or numbers subjects (object) or booleans subjects (object) or basket subjects (object) or payments subjects (object) or extended tests (object) non-empty unique
required
segment (object) or pointPerk (object) or pointAward (object) or credential (object) or scheduledTask (object) (Impact)
active
boolean

Responses

Request samples

Content type
application/json
{
  • "occurrences": {
    },
  • "matchType": "TYPE",
  • "conditions": [
    ],
  • "effect": {
    },
  • "active": true
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "created": "string",
  • "updated": "string",
  • "occurrences": {
    },
  • "matchType": "TYPE",
  • "conditions": [
    ],
  • "effect": {
    },
  • "active": true
}

Get All Rules

Retrieve all the rules for a tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Validate All Rules

Checks all rules for a tenant and reports any issues

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
{
  • "validation": {
    },
  • "logic": [
    ]
}

Get a Rule

Retrieves a rule for a tenant by Id

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
ruleId
required
string

The Id of the rule to retrieve.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "created": "string",
  • "updated": "string",
  • "occurrences": {
    },
  • "matchType": "TYPE",
  • "conditions": [
    ],
  • "effect": {
    },
  • "active": true
}

Delete a Rule

Removes a specific rule for a tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
perkId
required
string

The unique Id of the rule to remove.

query Parameters
includeEffect
boolean
Default: false

If true, the deletion will include effects related to the rule, such as removing pending ScheduledTasks.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Update a Rule

Update a rule for a tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
ruleId
required
string

The Id of the rule to update.

query Parameters
includeEffect
boolean
Default: false

If true, the update will include effects related to the rule, such as removing pending ScheduledTasks.

Request Body schema: application/json
object
matchType
required
string
Enum: "TYPE" "TIME"
required
Array of strings subjects (object) or numbers subjects (object) or booleans subjects (object) or basket subjects (object) or payments subjects (object) or extended tests (object) non-empty unique
required
segment (object) or pointPerk (object) or pointAward (object) or credential (object) or scheduledTask (object) (Impact)
active
boolean

Responses

Request samples

Content type
application/json
{
  • "occurrences": {
    },
  • "matchType": "TYPE",
  • "conditions": [
    ],
  • "effect": {
    },
  • "active": true
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Scheduled Tasks

Scheduled tasks are used to execute some action at a specific time in the future.

Create a Scheduled Task

Create a scheduled task for a tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
Any of
type
string
Value: "CREATE_PUSH_NOTIFICATION"
object

Responses

Request samples

Content type
application/json
Example
{
  • "type": "CREATE_PUSH_NOTIFICATION",
  • "parameters": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "CREATE_PUSH_NOTIFICATION",
  • "parameters": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "locationId": "string",
  • "status": "DRAFT",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "attempts": 0,
  • "queuedAt": "string",
  • "idempotencyKey": "string",
  • "error": "string",
  • "source": {
    }
}

Get All Scheduled Tasks

Retrieve all the scheduled tasks for a tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a Scheduled Task

Retrieves a specific scheduled task for a tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
taskId
required
string

The ID of the Scheduled Task to retrieve.

Responses

Response samples

Content type
application/json
Example
{
  • "type": "CREATE_PUSH_NOTIFICATION",
  • "parameters": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "locationId": "string",
  • "status": "DRAFT",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "attempts": 0,
  • "queuedAt": "string",
  • "idempotencyKey": "string",
  • "error": "string",
  • "source": {
    }
}

Delete a Scheduled Task

Delete a specific Scheduled Task for a Tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
taskId
required
string

The unique ID of the Scheduled Task to delete

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Update a Scheduled Task

Update an existing Scheduled Task for a Tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
taskId
required
string

The ID of the Scheduled Task to update.

Request Body schema: application/json
Any of
type
string
Value: "CREATE_PUSH_NOTIFICATION"
object

Responses

Request samples

Content type
application/json
Example
{
  • "type": "CREATE_PUSH_NOTIFICATION",
  • "parameters": {
    }
}

Response samples

Content type
application/json
Example
{
  • "type": "CREATE_PUSH_NOTIFICATION",
  • "parameters": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "locationId": "string",
  • "status": "DRAFT",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "attempts": 0,
  • "queuedAt": "string",
  • "idempotencyKey": "string",
  • "error": "string",
  • "source": {
    }
}

Segments

A segment is a group of users that can be used to drive different activities around marketing campaigns. A segment is also known as an audience.

The merchant can define rules for adding and removing users to a segment, send notifications to a segment, define different content to display to a segment, and give different loyalty awards to a segment.

Segment members are managed via explicit requests to add and remove users, or automatically via rules.

Users are also automatically removed (expired) according to the segment type and the expiryHorizon:

  • SCHEDULED = Drop a user when the expiryHorizon time has elapsed since they were added.
  • ROLLING = Drop a user when the expiryHorizon time has elapsed since they were added; if any action fires during the period that would add the user to the segment, then reset the expiry time.
  • PERSISTENT = Never expire membership

Expiry checks run once a day, so using expiry values less than 1 day will only be executed the day after.

Create a Segment

Creates a Segment for a Tenant.

This path is versioned via the x-api-version header, which should be '9' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '8': deprecated behaviour (default)
  • '9' or higher: current behaviour as described here
Request Body schema: application/json
title
required
string

Name of the segment

description
string

Segment description

type
required
any
Enum: "PERSISTENT" "ROLLING" "SCHEDULED"

Scheme for managing expiring user segment membership

expiryHorizon
number

Depends on type value - sets the duration in seconds that users should remain as a segment member

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "type": "PERSISTENT",
  • "expiryHorizon": 0
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "created": "string",
  • "updated": "string",
  • "title": "string",
  • "description": "string",
  • "type": "PERSISTENT",
  • "expiryHorizon": 0
}

Get all Segments

Retrieves all the Segments for a Tenant. Extra fields can be specified by using the include parameter. This path is versioned via the x-api-version header, which should be '12' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

include
string

A comma separated list of extra fields to return. Possible fields are: count (current user count), metrics (list of calculated metric values)

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '11': deprecated behaviour (default)
  • '12' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Get a Segment

Retrieves a specific Segment for a Tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
segmentId
required
string

The ID of the Segment to retrieve.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1', '2': deprecated behaviour (default)
  • '3' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "created": "string",
  • "updated": "string",
  • "title": "string",
  • "description": "string",
  • "type": "PERSISTENT",
  • "expiryHorizon": 0
}

Delete a Segment

Delete a specific Segment for a Tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
segmentId
required
string

The unique ID of the Segment to Delete

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1', '2': deprecated behaviour (default)
  • '3' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Update a Segment

Update an existing Segment for a Tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
segmentId
required
string

The ID of the Segment to update.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1', '2': deprecated behaviour (default)
  • '3' or higher: current behaviour as described here
Request Body schema: application/json
title
string

Name of the segment

description
string

Segment description

type
any
Enum: "PERSISTENT" "ROLLING" "SCHEDULED"

Scheme for managing expiring user segment membership

expiryHorizon
number

Depends on type value - sets the duration in seconds that users should remain as a segment member

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "type": "PERSISTENT",
  • "expiryHorizon": 0
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "created": "string",
  • "updated": "string",
  • "title": "string",
  • "description": "string",
  • "type": "PERSISTENT",
  • "expiryHorizon": 0
}

Add Users to a Segment

Add a list of user Ids to the Segment.

The maximum users you can add at a time is 100.

It is safe to add users who are already a member, but note it will reset their expiry time for ROLLING segments.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
segmentId
required
string

The ID of the Segment to add users to

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1', '2': deprecated behaviour (default)
  • '3' or higher: current behaviour as described here
Request Body schema: application/json
Array
string

user Id

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "added": 0
}

Get Segment Users

Fetch a paged list of users in the segment. The request can be optionaly expanded with extra user fields.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
segmentId
required
string

The Id of the Segment

query Parameters
expand
string

Optional list of extra user fields to be returned in addition to the User Id. Eg expand=fullName,state

limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1', '2': deprecated behaviour (default)
  • '3' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Remove Users from a Segment

Remove a list of user Ids from the Segment.

The maximum users you can remove at a time is 100.

It is safe to try and remove users who are not in the segment.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
segmentId
required
string

The ID of the Segment to add users to

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1', '2': deprecated behaviour (default)
  • '3' or higher: current behaviour as described here
Request Body schema: application/json
Array
string

user Id

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
application/json
{
  • "removed": 0
}

Start Bulk Segment User Import

Upload a file of users and add them to a segment if not already in the segment. If they are already in the segment, then reset their expiry according to the segment type and expiryDate parameter.

The response is an operation resource that can be polled in order to monitor progress. When complete, the operation will contain a result.href field providing a link to download a file of results.

Note: no events are emitted as part of this bulk import action.

Supported import file formats:

user_id
60f7e53e944a60af2caa9977
60f7e55550f30ab39776b834
Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
segmentId
required
string

The ID of the segment to add the users to.

query Parameters
expiryDate
string

An ISO 8061 date string. Added users will have this expiryDate set for SCHEDULED or ROLLING segment types. Existing users will have their expiryDate reset (ROLLING segment only).

dryRun
string

Set dryRun to false in order to perform the import. Otherwise, the import file will be processed to check for errors, but no users will be added.

header Parameters
x-pepper-req-nonce
string

This call requires a nonce in this header to prevent duplicate processing of calls. The nonce value represents an individual call. It should be set to a guid. Each new call should have a new guid. In the rare occasion you want to repeat a call, use the original guid value.

Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "namespace": "string",
  • "entityId": "string",
  • "nonce": "string",
  • "name": "string",
  • "status": "DONE",
  • "result": {
    },
  • "error": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "endedAt": "string"
}

Get Bulk Segment User Import Result

Download a file of segment user import results.

The full path including fileId is retrieved from the import operation's href.

Example Result File:

user_id,result,error
60f7e53e944a60af2caa9977,ok,
60f7e55550f30ab39776b834,exists,
60f7ef021a12d8ddf3ed8a24,fail,user not found
Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
fileId
required
string

The ID of the file to download.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Grant Perk to Segment Users

Grants a perk to all users in a segment who don't already have it.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
segmentId
required
string

The ID of the Segment used to grant the perk

header Parameters
x-pepper-req-nonce
string

This call requires a nonce in this header to prevent duplicate processing of calls. The nonce value represents an individual call. It should be set to a guid. Each new call should have a new guid. In the rare occasion you want to repeat a call, use the original guid value.

Request Body schema: application/json
perkId
string

Id of the perk to award

points
string

Amount of points to award

Responses

Request samples

Content type
application/json
{
  • "perkId": "string",
  • "points": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "namespace": "string",
  • "entityId": "string",
  • "nonce": "string",
  • "name": "string",
  • "status": "DONE",
  • "result": {
    },
  • "error": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "endedAt": "string"
}

Get a User's Segments

This endpoint is deprecated. Use GET /users/:userId?include=segmentIds or GET /users/:userId?include=segmentsinstead

Retrieve the Segments that the user is in.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The Id of the User

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stamps

Use the stamps endpoints to create, retrieve and edit Pepper Solo stamps details.

Gets the list of all the stamps for the tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Creates stamps for the tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
Array
locationId
required
string^[0-9a-fA-F]{24}$

The id of the Location that the stamp belongs to

stampId
required
string

The Snowshoe ID of the stamp

required
object

The effects enabled for this stamp

imprints
Array of numbers[ items[ items = 2 items ] ]

Array of imprints for this stamp

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
null

Gets a specific stamp for the tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
id
required
string

Pepper id of the stamp to retrieve

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "locationId": "string",
  • "stampId": "string",
  • "effects": {
    }
}

Update a single stamp for a tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
id
required
string

Pepper id of the stamp to update

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "locationId": "string",
  • "stampId": "string",
  • "effects": {
    }
}

Delete a single stamp for a tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
id
required
string

Pepper id of the stamp to delete

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "locationId": "string",
  • "stampId": "string",
  • "effects": {
    }
}

Create a Stamp Nonce

Creates a new nonce that expires after 120 seconds as well as the public key to encrypt a stamp impression and the nonce with.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
{
  • "nonce": "string",
  • "key": "string"
}

Validate and process a stamp impression

Validates a stamp impression encrypted with the nonce and public key and processes the effect of the stamp

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
impression
string

Encrypted JSON string containing co-ordinates of the impression of the stamp on phone as well as the one time nonce retrieved by hitting the create nonce endpoint

object

The intended effect of imprinting the stamp

Responses

Request samples

Content type
application/json
{
  • "impression": "string",
  • "effect": {
    }
}

Response samples

Content type
application/json
{
  • "result": {
    }
}

Update the imprint/fingerprint for a specific stamp

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
id
required
string

Pepper id of the stamp to update imprint for

Request Body schema: application/json
imprints
Array of numbers[ items[ items = 2 items ] ]

Array of imprints for this stamp

Responses

Request samples

Content type
application/json
{
  • "imprints": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "locationId": "string",
  • "stampId": "string",
  • "effects": {
    }
}

Users

Use the users endpoints to create, retrieve and edit a merchant's user details.

Lookup Users

Gets the users specified in the request body. Useful for retrieving a large batch of users.

The response is paged. Use limit and startKey to control the page returned.

Optional User fields favouriteLocations, favouriteProducts, extended, points are omitted from the response by default. Specify them in the include parameter to have them included.

Extra fields segmentIds, credentials and checkin are also optional. Specify them in include to have them included.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
sort
string

The names of the fields to sort the results by, in decreasing order of precendence. Allowed values are updatedAt, created. Separate each field by a comma. Prepend the field name with - sign to sort that field in descending order.

include
string

Specify which optional fields to return in the response. Optional fields are: favouriteLocations, favouriteProducts, extended, points, credentials, checkin and segmentIds

limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

Request Body schema: application/json
userIds
required
Array of strings

The ids of the users to retrieve

Responses

Request samples

Content type
application/json
{
  • "userIds": [
    ]
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Get Users

Gets all the users in the system for a Tenant.

The response is paged. Use limit and startKey to control the page returned.

Search terms supported are name and updatedAfter.

Optional User fields favouriteLocations, favouriteProducts, extended, points are omitted from the response by default. Specify them in the include parameter to have them included.

Extra fields segmentIds, credentials and checkin are also optional. Specify them in include to have them included.

This path is versioned via the x-api-version header, which should be '9' or higher. When x-api-version header is not present, the legacy resource is returned.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
name
string

Filter the request by user full names matching this value (minimum 3 characters, case insensitive).

updatedAfter
string

Filter the request by for users changed or added after this value. Use ISO date format.

createdAfter
string

Filter the request by for users created after this value. Use ISO date format.

credentialId
string

Filter the request by a user's credential i.e email address or phone number

role
string

Filter the request by for users with the specified role. Valid values are 'GUEST' and 'USER'.

sort
string

The names of the fields to sort the results by, in decreasing order of precendence. Allowed values are updatedAt, created. Separate each field by a comma. Prepend the field name with - sign to sort that field in descending order.

include
string

Specify which optional fields to return in the response. Optional fields are: favouriteLocations, favouriteProducts, extended, points, credentials, checkin and segmentIds

limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1', '2', '3': deprecated behaviour (default)
  • '4' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Create a User

Creates an end User for a Tenant.

The User’s roles property will be populated automatically on the platform based on the context of the request. If the request is anonymous, a User with a role of USER will be created. If the request is authenticated as an admin User, a User with a role of ADMIN can be created if specified.

If a credentials.provider value of FACEBOOK is specified, the passed id and token will be validated against the Facebook API and a failure will result in 422 being returned.

When a User account is created, the initial value of loyaltyPoints will be determined by the Merchant settings.

If the User being created has a role of USER and is being created using a MOBILE credential type, their account state will be set to PENDING. This means they will not be able to login until their account has been activated.

If the User being created has a role of USER and is being created using a FACEBOOK credential type, their account state will immediately be set to ACTIVE on successful validation with Facebook.

If a User is created using credentials that already exist in either the ACTIVE or PENDING state, a 422 will be returned.

If a non-Admin User is created with a MOBILE credential type, a 4 digit activation code will be sent via SMS to the supplied number. This activation code should be used to activate the account.

Single Accounts per Device

The platform will enforce single user accounts for a mobile device (by a tenant) if this is enabled in the tenant settings. The x-client-platform header must be sent to identify the platform type.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
autoActivate
string

Set autoActivate to true to skip the user activation process. Note, to use this, an admin session token must be provided.

awaitExternalAccountSync
string

Set awaitExternalAccountSync to true to wait for the external account sync to complete before returning user details. Note, this only applies if autoActivate is set to true.

uniqueDeviceIdAndroid
string

Supports Single Accounts per device. The token that identifies an Android device.

uniqueDeviceIdIOS
string

Supports Single Accounts per device. The token that identifies an iOS device.

Request Body schema: application/json
firstName
required
string
lastName
required
string
fullName
string
required
Array of objects non-empty
hasAgreedToShareData
boolean

The user has accepted sharing his/her data for the purposes of using the Tenant's application (GDPR).

hasAgreedToReceiveMarketing
boolean

The user has accepted receiving marketing messages from or on behalf of the Tenant (GDPR).

birthdate
string
gender
string
Enum: "FEMALE" "MALE"

Responses

Request samples

Content type
application/json
{
  • "firstName": "string",
  • "lastName": "string",
  • "fullName": "string",
  • "credentials": [
    ],
  • "hasAgreedToShareData": true,
  • "hasAgreedToReceiveMarketing": true,
  • "birthdate": "string",
  • "gender": "FEMALE"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenantId": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "fullName": "string",
  • "state": "ACTIVE",
  • "isGuest": true,
  • "roles": [
    ],
  • "subscribed": true,
  • "birthdate": "string",
  • "tokens": {
    },
  • "defaultTip": {
    },
  • "favouriteLocations": [
    ],
  • "primaryPlatform": "UNKNOWN",
  • "contacts": { },
  • "additionalInformation": [
    ],
  • "extended": { },
  • "card": {
    },
  • "hasPaymentCard": true,
  • "hasProfilePhoto": true,
  • "isRegisteredForPushNotifications": true,
  • "hasAgreedToShareData": true,
  • "hasAgreedToReceiveMarketing": true,
  • "externalPosId": "string",
  • "externalLoyaltyId": "string",
  • "updatedAt": "string",
  • "created": "string",
  • "deleted": true
}

Login/Create a user via SSO

Logs a User into the system via a 3rd party SSO provider and retrieves a session for use in subsequent calls to the API.

If the user does not exist in the system, a new user will be created from the details supplied in the request body. firstName and lastName are both required to create a new user if one does not exist already.

When a User account is created, the initial value of loyaltyPoints will be determined by the Merchant settings.

Single Accounts per Device

The platform will enforce single user accounts for a mobile device (by a tenant) if this is enabled in the tenant settings. The x-client-platform header must be sent to identify the platform type.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
ssoProvider
required
string
Enum: "google" "apple"

The SSO provider to verify the incoming JWT with

Request Body schema: application/json
idToken
required
string

The JWT obtained from the 3rd party SSO provider to authenticate and identify the user

firstName
string
lastName
string
fullName
string
hasAgreedToShareData
boolean

The user has accepted sharing his/her data for the purposes of using the Tenant's application (GDPR).

hasAgreedToReceiveMarketing
boolean

The user has accepted receiving marketing messages from or on behalf of the Tenant (GDPR).

birthdate
string
gender
string
Enum: "FEMALE" "MALE"

Responses

Request samples

Content type
application/json
{
  • "idToken": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "fullName": "string",
  • "hasAgreedToShareData": true,
  • "hasAgreedToReceiveMarketing": true,
  • "birthdate": "string",
  • "gender": "FEMALE"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "userId": "string",
  • "tenantId": "string",
  • "tenantTitle": "string",
  • "permanent": true,
  • "lastName": "string",
  • "fullName": "string",
  • "state": "ACTIVE",
  • "isGuest": true,
  • "isPrimary": true,
  • "roles": [
    ],
  • "user": {
    }
}

Activate a User

Activates a specific User.

The response is a compound of a Session resource, with the User included under user.

If an attempt is made to activate a User that is already active, a 422 will be returned.

If token is omitted from the POST body, the Platform assumes that the User is re-attempting activation and the SMS will be delivered again.

If an invalid token is provided, the Platform will return a 422.

On successful activation, the User’s state property will be changed to ACTIVE.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
id
required
string

User's credential id, such as an email or mobile number.

token
string

The activation token. If this omitted, this request is treated as a request to resend the SMS.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "userId": "string",
  • "tenantId": "string",
  • "tenantTitle": "string",
  • "permanent": true,
  • "lastName": "string",
  • "fullName": "string",
  • "state": "ACTIVE",
  • "isGuest": true,
  • "isPrimary": true,
  • "roles": [
    ],
  • "user": {
    }
}

Login a User

Logs a User into the system and retrieves a session for use in subsequent calls to the API.

The request should use Basic authentication.

If an AuthProvider header of FACEBOOK is used, then the 'Basic' auth token is comprised of the Facebook user id as the username, and the session token as the password.

If the User has a state of PENDING, the login will always fail, even if the correct credentials were provided.

Authorizations:
basic
header Parameters
AuthProvider
string
Default: MOBILE

Which authentication provider should fulfil the request

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "userId": "string",
  • "tenantId": "string",
  • "tenantTitle": "string",
  • "permanent": true,
  • "lastName": "string",
  • "fullName": "string",
  • "state": "ACTIVE",
  • "isGuest": true,
  • "isPrimary": true,
  • "roles": [
    ],
  • "user": {
    }
}

Logout a User

Logs out a User by Id.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
userId
required
string

The Id of the User to logout of the system.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Reset User Password

To reset a user password, two requests need to be made:

  1. A reset token request to initiate the request and request a token be sent via SMS or email
POST /users/reset
{
  "id": "07811555123"
}
  1. The new password request, including the reset token request to validate the call
POST /users/reset
{
  "token": "3375",
  "username": "07811555123",
  "password": "password"
}

A User who is in the PENDING state cannot request a reset and a 422 will be returned if they attempt to do so.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
One of
id
required
string

User's credential id, such as an email or mobile number.

Responses

Request samples

Content type
application/json
Example
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Get User by Id

Retrieves a User given a user Id

Optional User fields favouriteLocations, favouriteProducts, extended, points are omitted from the response by default. Specify them in the include parameter to have them included.

Extra fields segmentids, segments, credentials and checkin are also optional. Specify them in include to have them included.

This path is versioned via the x-api-version header, which should be '9' or higher. When x-api-version header is not present, the legacy resource is returned.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The specific ID of the User to retrieve.

query Parameters
include
string

Specify which optional fields to return in the response. Optional fields are: favouriteLocations, favouriteProducts, extended, points, credentials, checkin, segmentids, segments

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1', '2', '3': deprecated behaviour (default)
  • '4' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenantId": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "fullName": "string",
  • "state": "ACTIVE",
  • "isGuest": true,
  • "roles": [
    ],
  • "subscribed": true,
  • "birthdate": "string",
  • "tokens": {
    },
  • "defaultTip": {
    },
  • "favouriteLocations": [
    ],
  • "primaryPlatform": "UNKNOWN",
  • "contacts": { },
  • "additionalInformation": [
    ],
  • "extended": { },
  • "card": {
    },
  • "hasPaymentCard": true,
  • "hasProfilePhoto": true,
  • "isRegisteredForPushNotifications": true,
  • "hasAgreedToShareData": true,
  • "hasAgreedToReceiveMarketing": true,
  • "externalPosId": "string",
  • "externalLoyaltyId": "string",
  • "updatedAt": "string",
  • "created": "string",
  • "deleted": true,
  • "credentials": [
    ],
  • "checkin": {
    },
  • "segments": [
    ],
  • "segmentIds": [
    ]
}

Update a User

Updates a specific User with new information. One or more of the User record's fields can be updated in one call.

The User’s loyalty points cannot be updated via the API. A 422 will result.

A PUT call that includes a property of apnDeviceToken or gcmDeviceToken will cause a new Apple Push Notification or Google Cloud Messaging end-point respectively to be registered for the user on the Amazon Web Services SNS service and will allow Users to receive push notifications.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to update.

Request Body schema: application/json
firstName
string
lastName
string
fullName
string
Array of objects
birthdate
string
gender
string
Enum: "FEMALE" "MALE"
object

The defaults for tipping

favouriteLocations
Array of strings

List of the user's favourite location ids

primaryPlatform
string
Enum: "UNKNOWN" "IOS" "ANDROID"
contacts
object

TODO

extended
object

Tenant specific extensions. For example, login data for extra services such as Secret DJ

hasAgreedToShareData
boolean

The user has accepted sharing his/her data for the purposes of using the Tenant's application (GDPR).

hasAgreedToReceiveMarketing
boolean

The user has accepted receiving marketing messages from or on behalf of the Tenant (GDPR).

apnDeviceToken
string

Cause a new Apple Push Notification end-point to be registered for the user

gcmDeviceToken
string

Cause a new Google Cloud Messaging end-point to be registered for the user

photo
string

User image, base 64 encoded

Responses

Request samples

Content type
application/json
Example
{
  • "firstName": "Wilbert"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "tenantId": "string",
  • "firstName": "string",
  • "lastName": "string",
  • "fullName": "string",
  • "state": "ACTIVE",
  • "isGuest": true,
  • "roles": [
    ],
  • "subscribed": true,
  • "birthdate": "string",
  • "tokens": {
    },
  • "defaultTip": {
    },
  • "favouriteLocations": [
    ],
  • "primaryPlatform": "UNKNOWN",
  • "contacts": { },
  • "additionalInformation": [
    ],
  • "extended": { },
  • "card": {
    },
  • "hasPaymentCard": true,
  • "hasProfilePhoto": true,
  • "isRegisteredForPushNotifications": true,
  • "hasAgreedToShareData": true,
  • "hasAgreedToReceiveMarketing": true,
  • "externalPosId": "string",
  • "externalLoyaltyId": "string",
  • "updatedAt": "string",
  • "created": "string",
  • "deleted": true
}

Delete a User

Remove a User and all their associated records from the system. Note - internally, the user is marked as deleted, and all user information is redacted so that is no longer identifiable.

Requires ADMIN role to delete arbitrary user. USER role may delete their own accounts using this endpoint.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to remove.

query Parameters
deleteLoyaltyAccount
any

"Defaults to true. If true, the request will attempt to delete the user from the merchant's external loyalty service, if supported and configured."

deletePosAccount
any

"Defaults to true. If true, the request will attempt to delete the user from the merchant's pos account, if supported and configured."

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Create a Checkin for a User

If a Checkin is created for a User that does not already have a profile photo associated with their account, a status of 422 will be returned and the Checkin will not be created.

If the User for which a Checkin is being created is already checked in at another Location, the other Checkins will be deleted automatically for them. A User may only be checked in at a single Location at a time.

If the User is already checked in at the Location, an HTTP status code of 409 (Conflict) will be returned by the API.

Checkins will be automatically deleted after 30 minutes.

If the POS associated with the Merchant supports it, a notification will be delivered to the Location’s POS when a new Checkin is created.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The Id of the User to create the Checkin for.

Request Body schema: application/json
locationId
string

Location where the user checked in

type
string
Enum: "AUTO" "MANUAL" "CFD" "OFFLINE" "UNKNOWN"
trigger
string
Enum: "GEO" "BEACON" "CODE" "POS" "UNKNOWN"

What triggered the checkin to occur

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "type": "AUTO",
  • "trigger": "GEO"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "userId": "string",
  • "locationTitle": "string",
  • "userFullName": "string",
  • "type": "AUTO",
  • "updated": "string",
  • "created": "string",
  • "locationId": "string",
  • "trigger": "GEO"
}

Get Checkins for a User

Retrieves the Checkins for a specific User.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Checkins for.

query Parameters
per_page
string
Default: 20

Set the response to be paged by this number of results per page.

page
string
Default: 1

Request a specific page of results in the response. The first page is page 1

Responses

Response samples

Content type
application/json
{
  • "checkins": [
    ],
  • "summary": {
    }
}

Create a Credit for a User

Creates a Credit for a specific User

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to create the Credit for.

Request Body schema: application/json
required
One of
scheme
required
string
number
number
description
required
string
awardId
required
string

The ID of the Award to be credited

Request samples

Content type
application/json
Example
{
  • "scheme": "string",
  • "number": 0,
  • "description": "string",
  • "awardId": "string"
}

Get Credits for a User

Retrieves the Credits for a specific User

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Credits for.

Get Actions for User

Retrieve the Actions for a specific User.

This path is versioned via the x-api-version header, which should be '9' or higher.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Actions for.

query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

when.timestamp[.gt | .lte | .eq | .neq]
string <date-time>

Filter the response using action when.timestamp in comparison to this iso date value. Valid values of comparison are 'gt' (for greater than), 'lte', 'eq', 'neq'. The comparison defaults to 'eq' when not provided

type[.in | .nin]
string

Filter the response using action 'type' in comparison this list of comma separated types. Valid values of comparison are 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided

paymentType[.in | .nin]
string
Example: paymentType[.in | .nin]=CARDHOLDER_PRESENT,APPLEPAY

Filter transactions by payment type. Accepts comma-separated list of OrderPaymentType enum values. Valid values: CASH_AT_POS, CARD_AT_POS, GIFT_CARD_AT_POS, OTHER_AT_POS, APPLEPAY, GOOGLEPAY, CARD_ON_FILE, CARD_TENDERED, GIFT_CARD, CARDHOLDER_PRESENT, CASH, CARD, OTHER, APP, PAY_BY_BANK. Use 'in' (for matching any), 'nin' (for not matching any). The comparison defaults to 'in' when not provided.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '7': deprecated behaviour (default)
  • '8' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "actions": [
    ]
}

Create Addresses for User

Create one address for a specific user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the user to create the address for.

Request Body schema: application/json
name
string
required
object
coordinates
required
Array of numbers[ items = 2 items ]

[Longitude, Latitude]

note
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": {
    },
  • "coordinates": [
    ],
  • "note": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Update Addresses for User

Update one address for a specific user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the user to create the address for.

addressId
required
string

The unique ID of the address to update.

Request Body schema: application/json
name
string
required
object
coordinates
required
Array of numbers[ items = 2 items ]

[Longitude, Latitude]

note
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "address": {
    },
  • "coordinates": [
    ],
  • "note": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Delete Addresses from User

Delete one address for a specific user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the user to delete the address from.

addressId
required
string

The unique ID of the address to delete.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get user credentials

Retrieves the Credentials for a specific User.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Credentials for.

Start Bulk User Import

Upload a file of users to create, along with and perks and points to award and segments to join.

The response is an operation resource that can be polled in order to monitor progress. When complete, the operation will contain a result.href field providing a link to download a file of results.

Required columns:

  • user_first_name
  • user_last_name
  • opt_in_marketing in format TRUE | FALSE

Credential columns: 1 or both of these must be provided

  • email
  • mobile in E.164 format

Optional columns:

  • dob - in format YYYY-MM-DD

  • perk - one or more columns containing perk Ids to award to the imported user

  • audience - one or more columns containing audience Ids to add the imported user to

  • points_perk_XXXX - one or more columns. The perk award Id is parsed from the column suffix XXXX, and the column contains the points to award to the imported user

  • phoneNumberLastUsedToOrder - in E.164 format

  • Address fields - Note: line1, city, postalCode, country are all required column values if an address is being provided

    • line1 - Street address, e.g., "123 Main St."
    • line2 - apartment, suite, building etc. (optional)
    • city - City name
    • region - State, province or region (optional)
    • postalCode - Postal or ZIP code
    • country - Country code (e.g., 'US', 'GB')

  • any other columns - these are echoed to the output results. eg external user ids, etc

Example file:

user_first_name,user_last_name,dob,email,mobile,opt_in_marketing,points_perk_601689c37e7ef80ebefe4121,perk,perk,audience,audience
Fred,Pitt,1997-01-15,fred@gmail.com,447498886666,FALSE,1,605efeade9965c0ecc921311,603938b47a7e830f22cd524a,605c9d6466a2ac0ea3bc6a85,60393894ab83830f3eaae79b
Jane,Arnold,1999-01-01,jane@gmail.com,447398886666,TRUE,4,605efeade9965c0ecc921311,603938b47a7e830f22cd524a,605c9d6466a2ac0ea3bc6a85,60393894ab83830f3eaae79b
Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
dryRun
string

Set dryRun to false in order to perform the import. Otherwise, the import file will be processed to check for errors, but no awards will be granted.

suppressEvents
string

Set suppressEvents to false to cause all events to be emitted during processing.

header Parameters
x-pepper-req-nonce
string

This call requires a nonce in this header to prevent duplicate processing of calls. The nonce value represents an individual call. It should be set to a guid. Each new call should have a new guid. In the rare occasion you want to repeat a call, use the original guid value.

Request Body schema: multipart/form-data
file
string <binary>

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "namespace": "string",
  • "entityId": "string",
  • "nonce": "string",
  • "name": "string",
  • "status": "DONE",
  • "result": {
    },
  • "error": {
    },
  • "createdAt": "string",
  • "updatedAt": "string",
  • "endedAt": "string"
}

Get Bulk User Import Result

Download a file of user import results.

The full path including fileId is retrieved from the import operation's href.

Example Result File:

user_first_name,user_last_name,dob,email,mobile,opt_in_marketing,perk,audience,points_perk_601689c37e7ef80ebefe4121,pepper_id,mobile_e164,award_ids,audiences_added,error
Fred,Pitt,1997-01-15,fred@gmail.com,447498886666,FALSE,605efeade9965c0ecc921311; 603938b47a7e830f22cd524a,605c9d6466a2ac0ea3bc6a85; 60393894ab83830f3eaae79b,1,6064b01ff0c1267d8984cc46,+447498886666,601689c37e7ef80ebefe4121.6064b01ff0c1267d8984cc49=1; 605efeade9965c0ecc921311.6064b01ff0c1267d8984cc4a=1; 603938b47a7e830f22cd524a.6064b01ff0c1267d8984cc4b=1,2,
Jane,Arnold,1999-01-01,jane@gmail.com,447398886666,TRUE,605efeade9965c0ecc921311; 603938b47a7e830f22cd524a,605c9d6466a2ac0ea3bc6a85; 60393894ab83830f3eaae79b,4,6064b01ff0c1267d8984cc4e,+447398886666,601689c37e7ef80ebefe4121.6064b020f0c1267d8984cc51=4; 605efeade9965c0ecc921311.6064b020f0c1267d8984cc52=1; 603938b47a7e830f22cd524a.6064b020f0c1267d8984cc53=1,2,

Column description:

  • user_first_name,user_last_name,dob,email,mobile,opt_in_marketing columns echoed from the import file, along with any other extra columns
  • perk: colon separated list of the parsed perks to grant
  • audience: colon separated list of the parsed audiences to add
  • pepper_id: the pepper user id for the imported user
  • mobile_e164: the parsed mobile, if it was provided
  • award_ids: colon separated list of award information in the format .=
  • audiences_added: the count of audiences the user was added to
  • error: colon separated list of errors, if any
Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
fileId
required
string

The ID of the file to download.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Get a User's Segments

This endpoint is deprecated. Use GET /users/:userId?include=segmentIds or GET /users/:userId?include=segmentsinstead

Retrieve the Segments that the user is in.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The Id of the User

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a User's Awards Deprecated

Get all Awards for a specific User

Note: this endpoint returns the old Perks schema and will be changed in a future version. Use the endpoint GET /users/:userId/pointawards in the meantime.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Awards for.

query Parameters
includeUnvisualisedAwards
string

if true, it will include awards that have not been visualised in the response.

includeDisabled
string

if true, it will include awards linked to disabled perks in the response.

locationId
string

if supported by merchant's setup, it will only return the list of awards valid for the location ID provided.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Get a User's Awards (PointPerk)

Get all awards for a specific user

This endpoint will be deprecated in an upcoming release and be replaced by GET /user/:userId/awards

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Awards for.

query Parameters
includeUnvisualisedAwards
string

if true, it will include awards that have not been visualised in the response.

includeDisabled
string

if true, it will include awards linked to disabled perks in the response.

locationId
string

if supported by merchant's setup, it will only return the list of awards valid for the location ID provided.

Responses

Response samples

Content type
application/json
{
  • "awards": [
    ]
}

Get Payment Cards for a User

Retrieves the payment cards for a specific user. Only admin users can retrieve cards for other users.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Cards for.

Responses

Response samples

Content type
application/json
{
  • "cards": [
    ]
}

Get the Active Payment Card for a User

Retrieves the payment cards for a specific user. Only admin users can retrieve cards for other users.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the active payment card

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "created": "string",
  • "updated": "string",
  • "userId": "string",
  • "cardType": "STRIPE",
  • "gatewayId": "string",
  • "cardId": "string",
  • "methodType": "CARD",
  • "type": "string",
  • "email": "string",
  • "last4": "string",
  • "expires": "string",
  • "autoTopUp": {
    }
}

Award Enrichments

Use the Award Enrichment endpoints to create, updated, delete and get Award Enrichments.

Award Enrichments are used to enrich PointAwards, and external Loyalty Awards with data such as visualisations. Award Enrichments are loyalty provider agnostic.

Create an Award Enrichment

Creates an Award Enrichment for a Loyalty Award or Reward.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
loyaltyRewardId
required
string

A Reward ID representing Pepper PerkID or External Loyalty Reward ID

loyaltyProvider
required
string
Enum: "PEPPER" "SQUARE" "POWERCARD" "ATREEMO" "REVEL" "PAYTRONIX"

The provider of the Loyalty Reward this Enrichment is for

string or null
string or null
string or null
object or null
object or null
object or null
object or null
object or null
Array of strings or null

Responses

Request samples

Content type
application/json
{
  • "loyaltyRewardId": "string",
  • "loyaltyProvider": "PEPPER",
  • "title": "string",
  • "token": "string",
  • "template": "PSEUDO_CURRENCY",
  • "basketQualification": {
    },
  • "dateTimeRestriction": {
    },
  • "points": {
    },
  • "discount": {
    },
  • "visualisation": {
    },
  • "excludeDiscountIds": [
    ]
}

Response samples

Content type
application/json
{
  • "loyaltyRewardId": "string",
  • "loyaltyProvider": "PEPPER",
  • "title": "string",
  • "token": "string",
  • "template": "PSEUDO_CURRENCY",
  • "basketQualification": {
    },
  • "dateTimeRestriction": {
    },
  • "points": {
    },
  • "discount": {
    },
  • "visualisation": {
    },
  • "excludeDiscountIds": [
    ],
  • "_id": "string",
  • "created": "string",
  • "updated": "string"
}

Get all Award Enrichments

Retrieves all the Award Enrichments for a Tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Get an Award Enrichment

Retrieves a specific Award Enrichment for a Tenant

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
enrichmentId
required
string

The ID of the Award Enrichment to retrieve.

Responses

Response samples

Content type
application/json
{
  • "loyaltyRewardId": "string",
  • "loyaltyProvider": "PEPPER",
  • "title": "string",
  • "token": "string",
  • "template": "PSEUDO_CURRENCY",
  • "basketQualification": {
    },
  • "dateTimeRestriction": {
    },
  • "points": {
    },
  • "discount": {
    },
  • "visualisation": {
    },
  • "excludeDiscountIds": [
    ],
  • "_id": "string",
  • "created": "string",
  • "updated": "string"
}

Delete an Award Enrichment

Delete a specific Award Enrichment for a Tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
enrichmentId
required
string

The unique ID of the Award Enrichment to Delete

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Update a Award Enrichment

Update an existing Award Enrichment for a Tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
enrichmentId
required
string

The ID of the Award Enrichment to update.

Request Body schema: application/json
loyaltyRewardId
string

A Reward ID representing Pepper PerkID or External Loyalty Reward ID

loyaltyProvider
string
Enum: "PEPPER" "SQUARE" "POWERCARD" "ATREEMO" "REVEL" "PAYTRONIX"

The provider of the Loyalty Reward this Enrichment is for

string or null
string or null
string or null
object or null
object or null
object or null
object or null
object or null
Array of strings or null

Responses

Request samples

Content type
application/json
{
  • "loyaltyRewardId": "string",
  • "loyaltyProvider": "PEPPER",
  • "title": "string",
  • "token": "string",
  • "template": "PSEUDO_CURRENCY",
  • "basketQualification": {
    },
  • "dateTimeRestriction": {
    },
  • "points": {
    },
  • "discount": {
    },
  • "visualisation": {
    },
  • "excludeDiscountIds": [
    ]
}

Response samples

Content type
application/json
{
  • "loyaltyRewardId": "string",
  • "loyaltyProvider": "PEPPER",
  • "title": "string",
  • "token": "string",
  • "template": "PSEUDO_CURRENCY",
  • "basketQualification": {
    },
  • "dateTimeRestriction": {
    },
  • "points": {
    },
  • "discount": {
    },
  • "visualisation": {
    },
  • "excludeDiscountIds": [
    ],
  • "_id": "string",
  • "created": "string",
  • "updated": "string"
}

Subscription Schemes

Use the Subscription Scheme endpoints to create, retrieve and edit Subscription Schemes.

A Subscription Scheme defines the parameters of a subscription plan that users can subscribe to.

Create a Subscription Scheme

Creates a subscription scheme for a tenant.

A Subscription Scheme defines a recurring billing plan that users can subscribe to with various benefits (perks).

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
required
Array of objects

Pricing options

required
Array of objects

List of perk Ids associated with this subscription scheme

active
boolean

Whether the subscription scheme is active (available for new subscriptions)

title
required
string

Title of the subscription scheme

terms
string

Terms and conditions of the subscription scheme

object

Visualisation details for the subscription scheme

Responses

Request samples

Content type
application/json
{
  • "pricing": [
    ],
  • "perks": [
    ],
  • "active": true,
  • "title": "string",
  • "terms": "string",
  • "visualisation": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "stripe": {
    },
  • "pricing": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "perks": [
    ],
  • "active": true,
  • "title": "string",
  • "terms": "string",
  • "visualisation": {
    }
}

Get all Subscription Schemes

Retrieves all the subscription schemes for a tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '4': deprecated behaviour (default)
  • '5' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Get a Subscription Scheme

Retrieves a subscription scheme for a tenant by Id.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
schemeId
required
string

The Id of the subscription scheme to retrieve.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "stripe": {
    },
  • "pricing": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "deletedAt": "2019-08-24T14:15:22Z",
  • "perks": [
    ],
  • "active": true,
  • "title": "string",
  • "terms": "string",
  • "visualisation": {
    }
}

Update a Subscription Scheme

Update a subscription scheme for a tenant.

Note: price updates (Stripe Price changes) are not allowed via this endpoint.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
schemeId
required
string

The Id of the subscription scheme to update.

Request Body schema: application/json
Array of objects

Pricing options

Array of objects

List of perk Ids associated with this subscription scheme

active
boolean

Whether the subscription scheme is active (available for new subscriptions)

title
string

Title of the subscription scheme

terms
string

Terms and conditions of the subscription scheme

object

Visualisation details for the subscription scheme

Responses

Request samples

Content type
application/json
{
  • "pricing": [
    ],
  • "perks": [
    ],
  • "active": true,
  • "title": "string",
  • "terms": "string",
  • "visualisation": {
    }
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Delete a Subscription Scheme

Delete a subscription scheme for a tenant.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
schemeId
required
string

The unique Id of the subscription scheme to remove.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Subscriptions

Use the Subscription endpoints to create, retrieve and manage Subscriptions.

A Subscription represents an user's subscription to a Subscription Scheme.

Create a Subscription

Creates a subscription for a user.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
userId
string

Id of the user who will own this subscription. Only allowed for admin users to set.

subscriptionSchemeId
required
string

Id of the subscription scheme

paymentMethodId
string

Id of the payment method to be used for this subscription

priceId
string

Id of the price to be used for this subscription

Responses

Request samples

Content type
application/json
{
  • "userId": "string",
  • "subscriptionSchemeId": "string",
  • "paymentMethodId": "string",
  • "priceId": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "userId": "string",
  • "subscriptionSchemeId": "string",
  • "subscriptionScheme": {
    },
  • "stripe": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "paymentMethod": {
    },
  • "active": true,
  • "cancelAt": "2019-08-24T14:15:22Z",
  • "nextPaymentAt": "2019-08-24T14:15:22Z"
}

Get all Subscription

Retrieves all the subscriptions.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Get a Subscription

Retrieves a subscription.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
subscriptionId
required
string

The Id of the subscription to retrieve.

query Parameters
expand
Array of strings
Items Value: "subscriptionScheme"

Optional list of extra fields to be returned in addition to the default subscription fields. Eg expand=subscriptionScheme

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "userId": "string",
  • "subscriptionSchemeId": "string",
  • "subscriptionScheme": {
    },
  • "stripe": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "paymentMethod": {
    },
  • "active": true,
  • "cancelAt": "2019-08-24T14:15:22Z",
  • "nextPaymentAt": "2019-08-24T14:15:22Z"
}

Cancel a Subscription

Cancels a subscription.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
subscriptionId
required
string

The unique Id of the subscription to cancel.

Request Body schema: application/json
comment
string

Reason for cancelling the subscription

Responses

Request samples

Content type
application/json
{
  • "comment": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "userId": "string",
  • "subscriptionSchemeId": "string",
  • "subscriptionScheme": {
    },
  • "stripe": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "paymentMethod": {
    },
  • "active": true,
  • "cancelAt": "2019-08-24T14:15:22Z",
  • "nextPaymentAt": "2019-08-24T14:15:22Z"
}

Resume a Subscription

Resumes a subscription.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
subscriptionId
required
string

The unique Id of the subscription to resume.

Request Body schema: application/json
paymentMethodId
string

Id of the payment method to be used for this subscription

Responses

Request samples

Content type
application/json
{
  • "paymentMethodId": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "userId": "string",
  • "subscriptionSchemeId": "string",
  • "subscriptionScheme": {
    },
  • "stripe": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "paymentMethod": {
    },
  • "active": true,
  • "cancelAt": "2019-08-24T14:15:22Z",
  • "nextPaymentAt": "2019-08-24T14:15:22Z"
}

Sessions

Delete sessions

Removes all the sessions against a userId from the database

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique Id of the user

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Create an admin session

Creates a new admin session

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "userId": "string",
  • "tenantId": "string",
  • "tenantTitle": "string",
  • "permanent": true,
  • "roles": [
    ]
}

Credits

Create a Credit for a User

Creates a Credit for a specific User

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to create the Credit for.

Request Body schema: application/json
required
One of
scheme
required
string
number
number
description
required
string
awardId
required
string

The ID of the Award to be credited

Request samples

Content type
application/json
Example
{
  • "scheme": "string",
  • "number": 0,
  • "description": "string",
  • "awardId": "string"
}

Get Credits for a User

Retrieves the Credits for a specific User

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
userId
required
string

The unique ID of the User to retrieve the Credits for.

Delivery Boundaries

Create Delivery Boundaries for Location

Create one delivery boundary for a specific location.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the location to create the delivery boundary for.

Request Body schema: application/json
required
Polygon Boundary (object) or Circle Boundary (object) (Delivery Boundary)

Fields for creating and updating a Delivery Boundary

filter
required
string
Enum: "include" "exclude"

Location will only be available if delivery coordinates are within an include boundary AND outside of any exclude boundaries.

Responses

Request samples

Content type
application/json
{
  • "deliveryBoundary": {
    },
  • "filter": "include"
}

Response samples

Content type
application/json
{
  • "include": [
    ],
  • "exlude": [
    ]
}

Update Delivery Boundaries for Location

Update one delivery boundary for a specific location.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the location to update the delivery boundary for.

Request Body schema: application/json
required
Polygon Boundary (object) or Circle Boundary (object) (Delivery Boundary)

Fields for creating and updating a Delivery Boundary

filter
required
string
Enum: "include" "exclude"

Location will only be available if delivery coordinates are within an include boundary AND outside of any exclude boundaries.

Responses

Request samples

Content type
application/json
{
  • "deliveryBoundary": {
    },
  • "filter": "include"
}

Response samples

Content type
application/json
{
  • "include": [
    ],
  • "exlude": [
    ]
}

Delete Delivery Boundaries from Location

Delete one delivery boundary for a specific location.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
locationId
required
string

The unique ID of the location to delete the delivery boundary from.

deliveryBoundaryId
required
string

The unique ID of the deliveryBoundary to delete.

Responses

Response samples

Content type
application/json
{
  • "include": [
    ],
  • "exlude": [ ]
}

Delivery

Get Locations for Delivery

Retrieve the locations that are available for delivery for a given pair of co-ordinates.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
lat
required
number

Latitude of the delivery location.

long
required
number

Longitude of the delivery location.

include
Array of strings
Items Enum: "created" "updated" "state" "mainImageUrl" "alternativeOpeningHoursText" "buttons" "links" "description" "ordering" "VATnumber" "regions" "address" "tags" "zones"

Specify which optional fields to return in the response.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Vouchers

Create a Voucher

Creates a voucher for a tenant.

A voucher is redeemable a specific number of times, either globally or per user. In addition, validity dates can be set.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
title
required
string [ 1 .. 255 ] characters
code
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9]*$
voucherSchemeId
string^[0-9a-fA-F]{24}$

Id of the voucher scheme

startDate
required
string <date-time>
endDate
required
string <date-time>
numRedemptionsPerUser
required
integer >= 1
numGlobalRedemptions
required
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "code": "string",
  • "voucherSchemeId": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "numRedemptionsPerUser": 1,
  • "numGlobalRedemptions": 1
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "title": "string",
  • "code": "string",
  • "voucherSchemeId": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "numRedemptionsPerUser": 1,
  • "numGlobalRedemptions": 1
}

Get Vouchers

Gets vouchers for the tenantId, matching any query parameters.

This path is versioned via the x-api-version header, which should be '10' or higher. When x-api-version header is not present, the legacy resource is returned.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
startKey
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

limit
number

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

voucherSchemeId
string

Return vouchers matching voucherSchemeId

sort
string

The names of the fields to sort the results by, in decreasing order of precendence. Allowed values are startDate, endDate, code. Separate each field by a comma. Prepend the field name with - sign to sort that field in descending order.

header Parameters
x-api-version
number

The behaviour of this path is versioned via the x-api-version header. The version should be an integer number as a string, eg '2'. For this endpoint, the supported values are:

  • '1' ... '9': deprecated behaviour (default)
  • '10' or higher: current behaviour as described here

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Redeem a Voucher

Redeems a voucher for a user

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
code
required
string [ 1 .. 255 ] characters ^[A-Za-z0-9]*$

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "userId": "string",
  • "voucherId": "string",
  • "dateRedeemed": "string"
}

Get Voucher by Id

Retrieves a voucher via a voucher Id

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
voucherId
required
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "title": "string",
  • "code": "string",
  • "voucherSchemeId": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "numRedemptionsPerUser": 1,
  • "numGlobalRedemptions": 1,
  • "numRedemptions": 0
}

Update a Voucher

Updates a specific Voucher

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
voucherId
required
string
Request Body schema: application/json
non-empty
title
string [ 1 .. 255 ] characters
code
string [ 1 .. 255 ] characters ^[A-Za-z0-9]*$
voucherSchemeId
string^[a-fA-F0-9]{24}$

Id of the voucher scheme

startDate
string <date-time>
endDate
string <date-time>
numRedemptionsPerUser
integer >= 1
numGlobalRedemptions
integer >= 1

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "code": "string",
  • "voucherSchemeId": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "numRedemptionsPerUser": 1,
  • "numGlobalRedemptions": 1
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "title": "string",
  • "code": "string",
  • "voucherSchemeId": "string",
  • "startDate": "2019-08-24T14:15:22Z",
  • "endDate": "2019-08-24T14:15:22Z",
  • "numRedemptionsPerUser": 1,
  • "numGlobalRedemptions": 1
}

Settings

Upload Apple Pay Domain Association File

Upload the apple-developer-merchantid-domain-association.txt file for Apple Pay web domain verification. The file is stored in S3 at {tenantTitle}/.well-known/apple-developer-merchantid-domain-association.txt.

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: multipart/form-data
file
string <binary>

The .txt domain association file from Apple

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Metrics - Segment

Create a segment metric definition

Create a segment metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
scheduled
required
boolean
factType
required
string
Enum: "ATV" "TotalSpend" "OrderCount"
required
object
required
Array of objects or objects or strings non-empty

Responses

Request samples

Content type
application/json
{
  • "scheduled": true,
  • "factType": "ATV",
  • "query": {
    },
  • "periods": [
    ]
}

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "factType": "ATV",
  • "query": {
    },
  • "periods": [
    ],
  • "_id": "string",
  • "tenantId": "string",
  • "metricClass": "SegmentMetric"
}

Get segment metric definitions

Get segment metric definitions

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
startKey
required
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

limit
required
string

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

scheduled
boolean

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Update a segment metric definition

Update a segment metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
scheduled
boolean
factType
string
Enum: "ATV" "TotalSpend" "OrderCount"
object
Array of objects or objects or strings non-empty

Responses

Request samples

Content type
application/json
{
  • "scheduled": true,
  • "factType": "ATV",
  • "query": {
    },
  • "periods": [
    ]
}

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "factType": "ATV",
  • "query": {
    },
  • "periods": [
    ],
  • "_id": "string",
  • "tenantId": "string",
  • "metricClass": "SegmentMetric"
}

Get segment metric definition by id

Get segment metric definition by id

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string

Responses

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "factType": "ATV",
  • "query": {
    },
  • "periods": [
    ],
  • "_id": "string",
  • "tenantId": "string",
  • "metricClass": "SegmentMetric"
}

Delete a segment metric definition

Delete a segment metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Compute a segment metric definition

Compute a segment metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
header Parameters
x-pepper-req-nonce
required
string

This call requires a nonce in this header to prevent duplicate processing of calls. The nonce value represents an individual call. It should be set to a guid. Each new call should have a new guid. In the rare occasion you want to repeat a call, use the original guid value.

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "namespace": "string",
  • "entityId": "string",
  • "nonce": "string",
  • "name": "string",
  • "status": "DONE",
  • "metadata": null,
  • "result": null,
  • "error": null,
  • "isRetryable": true,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "endedAt": "string"
}

Get segment metrics

Get segment metrics

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
query Parameters
startKey
required
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

limit
required
string

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

metricId
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Metrics - User

Create a user metric definition

Create a user metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
scheduled
required
boolean
realtime
required
boolean
name
required
string
displayName
required
string
tags
Array of strings
recomputeOn
Array of strings
Items Enum: "NOOP" "CARD_CREATED" "CARD_DELETED" "CHECKIN" "USER_CREDITED" "GIFT_CARD_TOPUP" "GIFT_CARD_ACTIVATED" "ORDER_CREATED" "ORDER_ITEMS_ADDED" "ORDER_USER_JOINED" "ORDER_PAYMENT_RECEIVED" "ORDER_PAYMENT_REFUNDED" "ORDER_COMPLETED" "ORDER_USER_BILLED" "REFERAL_CLAIMED_REFEREE" "REFERAL_CLAIMED_REFERER" "REWARD_EARNED" "REDEEM_PERK" "AWARD_POINTS_REFUNDED" "AWARD_POINTS_RESET" "MEMBER_ADDED" "MEMBER_REMOVED" "USER_CREATED" "USER_CHANGED" "USER_DELETED" "USER_ACTIVATION_RESENT" "USER_ACTIVATED" "CREDENTIAL_VERIFIED" "VOUCHER_REDEEMED" "COUPON_REDEEMED" "COUPON_REFUNDED" "BOOKING_CREATED" "BOOKING_CHANGED" "BOOKING_COMPLETED" "SUBSCRIPTION_STARTED" "SUBSCRIPTION_PAYMENT_RECEIVED" "SUBSCRIPTION_CANCELLATION_REQUESTED" "SUBSCRIPTION_CANCELLED"
object
object
required
Array of objects or objects or objects or objects or objects

Responses

Request samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "effects": [
    ]
}

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "effects": [
    ]
}

Get user metric definitions

Get user metric definitions

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
query Parameters
startKey
required
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

limit
required
string

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

scheduled
boolean
tag
string

Filter user metric definitions by matching on a value in the tags field

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}

Update a user metric definition

Update a user metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
Request Body schema: application/json
scheduled
boolean
realtime
boolean
name
string
displayName
string
tags
Array of strings
recomputeOn
Array of strings
Items Enum: "NOOP" "CARD_CREATED" "CARD_DELETED" "CHECKIN" "USER_CREDITED" "GIFT_CARD_TOPUP" "GIFT_CARD_ACTIVATED" "ORDER_CREATED" "ORDER_ITEMS_ADDED" "ORDER_USER_JOINED" "ORDER_PAYMENT_RECEIVED" "ORDER_PAYMENT_REFUNDED" "ORDER_COMPLETED" "ORDER_USER_BILLED" "REFERAL_CLAIMED_REFEREE" "REFERAL_CLAIMED_REFERER" "REWARD_EARNED" "REDEEM_PERK" "AWARD_POINTS_REFUNDED" "AWARD_POINTS_RESET" "MEMBER_ADDED" "MEMBER_REMOVED" "USER_CREATED" "USER_CHANGED" "USER_DELETED" "USER_ACTIVATION_RESENT" "USER_ACTIVATED" "CREDENTIAL_VERIFIED" "VOUCHER_REDEEMED" "COUPON_REDEEMED" "COUPON_REFUNDED" "BOOKING_CREATED" "BOOKING_CHANGED" "BOOKING_COMPLETED" "SUBSCRIPTION_STARTED" "SUBSCRIPTION_PAYMENT_RECEIVED" "SUBSCRIPTION_CANCELLATION_REQUESTED" "SUBSCRIPTION_CANCELLED"
object

Responses

Request samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    }
}

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "effects": [
    ]
}

Get a user metric definition by id

Get a user metric definition by id

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string

Responses

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "effects": [
    ],
  • "id": "string"
}

Delete a user metric definition

Delete a user metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

Add a metric to a user metric definition

Add a metric to a user metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
metricId
required
string
Request Body schema: application/json
Any of
type
required
string
Enum: "TIPS_GIVEN" "NOOP" "CARD_CREATED" "CARD_DELETED" "CHECKIN" "USER_CREDITED" "GIFT_CARD_TOPUP" "GIFT_CARD_ACTIVATED" "ORDER_CREATED" "ORDER_ITEMS_ADDED" "ORDER_USER_JOINED" "ORDER_PAYMENT_RECEIVED" "ORDER_PAYMENT_REFUNDED" "ORDER_COMPLETED" "ORDER_USER_BILLED" "REFERAL_CLAIMED_REFEREE" "REFERAL_CLAIMED_REFERER" "REWARD_EARNED" "REDEEM_PERK" "AWARD_POINTS_REFUNDED" "AWARD_POINTS_RESET" "MEMBER_ADDED" "MEMBER_REMOVED" "USER_CREATED" "USER_CHANGED" "USER_DELETED" "USER_ACTIVATION_RESENT" "USER_ACTIVATED" "CREDENTIAL_VERIFIED" "VOUCHER_REDEEMED" "COUPON_REDEEMED" "COUPON_REFUNDED" "BOOKING_CREATED" "BOOKING_CHANGED" "BOOKING_COMPLETED" "SUBSCRIPTION_STARTED" "SUBSCRIPTION_PAYMENT_RECEIVED" "SUBSCRIPTION_CANCELLATION_REQUESTED" "SUBSCRIPTION_CANCELLED"
name
required
string
displayName
required
string
required
object or object or string

Responses

Request samples

Content type
application/json
{
  • "type": "POINTS_EARNED",
  • "perkId": "string",
  • "name": "string",
  • "displayName": "string",
  • "timeRange": {
    }
}

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "effects": [
    ]
}

Delete a metric from a user metric definition

Delete a metric from a user metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
metricId
required
string

Responses

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "effects": [
    ]
}

Add an effect to a user metric definition

Add an effect to a user metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
Request Body schema: application/json
Any of
type
required
string
Enum: "ADD_TO_SEGMENT" "REMOVE_FROM_SEGMENT"
segmentId
required
string
Array of objects or objects or objects or objects or objects or objects or objects or objects

Responses

Request samples

Content type
application/json
{
  • "type": "GRANT_PERK",
  • "perkId": "string",
  • "points": 0,
  • "counter": {
    },
  • "conditions": [
    ]
}

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "effects": [
    ]
}

Delete an effect from a user metric definition

Delete an effect from a user metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
effectId
required
string

Responses

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "effects": [
    ]
}

Add a condition to a user metric definition effect

Add a condition to a user metric definition effect

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
effectId
required
string
Request Body schema: application/json
Any of
metricId
required
string
operator
required
string
Enum: "EQUAL" "NOT_EQUAL" "GREATER_THAN" "LESS_THAN"
value
required
number

Responses

Request samples

Content type
application/json
{
  • "operator": "IS_IN_SEGMENT",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "effects": [
    ]
}

Delete a condition from a user metric definition e

Delete a condition from a user metric definition effect

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
effectId
required
string
conditionId
required
string

Responses

Response samples

Content type
application/json
{
  • "scheduled": true,
  • "realtime": true,
  • "name": "string",
  • "displayName": "string",
  • "tags": [
    ],
  • "recomputeOn": [
    ],
  • "query": {
    },
  • "metrics": {
    },
  • "_id": "string",
  • "tenantId": "string",
  • "effects": [
    ]
}

Compute user metric definition

Compute user metric definition

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
header Parameters
x-pepper-req-nonce
required
string

This call requires a nonce in this header to prevent duplicate processing of calls. The nonce value represents an individual call. It should be set to a guid. Each new call should have a new guid. In the rare occasion you want to repeat a call, use the original guid value.

Request Body schema: application/json
userId
string

Responses

Request samples

Content type
application/json
{
  • "userId": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "tenantId": "string",
  • "namespace": "string",
  • "entityId": "string",
  • "nonce": "string",
  • "name": "string",
  • "status": "DONE",
  • "metadata": null,
  • "result": null,
  • "error": null,
  • "isRetryable": true,
  • "createdAt": "string",
  • "updatedAt": "string",
  • "endedAt": "string"
}

Get user metric values

Get user metric values

Authorizations:
auth-tokenbearer-auth-tokenx-service-auth-token
path Parameters
definitionId
required
string
query Parameters
startKey
required
string

Request results to start at the record represented by this key. You can page through a dataset by making requests, setting startKey to the nextKey value provided in the last response.

limit
required
string

Set the response to be paged, and limit by this number of results. If not provided, a default limit (usually 100) will be used

metricId
string
userId
string

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": {
    }
}