Skip to main content
API docs by Redocly

Loyalty Core Platform API (2.0)

Download OpenAPI specification:Download

Coupon Books

Get all the coupon books for the current organization

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Default: 25
Example: limit=10

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

search
string

Case-insensitive substring match across the coupon book's name, description, and externalId.

tags
string

Filter by all of these tags (AND logic). Comma-separated.

tagsAny
string

Filter by any of these tags (OR logic). Comma-separated.

status
Array of strings
Items Enum: "draft" "published" "disabled" "archived"

The status of the coupon book. Accepts a single value or comma-separated list (e.g. 'draft,disabled').

locale
string
Deprecated

Translation locale requested for the coupon

audiences
string
locations
string
categories
string
productCategories
string
paymentMethods
string
channels
string
channelsMatch
string
Default: "effective"
Enum: "effective" "exact"

How the channels filter treats books with no channel restriction. 'effective' (default): they match. 'exact': they are excluded.

daysOfWeek
string
validFromDate
string <date-time>
validToDate
string <date-time>
validFromDateMin
string <date-time>

Admin filter: return only books whose validFromDate >= this value (future start). NULL validFromDate values are excluded.

validToDateMax
string <date-time>

Admin filter: return only books whose validToDate <= this value (already expired). Books with no validToDate are excluded.

tierKeys
Array of strings

Filter by tier keys

loyaltyProgramKey
string
externalId
string
type
string
Enum: "single" "list" "generated" "codeless"

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/coupon-books?page=0&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Creates a new coupon book

Authorizations:
bearer
Request Body schema: application/json
required
externalId
string
publishingStatus
required
string
Enum: "draft" "published" "disabled"

Publishing status of the coupon book

maxCouponCount
number
currentVersionId
number
name
required
string
description
string
subtitle
string
pictureUrl
string
detailPictureUrl
string
images
object

Named image URLs as key-value pairs (e.g., main, detail, thumbnail)

rankingIndex
number
type
required
string
Enum: "single" "list" "generated" "codeless"

Type of coupon book

discountAmount
number
discountType
string
maxAssignedPerMember
number
maxAssignedPerCoupon
number
validFromDate
string <date-time>
validToDate
string <date-time>
maxDiscountPerPeriod
number

Maximum discount amount allowed per period

discountPeriodType
string
Enum: "daily" "weekly" "monthly"

Period type for discount limit

maxUsagesPerPeriod
number

Maximum number of usages allowed per period

usagePeriodType
string
Enum: "daily" "weekly" "monthly"

Period type for usage limit

timezone
string

IANA timezone string for period calculations (e.g., America/Argentina/Buenos_Aires, Europe/Madrid)

maxDiscountPerUse
number

Maximum discount amount allowed per use

assignmentRequiredPoints
number
usageRequiredPoints
number
tags
Array of strings
audienceKeys
Array of strings
locations
Array of strings or null

Locations for filtering coupon books by location

categories
Array of strings or null

Categories for filtering coupon books by category

productCategories
Array of strings or null

Product categories for filtering coupon books by product category

paymentMethods
Array of strings or null

Payment methods for filtering coupon books by payment method

channels
Array of strings or null

Channels for filtering coupon books by channel

daysOfWeek
Array of numbers

Days of week when coupon book is available (1=Monday, 7=Sunday)

contentSchemaId
number
contentSchemaVersionId
number
customAttributes
object
condition
object
locale
string
Deprecated

Locale

content
object
Deprecated

Content of the coupon book

isDefaultLocale
boolean
Deprecated

Is the locale default

defaultLocale
string
Deprecated

Default locale

object or null

Required-points configuration (keys only). Required when assignmentRequiredPoints or usageRequiredPoints is set.

tiers
Array of numbers
Deprecated

Tiers (deprecated, use tierKeys instead)

tierKeys
Array of strings

Tier keys (use instead of tiers)

loyaltyProgramKey
string

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "publishingStatus": "draft",
  • "maxCouponCount": 0,
  • "currentVersionId": 0,
  • "name": "string",
  • "description": "string",
  • "subtitle": "string",
  • "pictureUrl": "string",
  • "detailPictureUrl": "string",
  • "images": {},
  • "rankingIndex": 0,
  • "type": "single",
  • "discountAmount": 0,
  • "discountType": "string",
  • "maxAssignedPerMember": 0,
  • "maxAssignedPerCoupon": 0,
  • "validFromDate": "2019-08-24T14:15:22Z",
  • "validToDate": "2019-08-24T14:15:22Z",
  • "maxDiscountPerPeriod": 0,
  • "discountPeriodType": "daily",
  • "maxUsagesPerPeriod": 0,
  • "usagePeriodType": "daily",
  • "timezone": "string",
  • "maxDiscountPerUse": 1000,
  • "assignmentRequiredPoints": 0,
  • "usageRequiredPoints": 0,
  • "tags": [
    ],
  • "audienceKeys": [
    ],
  • "locations": [
    ],
  • "categories": [
    ],
  • "productCategories": [
    ],
  • "paymentMethods": [
    ],
  • "channels": [
    ],
  • "daysOfWeek": [
    ],
  • "contentSchemaId": 0,
  • "contentSchemaVersionId": 0,
  • "customAttributes": { },
  • "condition": { },
  • "locale": "string",
  • "content": { },
  • "isDefaultLocale": true,
  • "defaultLocale": "string",
  • "requiredPointsConfig": {
    },
  • "tiers": [
    ],
  • "tierKeys": [
    ],
  • "loyaltyProgramKey": "string"
}

Response samples

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

Get an existing coupon book details

Authorizations:
bearer
path Parameters
couponBookKey
required
string

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/coupon-books/{couponBookKey}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

Updates a coupon book

Authorizations:
bearer
path Parameters
couponBookKey
required
string
Request Body schema: application/json
required
externalId
string
maxCouponCount
number
currentVersionId
number
description
string
subtitle
string
pictureUrl
string
detailPictureUrl
string
images
object

Named image URLs as key-value pairs (e.g., main, detail, thumbnail)

rankingIndex
number
discountAmount
number
discountType
string
maxAssignedPerMember
number
maxAssignedPerCoupon
number
validFromDate
string <date-time>
validToDate
string <date-time>
maxDiscountPerPeriod
number

Maximum discount amount allowed per period

discountPeriodType
string
Enum: "daily" "weekly" "monthly"
maxUsagesPerPeriod
number

Maximum number of usages allowed per period

usagePeriodType
string
Enum: "daily" "weekly" "monthly"
timezone
string

IANA timezone string for period calculations (e.g., America/Argentina/Buenos_Aires, Europe/Madrid)

maxDiscountPerUse
number

Maximum discount amount allowed per use

assignmentRequiredPoints
number
usageRequiredPoints
number
tags
Array of strings
audienceKeys
Array of strings
locations
Array of strings or null

Locations for filtering coupon books by location

categories
Array of strings or null

Categories for filtering coupon books by category

productCategories
Array of strings or null

Product categories for filtering coupon books by product category

paymentMethods
Array of strings or null

Payment methods for filtering coupon books by payment method

channels
Array of strings or null

Channels for filtering coupon books by channel

daysOfWeek
Array of numbers

Days of week when coupon book is available (1=Monday, 7=Sunday)

contentSchemaId
number
contentSchemaVersionId
number
customAttributes
object
condition
object
locale
string
Deprecated

Locale

content
object
Deprecated

Content of the coupon book

isDefaultLocale
boolean
Deprecated

Is the locale default

defaultLocale
string
Deprecated

Default locale

name
string

The name of the coupon book

extraFields
object

content extra fields

object or null

Required-points configuration (keys only). Required when assignmentRequiredPoints or usageRequiredPoints is set. Pass null to clear the stored config.

tiers
Array of numbers
Deprecated

Tiers (deprecated, use tierKeys instead)

tierKeys
Array of strings

Tier keys (use instead of tiers)

loyaltyProgramKey
string

Responses

Request samples

Content type
application/json
{
  • "externalId": "string",
  • "maxCouponCount": 0,
  • "currentVersionId": 0,
  • "description": "string",
  • "subtitle": "string",
  • "pictureUrl": "string",
  • "detailPictureUrl": "string",
  • "images": {},
  • "rankingIndex": 0,
  • "discountAmount": 0,
  • "discountType": "string",
  • "maxAssignedPerMember": 0,
  • "maxAssignedPerCoupon": 0,
  • "validFromDate": "2019-08-24T14:15:22Z",
  • "validToDate": "2019-08-24T14:15:22Z",
  • "maxDiscountPerPeriod": 0,
  • "discountPeriodType": "daily",
  • "maxUsagesPerPeriod": 0,
  • "usagePeriodType": "daily",
  • "timezone": "string",
  • "maxDiscountPerUse": 1000,
  • "assignmentRequiredPoints": 0,
  • "usageRequiredPoints": 0,
  • "tags": [
    ],
  • "audienceKeys": [
    ],
  • "locations": [
    ],
  • "categories": [
    ],
  • "productCategories": [
    ],
  • "paymentMethods": [
    ],
  • "channels": [
    ],
  • "daysOfWeek": [
    ],
  • "contentSchemaId": 0,
  • "contentSchemaVersionId": 0,
  • "customAttributes": { },
  • "condition": { },
  • "locale": "string",
  • "content": { },
  • "isDefaultLocale": true,
  • "defaultLocale": "string",
  • "name": "string",
  • "extraFields": { },
  • "requiredPointsConfig": {
    },
  • "tiers": [
    ],
  • "tierKeys": [
    ],
  • "loyaltyProgramKey": "string"
}

Response samples

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

Updates the status of a coupon book (draft, published, disabled, or archived). Archiving is permanent and irreversible.

Authorizations:
bearer
path Parameters
couponBookKey
required
string
Request Body schema: application/json
required
publishingStatus
required
string
Enum: "draft" "published" "disabled" "archived"

Status of the coupon book. Setting archived is permanent and irreversible — the book will be hidden from members and will no longer accept new assignments or coupon usages.

Responses

Request samples

Content type
application/json
{
  • "publishingStatus": "draft"
}

Response samples

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

Check where a coupon book is referenced

Returns whether the coupon book is referenced in any campaign effect (assign-coupon) or in any CMS document belonging to a collection of contentType 'coupons'. Includes full details of each reference location.

Authorizations:
bearer
path Parameters
couponBookKey
required
string
Example: book_summer2025

The key of the coupon book to check

Responses

Response samples

Content type
application/json
{
  • "isReferenced": true,
  • "references": {
    }
}

Coupon Books Coupons

Get all coupon codes in a coupon book

Authorizations:
bearer
path Parameters
couponBookKey
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

Responses

Request samples 

curl -X GET https://api.sandbox.qurable.io/v2/coupon-books/{couponBookKey}/coupons

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Add coupon codes to a coupon book

Authorizations:
bearer
path Parameters
couponBookKey
required
string
Request Body schema: application/json
required
codes
required
Array of strings

Codes to be added

Responses

Request samples

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

Response samples

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

Members Coupon Books

Get all the coupon books from a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

tags
string

Filter by all of these tags (AND logic). Comma-separated.

tagsAny
string

Filter by any of these tags (OR logic). Comma-separated.

validFromDate
string <date-time>
validToDate
string <date-time>
locale
string
Deprecated

Translation locale requested for the coupon

locations
string
categories
string
productCategories
string
paymentMethods
string
channels
string
channelsMatch
string
Default: "effective"
Enum: "effective" "exact"

How the channels filter treats books with no channel restriction. 'effective' (default): they match. 'exact': they are excluded.

daysOfWeek
string
dryRun
boolean

When true, returns every candidate coupon book (skipping eligibility filtering) with eligible and exclusionReasons fields populated per book. The same predicates are still applied — they are surfaced as reasons instead of filters. Useful for debugging why a particular book is or isn't returned for a member.

limit
number [ 1 .. 100 ]
Default: 25
Example: limit=10

The limit of items to return per page

couponBookKey
string
withStockOnly
boolean
externalId
string
type
string
Enum: "single" "list" "generated" "codeless"

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/coupon-books?page=0&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Use a coupon from the coupon-book

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
couponBookKey
required
string
Request Body schema: application/json
required
systemUniqueKey
string

System Unique Key by Organization ID

code
string

Code to be used

pendingCaptureLedgerTransactionId
string

Ledger transaction ID

externalId
string

External ID for tracking

pointsOverride
number

Optional points override. Positive values burn points, negative values mint points, zero skips point transaction. When absent, uses coupon book configured points.

amountDiscounted
number

The actual discount amount applied in this usage

description
string

Description for the ledger transaction

tags
Array of strings

Tags for the ledger transaction

bypassUsageRestrictions
boolean
Default: false

Bypass time-based usage restrictions for late-arriving reports of real-world events. Ignores: coupon expiredAt, period usage limit, and period discount limit. Stock caps, per-member quota, coupon-must-exist, and ledger point requirements still apply.

usageData
object
autoAssign
boolean

Responses

Request samples

Content type
application/json
{
  • "systemUniqueKey": "string",
  • "code": "string",
  • "pendingCaptureLedgerTransactionId": "1234",
  • "externalId": "ext-123",
  • "pointsOverride": 100,
  • "amountDiscounted": 0,
  • "description": "string",
  • "tags": [
    ],
  • "bypassUsageRestrictions": false,
  • "usageData": { },
  • "autoAssign": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "string",
  • "couponUsage": {
    }
}

Assign a coupon from the coupon-book

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
couponBookKey
required
string
Request Body schema: application/json
required
amount
object
Default: 1

Amount to be assigned for each code

pendingCaptureLedgerTransactionId
string

Ledger transaction ID

externalId
string

External ID for tracking

pointsOverride
number

Optional points override. Positive values burn points, negative values mint points, zero skips point transaction. When absent, uses coupon book configured points.

description
string

Description for the ledger transaction

tags
Array of strings

Tags for the ledger transaction

systemUniqueKey
string
code
string
couponData
object
usageData
object
expiresAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "pendingCaptureLedgerTransactionId": "1234",
  • "externalId": "ext-456",
  • "pointsOverride": 50,
  • "description": "string",
  • "tags": [
    ],
  • "systemUniqueKey": "string",
  • "code": "string",
  • "couponData": { },
  • "usageData": { },
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "string",
  • "couponUsage": {
    }
}

Get all the coupons from a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

notUsedOnly
boolean
couponBookTags
string

Filter by coupon books with all of these tags (AND logic). Comma-separated.

couponBookTagsAny
string

Filter by coupon books with any of these tags (OR logic). Comma-separated.

couponCode
string
couponBookKey
string

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/coupons?page=0&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Get all the coupon usages from a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

codes
Array of a[ items ]

Filter coupon usages by coupon codes (exact match). Maximum 100 codes allowed.

fromCreatedAt
string <date-time>

Filter coupon usages created from this date

toCreatedAt
string <date-time>

Filter coupon usages created up to this date

unusedOnly
boolean
Default: false

When true, returns only assignation records (amountAssigned > 0) for coupon codes where the member still has available balance

couponBookTags
string

Filter by coupon books with all of these tags (AND logic). Comma-separated.

couponBookTagsAny
string

Filter by coupon books with any of these tags (OR logic). Comma-separated.

couponBookKey
string

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/CL-RUT-90892932/coupon-usages?page=0&limit=10&couponBookKey={couponBookKey}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Get a single coupon usage from a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
couponUsageKey
required
string

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/coupon-usages/{couponUsageKey}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "string",
  • "couponUsage": {
    }
}

Revert a coupon usage from a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
couponUsageKey
required
string

Responses

Request samples 


curl -X 'POST' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/coupon-usages/{couponUsageKey}/revert' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "status": "success",
  • "message": "string",
  • "couponUsage": {
    }
}

Revert the latest (or all) unreverted coupon usage(s) for a specific coupon code

By default reverts the most recent unreverted usage. Use revertAll=true to revert all unreverted usages for this code. WARNING: revertAll=true can revert up to 100 usages - use with caution. Partial failures in batch mode will return a warning status with details.

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
couponBookKey
required
string
couponCode
required
string
query Parameters
revertAll
boolean
Default: false

When true, revert all unreverted usages for this coupon code (max 100 usages). Default: false

Responses

Response samples

Content type
application/json
Example
{
  • "status": "success",
  • "message": "string",
  • "couponUsage": {
    }
}

Coupons

Get all coupons

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=10

The limit of items to return per page

code
string
couponBookKey
string
loyaltyMemberId
string
expired
boolean

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/coupons?code={code}?page=0&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Badges

Get all badges for an organization

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

active
boolean

Filter by active status

tags
string

Filter by all of these tags (AND logic). Comma-separated.

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new badge

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string
description
string
pictureUrl
string
maxAmount
required
number
active
required
boolean
tags
Array of strings
customAttributes
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "maxAmount": 0,
  • "active": true,
  • "tags": [
    ],
  • "customAttributes": { }
}

Response samples

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

Get a badge by key

Authorizations:
bearer
path Parameters
badgeKey
required
string

Responses

Response samples

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

Update an existing badge

Authorizations:
bearer
path Parameters
badgeKey
required
string
Request Body schema: application/json
required
name
string
description
string
pictureUrl
string
maxAmount
number
active
boolean
tags
Array of strings
customAttributes
object

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "maxAmount": 0,
  • "active": true,
  • "tags": [
    ],
  • "customAttributes": { }
}

Response samples

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

Member Badges

Get badges assigned to a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Default: 25
Example: limit=25

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

active
boolean

Filter by active status

tags
string

Filter by all of these tags (AND logic). Comma-separated.

badgeKeys
string

Filter by a specific list of badge keys (comma-separated). When provided, requested badges are returned even if the member's assignedBalance is 0.

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/badges?page=1&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Get member badge balance

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
badgeKey
required
string

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/badges/{badgeKey}/balance' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

Assign a badge to a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
badgeKey
required
string
Request Body schema: application/json
required
amount
number >= 1
Default: 1

Amount to assign

systemUniqueKey
string

System unique key for idempotency

customAttributes
object

Custom attributes

externalId
string

External ID for tracking

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "systemUniqueKey": "string",
  • "customAttributes": { },
  • "externalId": "string"
}

Response samples

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

Unassign a badge from a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
badgeKey
required
string
Request Body schema: application/json
required
amount
number >= 1
Default: 1

Amount to unassign

systemUniqueKey
string

System unique key for idempotency

customAttributes
object

Custom attributes

externalId
string

External ID for tracking

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "systemUniqueKey": "string",
  • "customAttributes": { },
  • "externalId": "string"
}

Response samples

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

Revert a badge assignment

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
badgeTrackingKey
required
string

Responses

Request samples 


curl -X 'POST' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/badge-trackings/{badgeTrackingKey}/revert' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

CMS

Get all collections with filtering

Authorizations:
bearer
query Parameters
contentType
string
Example: contentType=static

Filter by content type

tags
Array of strings

Filter by tags

page
number
Default: 0
Example: page=0

Page number

limit
number
Default: 20
Example: limit=20

Results per page

sort
string
Example: sort=createdAt:desc

Sort field and direction

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0
}

Create a new collection

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string

Collection name

description
required
string

Collection description

slug
string

Slug (auto-generated from name if omitted)

ftsFields
Array of strings

FTS fields

facetFields
object

Facet fields map

jsonschema
object

JSON Schema for documents

tags
Array of strings

Tags for categorization

contentType
string
Enum: "static" "coupon"

Content type

customAttributes
object

Custom attributes for the collection

Responses

Request samples

Content type
application/json
{
  • "name": "products",
  • "description": "Lorem ipsum",
  • "slug": "string",
  • "ftsFields": [
    ],
  • "facetFields": {
    },
  • "jsonschema": { },
  • "tags": [
    ],
  • "contentType": "static",
  • "customAttributes": {
    }
}

Response samples

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

Get collection by key or slug

Authorizations:
bearer
path Parameters
collectionKeyOrSlug
required
string

Responses

Response samples

Content type
application/json
{
  • "collectionKey": "products",
  • "name": "products",
  • "description": "Lorem ipsum",
  • "slug": "string",
  • "ftsFields": [
    ],
  • "facetFields": {
    },
  • "jsonschema": { },
  • "tags": [
    ],
  • "contentType": "static",
  • "customAttributes": {
    },
  • "createdAt": "2022-01-01T00:00:00.000Z",
  • "updatedAt": "2022-01-01T00:00:00.000Z"
}

Update a collection by key or slug

Authorizations:
bearer
path Parameters
collectionKeyOrSlug
required
string
Request Body schema: application/json
required
name
string

Collection name

description
string

Collection description

slug
string

Slug (auto-generated from name if omitted)

ftsFields
Array of strings

FTS fields

facetFields
object

Facet fields map

jsonschema
object

JSON Schema for documents

tags
Array of strings

Tags for categorization

contentType
string
Enum: "static" "coupon"

Content type

customAttributes
object

Custom attributes for the collection

Responses

Request samples

Content type
application/json
{
  • "name": "products",
  • "description": "Lorem ipsum",
  • "slug": "string",
  • "ftsFields": [
    ],
  • "facetFields": {
    },
  • "jsonschema": { },
  • "tags": [
    ],
  • "contentType": "static",
  • "customAttributes": {
    }
}

Response samples

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

Get collection documents by key or slug

Searches the collection's documents (full-text, facets, ranges, pagination). Served from a read replica, so a document written moments earlier may take a short replication delay to appear here; read a document by key or slug for a read-your-writes consistent view.

Authorizations:
bearer
path Parameters
collectionKeyOrSlug
required
string
query Parameters
q
string
Example: q=auriculares

Free text for full-text search

range
string
Example: range=range.price.min=10&range.price.max=100

Range filters (numeric or date). Use dot notation in query string: range.{field}.min=value&range.{field}.max=value

facet
string
Example: facet=facet.audienceKeys=['aud_00000']

Facet filters for exact matches. Use dot notation: facets.{field}=value or facets.{field}=['val1','val2']

locale
string
Default: ""

Locale filter (empty string for default)

status
string
Enum: "draft" "published"
Example: status=published

Document status filter (default: published)

sort
string
Example: sort=price:asc,createdAt:desc

Sort field and direction (e.g. "price:asc", "createdAt:desc")

page
number
Example: page=0

Page number (starting at 0)

limit
number
Example: limit=20

Result limit (1–200)

Responses

Response samples

Content type
application/json
{
  • "collection": {
    },
  • "query": {
    },
  • "totalCount": 10,
  • "items": [
    ],
  • "facets": {
    }
}

Batch create or update documents

Creates or updates multiple documents in a collection. Each document must include a documentKey. Existing documents will be updated, new documents will be created.

Authorizations:
bearer
path Parameters
collectionKeyOrSlug
required
string
Request Body schema: application/json
required
required
Array of objects (CmsBatchUpsertDocumentItemDto)

Documents to create or update

Array
documentKey
required
string

Document key (required for batch upsert)

slug
string

Slug (optional, duplicates allowed)

attrs
required
object

Document attributes

status
required
string
Enum: "draft" "published"
locale
required
string
Default: ""

Locale code (empty string for default)

fromDate
string or null <date-time>

Start date for content visibility

toDate
string <date-time>

End date for content visibility

audienceKeys
Array of strings

Audience segment keys

daysOfWeek
Array of strings

Days of week the document is valid (1=Monday, 7=Sunday). Empty or null means all days.

object

Per-day hour schedule with IANA timezone. Entries specify a day and hour window (fromHour–toHour, both inclusive, 0-23). Takes precedence over daysOfWeek when present.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "upserted": [
    ],
  • "failed": [
    ],
  • "total": 0,
  • "successCount": 0,
  • "failureCount": 0
}

Get a specific document by documentKey or slug, and locale

Get document for a specific locale using either documentKey (UUID) or slug. Use empty string or omit locale query param for default locale.

Authorizations:
bearer
path Parameters
collectionKeyOrSlug
required
string
documentKeyOrSlug
required
string
query Parameters
locale
required
string

Responses

Response samples

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

Update a specific document by documentKey or slug

Update document for a specific locale. Use empty string or omit locale query param for default locale.

Authorizations:
bearer
path Parameters
collectionKeyOrSlug
required
string
documentKeyOrSlug
required
string
query Parameters
locale
required
string
Request Body schema: application/json
required
slug
string

Slug (optional, duplicates allowed)

attrs
object

Document attributes

status
string
Enum: "draft" "published"
fromDate
string or null <date-time>

Start date for content visibility

toDate
string <date-time>

End date for content visibility

audienceKeys
Array of strings

Audience segment keys

daysOfWeek
Array of strings

Days of week the document is valid (1=Monday, 7=Sunday). Empty or null means all days.

object

Per-day hour schedule with IANA timezone. Entries specify a day and hour window (fromHour–toHour, both inclusive, 0-23). Takes precedence over daysOfWeek when present.

locale
string
Default: ""

Locale code (empty string for default)

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "attrs": { },
  • "status": "draft",
  • "fromDate": "2019-08-24T14:15:22Z",
  • "toDate": "2019-08-24T14:15:22Z",
  • "audienceKeys": [
    ],
  • "daysOfWeek": [
    ],
  • "dayOfWeekSchedule": {
    },
  • "locale": ""
}

Response samples

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

Delete a single document (soft delete)

Deletes a single document by documentKey or slug. Returns the deleted document details.

Authorizations:
bearer
path Parameters
collectionKeyOrSlug
required
string
documentKeyOrSlug
required
string
query Parameters
locale
required
string

Responses

Response samples

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

Get all locale versions of a document

Returns all translations (locales) for a given documentKey or slug.

Authorizations:
bearer
path Parameters
collectionKeyOrSlug
required
string
documentKeyOrSlug
required
string

Responses

Response samples

Content type
application/json
{
  • "documentKeyOrSlug": "string",
  • "locales": [
    ]
}

Create or update a specific locale version of a document

Upsert a translation for a specific locale. The documentKey groups all translations together.

Authorizations:
bearer
path Parameters
collectionKeyOrSlug
required
string
documentKeyOrSlug
required
string
locale
required
string
Request Body schema: application/json
required
slug
string

Slug (optional, duplicates allowed)

attrs
required
object

Document attributes

status
required
string
Enum: "draft" "published"
fromDate
string or null <date-time>

Start date for content visibility

toDate
string <date-time>

End date for content visibility

audienceKeys
Array of strings

Audience segment keys

daysOfWeek
Array of strings

Days of week the document is valid (1=Monday, 7=Sunday). Empty or null means all days.

object

Per-day hour schedule with IANA timezone. Entries specify a day and hour window (fromHour–toHour, both inclusive, 0-23). Takes precedence over daysOfWeek when present.

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "attrs": { },
  • "status": "draft",
  • "fromDate": "2019-08-24T14:15:22Z",
  • "toDate": "2019-08-24T14:15:22Z",
  • "audienceKeys": [
    ],
  • "daysOfWeek": [
    ],
  • "dayOfWeekSchedule": {
    }
}

Response samples

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

Members

Gets organization's members details

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=25

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

email
string

Filter by email

loyaltyMemberId
string

Filter by loyalty member id

govId
string

Filter by government id (matches the id inside the gov_id field)

fromCreatedAt
string <date-time>

Filter members created from this date

toCreatedAt
string <date-time>

Filter members created up to this date

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 100,
  • "page": 1,
  • "limit": 10
}

Creates a new member in the current organization

Authorizations:
bearer
Request Body schema: application/json
required
loyaltyMemberId
required
string

Loyalty Member Id within Organization and Loyalty Program

publicLoyaltyMemberId
string

Optional Public Loyalty Member Id within Organization and Loyalty Program

object

Member's Profile Info.

active
boolean

Member's Active Status.

customAttributes
object

Custom dynamic attributes for organization member.

memberType
string

Type of the member.

channelAcquisition
string

Channel through which the member was acquired.

notifications
object

Notification preferences

referralCode
string

An Optional Referral Code

Responses

Request samples

Content type
application/json
{
  • "loyaltyMemberId": "11111-11111",
  • "publicLoyaltyMemberId": "11111-11111",
  • "profile": {
    },
  • "active": true,
  • "customAttributes": {
    },
  • "memberType": "organization",
  • "channelAcquisition": "mobile_app",
  • "notifications": {
    },
  • "referralCode": "ref-24fAdsa"
}

Response samples

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

Gets organization's Loyalty Member details

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
includeBalance
boolean
Default: true

When false, skips the wallet-balance lookup and returns the member without ledger balances. Defaults to true.

Responses

Response samples

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

Updates a member in the current organization

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
Request Body schema: application/json
required
loyaltyMemberId
string

Loyalty Member Id within Organization and Loyalty Program

publicLoyaltyMemberId
string

Optional Public Loyalty Member Id within Organization and Loyalty Program

object

Member's Profile Info.

active
boolean

Member's Active Status.

customAttributes
object

Custom dynamic attributes for organization member.

memberType
string

Type of the member.

notifications
object

Notification preferences

updateReason
string

Reason for updating the member

emitEvent
boolean
Default: true

If true (default), pushes a MemberUpdated loyalty event onto SQS so event triggers and downstream consumers react to this update. Set to false to suppress the event — for back-office or migration writes that should not fan out. The DB audit log is written regardless.

Responses

Request samples

Content type
application/json
{
  • "loyaltyMemberId": "11111-11111",
  • "publicLoyaltyMemberId": "11111-11111",
  • "profile": {
    },
  • "active": true,
  • "customAttributes": {
    },
  • "memberType": "organization",
  • "notifications": {
    },
  • "updateReason": "Updated member profile information",
  • "emitEvent": true
}

Response samples

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

Check matching audiences for a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
Request Body schema: application/json
required
audienceIds
required
Array of numbers

Responses

Request samples

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

Response samples

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

Get all matching audiences for a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string

Responses

Response samples

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

Check members existence

Authorizations:
bearer
Request Body schema: application/json
required
loyaltyMemberIds
required
Array of strings

List of loyaltyMemberId

Responses

Request samples

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

Response samples

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

Sets a manual loyalty tier for a member in a program

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
loyaltyProgramKey
required
string
Request Body schema: application/json
required
loyaltyTierKey
string

The key of the loyalty tier. If not specified, tier is unassigned

expiresAt
string <date-time>

Optional expiration date of the tier. At that expiration the tier will be re-evaluated.

externalId
string

The ID of the external event

systemUniqueKey
string

A unique key for the system

description
string

Description associated with the tier change

tags
Array of strings

Tags associated with the tier change

Responses

Request samples

Content type
application/json
{
  • "loyaltyTierKey": "string",
  • "expiresAt": "2027-02-26T02:18:13.117Z",
  • "externalId": "string",
  • "systemUniqueKey": "string",
  • "description": "string",
  • "tags": [
    ]
}

Response samples

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

Gets events for a loyalty member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=25

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

fromCreatedAt
string <date-time>

Filter events created from this date

toCreatedAt
string <date-time>

Filter events created up to this date

eventType
string
Enum: "member-purchase-order-created" "member-purchase-order-confirmed" "member-purchase-order-cancelled" "member-purchase-order-rejected" "member-purchase-order-returned" "member-purchase-order-partially-returned" "member-created" "member-updated" "member-profile-completed" "member-tier-set" "member-tier-removed" "member-profile-deactivated" "member-generic-event" "benefit-used" "coupon-code-assigned" "coupon-code-used" "badge-assigned" "badge-unassigned" "mission-status-updated" "ledger-transaction-created" "member-payment-confirmed"

Filter events by type

status
string
Enum: "pending" "running" "failed" "success"

Filter events by status

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Gets transactions for a loyalty member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=25

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

fromExternalEventDate
string <date-time>

Optional Reference From Event Date

toExternalEventDate
string <date-time>

Optional Reference To Event Date

ledgerAccountKey
string

Optional Ledger Account Key

systemUniqueKey
string

Optional System Unique Key for tracking

tags
string

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Get valid CMS documents for a member from a collection

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
collectionKeyOrSlug
required
string
query Parameters
page
number >= 0
Default: 0
Example: page=0

Page number (0-indexed)

limit
number [ 1 .. 200 ]
Default: 20
Example: limit=20

Number of results per page

sort
string
Example: sort=createdAt:desc

Sort field and direction (e.g., 'createdAt:desc', 'name:asc')

Responses

Response samples

Content type
application/json
{
  • "collection": {
    },
  • "query": {
    },
  • "totalCount": 10,
  • "items": [
    ],
  • "facets": {
    }
}

Events

Track loyalty events

Track loyalty events for members with configurable execution modes:

Execution Modes:

  • full (default): Complete evaluation and execution of all effects (points, tiers, missions, etc.)
  • dryRun: Simulation mode - evaluates effects without executing any changes
  • captureOnly: Persistence mode - skips effects evaluation, only creates event record and associated order/transaction data

Use Cases:

  • Use full for normal event processing with loyalty rewards
  • Use dryRun for testing and preview of what effects would be triggered
  • Use captureOnly for recording transactions without triggering loyalty effects (useful for historical data import or delayed processing)

Note: The dryRun parameter is deprecated. Use executionMode instead.

Authorizations:
bearer
Request Body schema: application/json
required
required
Array of objects (TrackOrganizationLoyaltyEventDto) [ 1 .. 100 ] items

Array of loyalty events to track

campaignKeys
Array of strings

Array of campaign keys to filter campaigns for evaluation

executionMode
string
Default: "full"
Enum: "full" "dryRun" "captureOnly" "authorize"

Execution mode for event processing

dryRun
boolean
Deprecated

DEPRECATED: Use executionMode instead. If true, the events will be processed but no actual changes will be made

Responses

Request samples

Content type
application/json
{
  • "events": [
    ],
  • "campaignKeys": [
    ],
  • "executionMode": "full",
  • "dryRun": false
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "executionMode": "full",
  • "dryRun": false
}

Track loyalty events asynchronously

Validates and stores the events, then enqueues them for asynchronous evaluation by a dedicated worker (batched, with retry + DLQ). Responds 202 with a per-event outcome (queued/rejected). The evaluation results (effects, ledger changes) are NOT returned here — they are delivered to a configured WebHook trigger. Correlate via the returned loyaltyEventKey.

Authorizations:
bearer
Request Body schema: application/json
required
required
Array of objects (TrackOrganizationLoyaltyEventDto) [ 1 .. 500 ] items

Array of loyalty events to store and process asynchronously

Array ([ 1 .. 500 ] items)
loyaltyMemberId
required
string

The loyalty member ID

sponsorLoyaltyMemberId
string
systemUniqueKey
required
string

System-wide unique key for the event

externalId
string
eventType
required
string

Type of the event

description
string
payload
object
externalEventDate
string <date-time>
tags
Array of strings

Responses

Request samples

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

Response samples

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

Cancel a loyalty event

Cancel a loyalty event and its effects (ledger transactions and limits/counters).

Cancellation Modes:

  • Full cancellation: Omit amount and items to cancel all effects of the event
  • Partial cancellation: Provide amount and/or items to cancel specific effects (coming soon)

The endpoint currently returns a discovery of child events with ledger transactions that would be cancelled.

Authorizations:
bearer
path Parameters
loyaltyEventKey
required
string
Request Body schema: application/json
required
description
string <= 255 characters

Optional description for the cancellation event

allowOverdraft
boolean
Default: false

Opt-in to let the revert of an already-spent mint drive the member's points balance into overdraft debt (instead of clamping to the available balance). Requires an overdraft-enabled account; used by the third-party (Pomelo) flow where the core must stay in debt until future earnings repay it.

Responses

Request samples

Content type
application/json
{
  • "description": "Order refunded by customer request",
  • "allowOverdraft": false
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "executionMode": "full",
  • "dryRun": false
}

Event Types

Lists event types available for selection — curated built-in types plus the organization's active custom event types.

Authorizations:
bearer

Responses

Response samples

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

Lists the organization's custom (non-built-in) loyalty event types.

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Creates a new custom loyalty event type.

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string
customAttributes
object
description
string
active
boolean
schemaType
required
string
Enum: "builtin" "string" "number" "url" "custom"

The type of schema that this event type uses.

apiCode
required
string [ 1 .. 255 ] characters /^[a-z0-9\-_.]+$/

Unique identifier within the organization. Must be non-empty and contain only lowercase alphanumeric characters, hyphens, underscores, and periods.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "customAttributes": { },
  • "description": "string",
  • "active": true,
  • "schemaType": "builtin",
  • "apiCode": "app-install"
}

Response samples

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

Gets a custom loyalty event type by its apiCode.

Authorizations:
bearer
path Parameters
apiCode
required
string

Responses

Response samples

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

Updates an existing custom loyalty event type.

Authorizations:
bearer
path Parameters
apiCode
required
string
Request Body schema: application/json
required
name
string
customAttributes
object
description
string
active
boolean
schemaType
string
Enum: "builtin" "string" "number" "url" "custom"

The type of schema that this event type uses.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "customAttributes": { },
  • "description": "string",
  • "active": true,
  • "schemaType": "builtin"
}

Response samples

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

Loyalty Points

Mint loyalty points

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
Request Body schema: application/json
required
amount
required
number >= 1

The amount of points to mint

systemUniqueKey
string <= 255 characters

The system unique key for the loyalty program

externalEventDate
string <date-time>

The date of the external event

description
string <= 255 characters

The description of the external event

tags
Array of strings

Optional tags for the event

fiatValue
number

Fiat value associated with the transaction

fiatGrossAmount
number

Fiat gross amount associated with the transaction

fiatCurrency
string <= 10 characters

Fiat currency code (e.g. USD, EUR)

force
boolean

If true, bypasses the inactive-member validation and allows minting/burning on a member whose organization-association is active = false. Only skips that specific check — member-not-found, account-not-found, balance-insufficient, etc. still apply. Default: false.

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "systemUniqueKey": "string",
  • "externalEventDate": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "tags": [
    ],
  • "fiatValue": 0,
  • "fiatGrossAmount": 0,
  • "fiatCurrency": "string",
  • "force": false
}

Response samples

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

Peer-to-peer transfer of loyalty points

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
Request Body schema: application/json
required
toLoyaltyMemberId
required
string >= 2 characters

The loyalty member ID to transfer points to

amount
required
number >= 1

The amount of points to transfer

systemUniqueKey
string <= 255 characters

The system unique key for the loyalty program

externalEventDate
string <date-time>

The date of the external event

description
string <= 255 characters

The description of the external event

tags
Array of strings

Optional tags for the event

fiatValue
number

Fiat value associated with the transaction

fiatGrossAmount
number

Fiat gross amount associated with the transaction

fiatCurrency
string <= 10 characters

Fiat currency code (e.g. USD, EUR)

Responses

Request samples

Content type
application/json
{
  • "toLoyaltyMemberId": "string",
  • "amount": 1,
  • "systemUniqueKey": "string",
  • "externalEventDate": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "tags": [
    ],
  • "fiatValue": 0,
  • "fiatGrossAmount": 0,
  • "fiatCurrency": "string"
}

Response samples

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

Burn loyalty points

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
Request Body schema: application/json
required
amount
required
number >= 1

The amount of points to mint

systemUniqueKey
string <= 255 characters

The system unique key for the loyalty program

externalEventDate
string <date-time>

The date of the external event

description
string <= 255 characters

The description of the external event

tags
Array of strings

Optional tags for the event

fiatValue
number

Fiat value associated with the transaction

fiatGrossAmount
number

Fiat gross amount associated with the transaction

fiatCurrency
string <= 10 characters

Fiat currency code (e.g. USD, EUR)

force
boolean

If true, bypasses the inactive-member validation and allows minting/burning on a member whose organization-association is active = false. Only skips that specific check — member-not-found, account-not-found, balance-insufficient, etc. still apply. Default: false.

captureMethod
string
Enum: "manual" "auto"

The capture method: manual or auto. Default is auto

allowOverdraft
boolean
Default: false

Opt-in to let a burn with shortfall drive the wallet into overdraft debt instead of failing Insufficient balance. Requires the account to be revolving with overdraftLimit > 0. Ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "systemUniqueKey": "string",
  • "externalEventDate": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "tags": [
    ],
  • "fiatValue": 0,
  • "fiatGrossAmount": 0,
  • "fiatCurrency": "string",
  • "force": false,
  • "captureMethod": "auto",
  • "allowOverdraft": false
}

Response samples

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

[Deprecated] Use POST /v2/accounts/:accountKeyOrAlias/txs/capture Deprecated

Capture loyalty points from default account. Points must have been burned with captureMethod = manual

Authorizations:
bearer
Request Body schema: application/json
required
required
Array of objects (TransactionCaptureDto)

The transactions to capture

Array
captureAmount
number >= 1

The amount of points to capture

ledgerTransactionId
required
string <= 255 characters

The ledger transaction id to capture

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "ok": true
}

[Deprecated] Use POST /v2/accounts/:accountKeyOrAlias/txs/revert Deprecated

Revert loyalty points from default account. Can only revert debit transactions and batch is processed as an atomic set.

Authorizations:
bearer
Request Body schema: application/json
required
required
Array of objects (RevertLoyaltyPointsDto)

The transactions to revert

Array
ledgerTransactionId
required
string <= 255 characters

The ledger transaction id to revert

systemUniqueKey
string <= 255 characters

The system unique key for the loyalty program

externalEventDate
string <date-time>

The date of the external event

description
string <= 255 characters

The description of the external event

tags
Array of strings

Optional tags for the event

Responses

Request samples

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

Response samples

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

List Member's Transactions

Get all member transactions

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=25

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

fromDate
string <date-time>

Optional Reference From Event Date

toDate
string <date-time>

Optional Reference To Event Date

fromLedgerTransactionId
number >= 1

Optional starting ledgerTransactionId (returns txs with id >= this)

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/points/txs?page=0&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Get nearest wallet expirations

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string

Responses

Response samples

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

Loyalty Cashback

Mint loyalty cashback

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
Request Body schema: application/json
required
amount
required
number >= 1

The amount of points to mint

systemUniqueKey
string <= 255 characters

The system unique key for the loyalty program

externalEventDate
string <date-time>

The date of the external event

description
string <= 255 characters

The description of the external event

tags
Array of strings

Optional tags for the event

fiatValue
number

Fiat value associated with the transaction

fiatGrossAmount
number

Fiat gross amount associated with the transaction

fiatCurrency
string <= 10 characters

Fiat currency code (e.g. USD, EUR)

force
boolean

If true, bypasses the inactive-member validation and allows minting/burning on a member whose organization-association is active = false. Only skips that specific check — member-not-found, account-not-found, balance-insufficient, etc. still apply. Default: false.

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "systemUniqueKey": "string",
  • "externalEventDate": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "tags": [
    ],
  • "fiatValue": 0,
  • "fiatGrossAmount": 0,
  • "fiatCurrency": "string",
  • "force": false
}

Response samples

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

Burn loyalty cashback

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
Request Body schema: application/json
required
amount
required
number >= 1

The amount of points to mint

systemUniqueKey
string <= 255 characters

The system unique key for the loyalty program

externalEventDate
string <date-time>

The date of the external event

description
string <= 255 characters

The description of the external event

tags
Array of strings

Optional tags for the event

fiatValue
number

Fiat value associated with the transaction

fiatGrossAmount
number

Fiat gross amount associated with the transaction

fiatCurrency
string <= 10 characters

Fiat currency code (e.g. USD, EUR)

force
boolean

If true, bypasses the inactive-member validation and allows minting/burning on a member whose organization-association is active = false. Only skips that specific check — member-not-found, account-not-found, balance-insufficient, etc. still apply. Default: false.

captureMethod
string
Enum: "manual" "auto"

The capture method: manual or auto. Default is auto

allowOverdraft
boolean
Default: false

Opt-in to let a burn with shortfall drive the wallet into overdraft debt instead of failing Insufficient balance. Requires the account to be revolving with overdraftLimit > 0. Ignored otherwise.

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "systemUniqueKey": "string",
  • "externalEventDate": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "tags": [
    ],
  • "fiatValue": 0,
  • "fiatGrossAmount": 0,
  • "fiatCurrency": "string",
  • "force": false,
  • "captureMethod": "auto",
  • "allowOverdraft": false
}

Response samples

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

List Member's Cashback Transactions

Get all member cashback transactions

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=25

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

fromDate
string <date-time>

Optional Reference From Event Date

toDate
string <date-time>

Optional Reference To Event Date

fromLedgerTransactionId
number >= 1

Optional starting ledgerTransactionId (returns txs with id >= this)

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Get nearest cashback wallet expirations

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string

Responses

Response samples

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

Loyalty Accounts

Capture loyalty points from specified account.

Capture loyalty points from specified account. Points must have been burned with captureMethod = manual

Authorizations:
bearer
path Parameters
accountKeyOrAlias
required
string
Request Body schema: application/json
required
required
Array of objects (TransactionCaptureDto)

The transactions to capture

Array
captureAmount
number >= 1

The amount of points to capture

ledgerTransactionId
required
string <= 255 characters

The ledger transaction id to capture

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "ok": true
}

Revert loyalty points from specified account.

Revert loyalty points from specified account. Can only revert debit transactions and batch is processed as an atomic set.

Authorizations:
bearer
path Parameters
accountKeyOrAlias
required
string
Request Body schema: application/json
required
required
Array of objects (RevertLoyaltyPointsDto)

The transactions to revert

Array
ledgerTransactionId
required
string <= 255 characters

The ledger transaction id to revert

systemUniqueKey
string <= 255 characters

The system unique key for the loyalty program

externalEventDate
string <date-time>

The date of the external event

description
string <= 255 characters

The description of the external event

tags
Array of strings

Optional tags for the event

Responses

Request samples

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

Response samples

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

Referral Programs

List all referral programs

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new referral program

Authorizations:
bearer
Request Body schema: application/json
required
loyaltyProgramKey
string <= 255 characters

Loyalty program key

name
required
string <= 255 characters

Name of the referral program

description
string <= 1000 characters

Description

pictureUrl
string <= 255 characters

Picture URL

customAttributes
object

Custom attributes

active
required
boolean

Whether the program is active

tags
Array of strings

Tags

code
required
string <= 255 characters

Unique code for the campaign

eventType
required
string <= 255 characters

Event type that triggers the referral

referrerPointsAccrual
number >= 0

Points accrual for the referrer

referrerLedgerKey
string <= 255 characters

Ledger key for the referrer reward

referrerLedgerAccountKey
string <= 255 characters

Ledger account key for the referrer reward

referrerCouponBookKey
string <= 255 characters

Coupon book key for the referrer reward

referredCount
number >= 1

Number of referred members required before the referrer is rewarded

referredPointsAccrual
number >= 0

Points accrual for the referred member

referredLedgerKey
string <= 255 characters

Ledger key for the referred member reward

referredLedgerAccountKey
string <= 255 characters

Ledger account key for the referred member reward

referredCouponBookKey
string <= 255 characters

Coupon book key for the referred member reward

validFromDate
string <date-time>

Valid from date

validToDate
string <date-time>

Valid to date

maxPerCode
required
number >= 1

Maximum number of times a code can be used

maxReferralsPerMember
number >= 1

Maximum referrals per member

maxRedeemsPerReferredMemberPerCode
number >= 1

Maximum times a referred member can redeem codes from this program

Responses

Request samples

Content type
application/json
{
  • "loyaltyProgramKey": "string",
  • "name": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "customAttributes": { },
  • "active": true,
  • "tags": [
    ],
  • "code": "string",
  • "eventType": "string",
  • "referrerPointsAccrual": 0,
  • "referrerLedgerKey": "string",
  • "referrerLedgerAccountKey": "string",
  • "referrerCouponBookKey": "string",
  • "referredCount": 1,
  • "referredPointsAccrual": 0,
  • "referredLedgerKey": "string",
  • "referredLedgerAccountKey": "string",
  • "referredCouponBookKey": "string",
  • "validFromDate": "2019-08-24T14:15:22Z",
  • "validToDate": "2019-08-24T14:15:22Z",
  • "maxPerCode": 1,
  • "maxReferralsPerMember": 1,
  • "maxRedeemsPerReferredMemberPerCode": 1
}

Response samples

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

Get a referral program by key

Authorizations:
bearer
path Parameters
referralProgramKey
required
string

Responses

Response samples

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

Update a referral program by key

Authorizations:
bearer
path Parameters
referralProgramKey
required
string
Request Body schema: application/json
required
loyaltyProgramKey
string <= 255 characters

Loyalty program key

name
required
string <= 255 characters

Name of the referral program

description
string <= 1000 characters

Description

pictureUrl
string <= 255 characters

Picture URL

customAttributes
object

Custom attributes

active
required
boolean

Whether the program is active

tags
Array of strings

Tags

code
required
string <= 255 characters

Unique code for the campaign

eventType
required
string <= 255 characters

Event type that triggers the referral

referrerPointsAccrual
number >= 0

Points accrual for the referrer

referrerLedgerKey
string <= 255 characters

Ledger key for the referrer reward

referrerLedgerAccountKey
string <= 255 characters

Ledger account key for the referrer reward

referrerCouponBookKey
string <= 255 characters

Coupon book key for the referrer reward

referredCount
number >= 1

Number of referred members required before the referrer is rewarded

referredPointsAccrual
number >= 0

Points accrual for the referred member

referredLedgerKey
string <= 255 characters

Ledger key for the referred member reward

referredLedgerAccountKey
string <= 255 characters

Ledger account key for the referred member reward

referredCouponBookKey
string <= 255 characters

Coupon book key for the referred member reward

validFromDate
string <date-time>

Valid from date

validToDate
string <date-time>

Valid to date

maxPerCode
required
number >= 1

Maximum number of times a code can be used

maxReferralsPerMember
number >= 1

Maximum referrals per member

maxRedeemsPerReferredMemberPerCode
number >= 1

Maximum times a referred member can redeem codes from this program

Responses

Request samples

Content type
application/json
{
  • "loyaltyProgramKey": "string",
  • "name": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "customAttributes": { },
  • "active": true,
  • "tags": [
    ],
  • "code": "string",
  • "eventType": "string",
  • "referrerPointsAccrual": 0,
  • "referrerLedgerKey": "string",
  • "referrerLedgerAccountKey": "string",
  • "referrerCouponBookKey": "string",
  • "referredCount": 1,
  • "referredPointsAccrual": 0,
  • "referredLedgerKey": "string",
  • "referredLedgerAccountKey": "string",
  • "referredCouponBookKey": "string",
  • "validFromDate": "2019-08-24T14:15:22Z",
  • "validToDate": "2019-08-24T14:15:22Z",
  • "maxPerCode": 1,
  • "maxReferralsPerMember": 1,
  • "maxRedeemsPerReferredMemberPerCode": 1
}

Response samples

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

Create a new referral code

Create a new referral code for a given loyalty member

Authorizations:
bearer
path Parameters
referralProgramKey
required
string
Request Body schema: application/json
required
codes
required
Array of strings[ items <= 255 characters ]

The codes to be created

loyaltyMemberId
required
string <= 255 characters

The loyalty member to be associated with the code

Responses

Request samples

Content type
application/json
{
  • "codes": [
    ],
  • "loyaltyMemberId": "string"
}

Response samples

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

List referral codes for a program

Optionally filter by loyalty member id

Authorizations:
bearer
path Parameters
referralProgramKey
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

loyaltyMemberId
string <= 255 characters

Filter codes by loyalty member id

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

List referral codes for a specific member in a program

Returns up to 50 referral codes owned by the given member. Used by dry-run testers to pre-populate the referral code field.

Authorizations:
bearer
path Parameters
referralProgramKey
required
string
loyaltyMemberId
required
string

Responses

Response samples

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

Get a referral code and its owner

Returns the referral code details and the loyalty member who owns it

Authorizations:
bearer
path Parameters
referralProgramKey
required
string
code
required
string

Responses

Response samples

Content type
application/json
{
  • "loyaltyMemberId": "string",
  • "code": "string",
  • "totalUsages": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

List members referred by a given code

Authorizations:
bearer
path Parameters
referralProgramKey
required
string
code
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Validate a referral code

Check if a referral code exists and has usages left

Authorizations:
bearer
path Parameters
referralProgramKey
required
string
code
required
string

Responses

Response samples

Content type
application/json
{
  • "isValid": true,
  • "code": "string",
  • "totalUsages": 0,
  • "maxUsages": 0,
  • "usagesLeft": 0,
  • "reason": "string"
}

Get referral members report for a program

Authorizations:
bearer
path Parameters
referralProgramKey
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Missions

Get organization's missions

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

type
string
codes
string
tags
string
loyaltyProgramKey
string

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/missions?page=0&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new mission

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string
shortDescription
string
description
string
pictureUrl
string
customAttributes
object
type
string
tags
Array of strings
code
required
string
active
boolean
validFrom
string <date-time>
validTo
string <date-time>
repetitionPeriod
string
periodLimit
number
pointsAccrual
number
couponBookKey
string
badgeKey
string

Badge key to assign to the member when the mission is achieved

ledgerTransactionDescription
string

Custom ledger transaction description used when mission accrues points

Array of strings or InlineMatcherDto (object)

Inline matcher. Can be a simple array of category codes (e.g. ['bebidas', 'snacks']) which means at least 1 of each (AND), or a full object with operator and conditions. Cannot be used together with matcherId.

object

Badge matcher. Only supported for badge-assigned / badge-unassigned event types. Defines badge balance conditions combined with AND/OR. Cannot be used together with matcherId or inlineMatcher.

minSpendValue
number >= 0

Minimum order total (payload.total) required for an event to count towards mission progress. Only supported for purchase-order and member-payment-confirmed event types. Matches the minSpendValue filter on smart campaigns.

object

Optional manual expiration applied to every mint produced by the mission's points reward. Same shape and semantics as the campaign-level manualExpiration: { value: positive integer, unit: 'days' | 'weeks' | 'months' }. Only valid when pointsAccrual > 0 (rejected with 400 otherwise); the target ledger account must have pointTrackingEnabled = true.

eventType
required
string <= 255 characters

Event Type to match. Accepts built-in event types (e.g. member-purchase-order-confirmed) and organization-scoped custom event apiCodes.

maxRepetitions
required
number >= 1

Max number of repetitions

goalCount
required
number >= 1

Goal count

loyaltyProgramKey
required
string
matcherKey
string
audienceKey
string
ledgerKey
string
ledgerAccountKey
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "shortDescription": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "customAttributes": { },
  • "type": "string",
  • "tags": [
    ],
  • "code": "string",
  • "active": true,
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "repetitionPeriod": "string",
  • "periodLimit": 0,
  • "pointsAccrual": 0,
  • "couponBookKey": "string",
  • "badgeKey": "string",
  • "ledgerTransactionDescription": "string",
  • "inlineMatcher": [
    ],
  • "badgeMatcher": {
    },
  • "minSpendValue": 50,
  • "manualExpiration": {
    },
  • "eventType": "member-purchase-order-confirmed",
  • "maxRepetitions": 10,
  • "goalCount": 3,
  • "loyaltyProgramKey": "string",
  • "matcherKey": "string",
  • "audienceKey": "string",
  • "ledgerKey": "string",
  • "ledgerAccountKey": "string"
}

Response samples

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

Get a mission by key

Authorizations:
bearer
path Parameters
missionKey
required
string

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/missions/{missionKey}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

Update an existing mission

Authorizations:
bearer
path Parameters
missionKey
required
string
Request Body schema: application/json
required
name
required
string
shortDescription
string
description
string
pictureUrl
string
customAttributes
object
type
string
tags
Array of strings
code
required
string
active
boolean
validFrom
string <date-time>
validTo
string <date-time>
pointsAccrual
number
couponBookKey
string
badgeKey
string

Badge key to assign to the member when the mission is achieved

ledgerTransactionDescription
string

Custom ledger transaction description used when mission accrues points

Array of strings or InlineMatcherDto (object)

Inline matcher. Can be a simple array of category codes (e.g. ['bebidas', 'snacks']) which means at least 1 of each (AND), or a full object with operator and conditions. Cannot be used together with matcherId.

object

Badge matcher. Only supported for badge-assigned / badge-unassigned event types. Defines badge balance conditions combined with AND/OR. Cannot be used together with matcherId or inlineMatcher.

minSpendValue
number >= 0

Minimum order total (payload.total) required for an event to count towards mission progress. Only supported for purchase-order and member-payment-confirmed event types. Matches the minSpendValue filter on smart campaigns.

object

Optional manual expiration applied to every mint produced by the mission's points reward. Same shape and semantics as the campaign-level manualExpiration: { value: positive integer, unit: 'days' | 'weeks' | 'months' }. Only valid when pointsAccrual > 0 (rejected with 400 otherwise); the target ledger account must have pointTrackingEnabled = true.

eventType
required
string <= 255 characters

Event Type to match. Accepts built-in event types (e.g. member-purchase-order-confirmed) and organization-scoped custom event apiCodes.

maxRepetitions
required
number >= 1

Max number of repetitions

goalCount
required
number >= 1

Goal count

loyaltyProgramKey
required
string
matcherKey
string
audienceKey
string
ledgerKey
string
ledgerAccountKey
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "shortDescription": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "customAttributes": { },
  • "type": "string",
  • "tags": [
    ],
  • "code": "string",
  • "active": true,
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "pointsAccrual": 0,
  • "couponBookKey": "string",
  • "badgeKey": "string",
  • "ledgerTransactionDescription": "string",
  • "inlineMatcher": [
    ],
  • "badgeMatcher": {
    },
  • "minSpendValue": 50,
  • "manualExpiration": {
    },
  • "eventType": "member-purchase-order-confirmed",
  • "maxRepetitions": 10,
  • "goalCount": 3,
  • "loyaltyProgramKey": "string",
  • "matcherKey": "string",
  • "audienceKey": "string",
  • "ledgerKey": "string",
  • "ledgerAccountKey": "string"
}

Response samples

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

Get member's missions

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

type
string
codes
string
tags
string
minTimesAchieved
number >= 0

Min number of times it has been achieved

minCounterCount
number >= 0

Min number of times the event has been triggered

available
boolean

Filter available missions

inProgress
boolean

If member started the mission but has not achieved it yet (even if she completed it in the past)

active
boolean

Filter missions with active status

validFrom
string <date-time>

Filter missions with valid from date

validTo
string <date-time>

Filter missions with valid to date

missionKey
string
loyaltyProgramKey
string

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/missions?page=0&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Campaigns

Get organization's campaigns

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

type
string
codes
string
tags
string
loyaltyProgramKey
string

Responses

Request samples 


      'https://api.sandbox.qurable.io/v2/campaigns?page=0&limit=10' \
      -H 'accept: application/json' \
      -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new campaign

Authorizations:
bearer
Request Body schema: application/json
required
code
required
string
active
boolean
name
required
string
description
string
pictureUrl
string
type
string
tags
Array of strings
enabledTopics
Array of strings
audienceKeys
Array of strings
daysOfWeek
Array of strings
locationCodes
Array of strings
loyaltyTierKeys
Array of strings
eventType
string
pointsMonthlyLimitPerMember
number
allowPartialApplicationOnLimit
boolean
maxTransactionsPerMember
number
Array of objects (CampaignLimitRuleDto)

Unified campaign limit rules — one entry per (scope, type, period, ledgerAccountKey) combination. Combine multiple rules to express e.g. {transactions, everything, 3} + {transactions, monthly, 1} + {points, monthly, 50000}. An event must pass every rule of its type to qualify. A points rule may target a specific account via ledgerAccountKey; omit it to target the program's default account. Prefer this over the deprecated maxTransactionsPerMember and pointsMonthlyLimitPerMember fields.

minSpendValue
number
customAttributes
object
smartRewards
object
validFrom
string <date-time>
validTo
string <date-time>
loyaltyProgramKey
string
Array of objects (CreateActionDto)

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "active": true,
  • "name": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "type": "string",
  • "tags": [
    ],
  • "enabledTopics": [
    ],
  • "audienceKeys": [
    ],
  • "daysOfWeek": [
    ],
  • "locationCodes": [
    ],
  • "loyaltyTierKeys": [
    ],
  • "eventType": "string",
  • "pointsMonthlyLimitPerMember": 0,
  • "allowPartialApplicationOnLimit": true,
  • "maxTransactionsPerMember": 0,
  • "limitRules": [
    ],
  • "minSpendValue": 0,
  • "customAttributes": { },
  • "smartRewards": { },
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "loyaltyProgramKey": "string",
  • "actions": [
    ]
}

Response samples

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

Get a campaign by key

Authorizations:
bearer
path Parameters
campaignKey
required
string

Responses

Request samples 


        curl -X 'GET' \
        'https://api.sandbox.qurable.io/v2/campaigns/{campaignKey}' \
        -H 'accept: application/json' \
        -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

Update an existing campaign

Authorizations:
bearer
path Parameters
campaignKey
required
string
Request Body schema: application/json
required
code
required
string
active
boolean
name
required
string
description
string
pictureUrl
string
type
string
tags
Array of strings
enabledTopics
Array of strings
audienceKeys
Array of strings
daysOfWeek
Array of strings
locationCodes
Array of strings
loyaltyTierKeys
Array of strings
eventType
string
pointsMonthlyLimitPerMember
number
allowPartialApplicationOnLimit
boolean
maxTransactionsPerMember
number
Array of objects (CampaignLimitRuleDto)

Unified campaign limit rules — one entry per (scope, type, period, ledgerAccountKey) combination. Combine multiple rules to express e.g. {transactions, everything, 3} + {transactions, monthly, 1} + {points, monthly, 50000}. An event must pass every rule of its type to qualify. A points rule may target a specific account via ledgerAccountKey; omit it to target the program's default account. Prefer this over the deprecated maxTransactionsPerMember and pointsMonthlyLimitPerMember fields.

minSpendValue
number
customAttributes
object
smartRewards
object
validFrom
string <date-time>
validTo
string <date-time>
Array of objects (UpdateActionWithKeyDtoV2)
loyaltyProgramKey
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "active": true,
  • "name": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "type": "string",
  • "tags": [
    ],
  • "enabledTopics": [
    ],
  • "audienceKeys": [
    ],
  • "daysOfWeek": [
    ],
  • "locationCodes": [
    ],
  • "loyaltyTierKeys": [
    ],
  • "eventType": "string",
  • "pointsMonthlyLimitPerMember": 0,
  • "allowPartialApplicationOnLimit": true,
  • "maxTransactionsPerMember": 0,
  • "limitRules": [
    ],
  • "minSpendValue": 0,
  • "customAttributes": { },
  • "smartRewards": { },
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "actions": [
    ],
  • "loyaltyProgramKey": "string"
}

Response samples

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

Actions

Get all actions for a campaign

Authorizations:
bearer
path Parameters
campaignKey
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

status
string
Enum: "disabled" "running" "draft"

The status of the action

campaignKey
string

Responses

Request samples 

curl -X GET "https://api.qurable.com/v2/campaigns/{campaignKey}/actions" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new action

Authorizations:
bearer
path Parameters
campaignKey
required
string
Request Body schema: application/json
required
campaignVersionId
number
actionIndex
number
abortEvaluationIfFalse
boolean
abortEvaluationOnError
boolean
name
required
string
rules
object
effects
required
object
status
required
string
Enum: "disabled" "running" "draft"
priority
required
number
exclusiveGroup
string

Responses

Request samples

Content type
application/json
{
  • "campaignVersionId": 0,
  • "actionIndex": 0,
  • "abortEvaluationIfFalse": true,
  • "abortEvaluationOnError": true,
  • "name": "string",
  • "rules": { },
  • "effects": { },
  • "status": "disabled",
  • "priority": 0,
  • "exclusiveGroup": "string"
}

Response samples

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

Get a specific action by key

Authorizations:
bearer
path Parameters
campaignKey
required
string
actionKey
required
string

Responses

Request samples 

curl -X GET "https://api.qurable.com/v2/campaigns/{campaignKey}/actions/{actionKey}" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Response samples

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

Update an existing action

Authorizations:
bearer
path Parameters
campaignKey
required
string
actionKey
required
string
Request Body schema: application/json
required
campaignVersionId
number
actionIndex
number
abortEvaluationIfFalse
boolean
abortEvaluationOnError
boolean
name
required
string
rules
object
effects
required
object
status
required
string
Enum: "disabled" "running" "draft"
priority
required
number
exclusiveGroup
string

Responses

Request samples

Content type
application/json
{
  • "campaignVersionId": 0,
  • "actionIndex": 0,
  • "abortEvaluationIfFalse": true,
  • "abortEvaluationOnError": true,
  • "name": "string",
  • "rules": { },
  • "effects": { },
  • "status": "disabled",
  • "priority": 0,
  • "exclusiveGroup": "string"
}

Response samples

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

Action Matchers

Get organization's action matchers

Authorizations:
bearer
query Parameters
type
string
Value: "item-matcher"
page
number
Default: 0
limit
number
Default: 10

Responses

Request samples 


      curl -X 'GET' \
      'https://api.sandbox.qurable.io/v2/action-matchers?page=0&limit=10' \
      -H 'accept: application/json' \
      -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "matchers": [
    ],
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0
}

Create a new action matcher

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string <= 255 characters

The name of the action matcher

type
required
string
Value: "item-matcher"

The type of the action matcher

matcher
required
object

The matcher configuration

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "item-matcher",
  • "matcher": { }
}

Response samples

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

Get an action matcher by key

Authorizations:
bearer
path Parameters
matcherKey
required
string

Responses

Request samples 


        curl -X 'GET' \
        'https://api.sandbox.qurable.io/v2/action-matchers/{matcherKey}' \
        -H 'accept: application/json' \
        -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

Update an existing action matcher

Authorizations:
bearer
path Parameters
matcherKey
required
string
Request Body schema: application/json
required
name
string <= 255 characters

The name of the action matcher

type
string
Value: "item-matcher"

The type of the action matcher

matcher
object

The matcher configuration

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "item-matcher",
  • "matcher": { }
}

Response samples

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

Smart Campaigns

Get Smart Campaign Conditions with pagination and filtering

Authorizations:
bearer
query Parameters
eventType
string
Example: eventType=member-payment-confirmed

Filter conditions by event type compatibility

Responses

Request samples 

curl -X 'GET' \
        'https://api.sandbox.qurable.io/v2/smart-campaigns/conditions?page=1&limit=10&category=Member&search=tier' \
        -H 'accept: application/json' \
        -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

Get Smart Campaign Effects with pagination and filtering

Authorizations:
bearer
query Parameters
eventType
string
Example: eventType=member-payment-confirmed

Filter effects by event type compatibility and compute supported accrual types

Responses

Request samples 

curl -X 'GET' \
        'https://api.sandbox.qurable.io/v2/smart-campaigns/effects?page=1&limit=10&category=Rewards&search=points' \
        -H 'accept: application/json' \
        -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Create a new smart campaign

Authorizations:
bearer
Request Body schema: application/json
required
code
required
string
active
boolean
name
required
string
description
string
pictureUrl
string
type
string
tags
Array of strings
enabledTopics
Array of strings
Deprecated

Deprecated: enabledTopics is automatically derived from eventType.

audienceKeys
Array of strings
daysOfWeek
Array of strings[ items [ 1 .. 7 ] ]

Days of week when campaign is active (1=Monday, 7=Sunday)

locationCodes
Array of strings

Location codes where campaign is active

loyaltyTierKeys
Array of strings
eventType
string
pointsMonthlyLimitPerMember
number
allowPartialApplicationOnLimit
boolean
maxTransactionsPerMember
number
Array of objects (CampaignLimitRuleDto)

Unified campaign limit rules — one entry per (scope, type, period, ledgerAccountKey) combination. Combine multiple rules to express e.g. {transactions, everything, 3} + {transactions, monthly, 1} + {points, monthly, 50000}. An event must pass every rule of its type to qualify. A points rule may target a specific account via ledgerAccountKey; omit it to target the program's default account. Prefer this over the deprecated maxTransactionsPerMember and pointsMonthlyLimitPerMember fields.

minSpendValue
number
customAttributes
object
smartRewards
object
validFrom
string <date-time>
validTo
string <date-time>
required
Array of objects (RewardConfigurationDto)

Array of reward configurations

loyaltyProgramKey
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "active": true,
  • "name": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "type": "string",
  • "tags": [
    ],
  • "enabledTopics": [
    ],
  • "audienceKeys": [
    ],
  • "daysOfWeek": [
    ],
  • "locationCodes": [
    ],
  • "loyaltyTierKeys": [
    ],
  • "eventType": "string",
  • "pointsMonthlyLimitPerMember": 0,
  • "allowPartialApplicationOnLimit": true,
  • "maxTransactionsPerMember": 0,
  • "limitRules": [
    ],
  • "minSpendValue": 0,
  • "customAttributes": { },
  • "smartRewards": { },
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "rewards": [
    ],
  • "loyaltyProgramKey": "string"
}

Response samples

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

Get a smart campaign by key

Authorizations:
bearer
path Parameters
campaignKey
required
string

Responses

Request samples 

curl -X 'GET' \
        'https://api.sandbox.qurable.io/v2/smart-campaigns/{campaignKey}' \
        -H 'accept: application/json' \
        -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

Update an existing smart campaign

Authorizations:
bearer
path Parameters
campaignKey
required
string
Request Body schema: application/json
required
code
required
string
active
boolean
name
required
string
description
string
pictureUrl
string
type
string
tags
Array of strings
enabledTopics
Array of strings
Deprecated

Deprecated: enabledTopics is automatically derived from eventType.

audienceKeys
Array of strings
daysOfWeek
Array of strings[ items [ 1 .. 7 ] ]

Days of week when campaign is active (1=Monday, 7=Sunday)

locationCodes
Array of strings

Location codes where campaign is active

loyaltyTierKeys
Array of strings
eventType
string
pointsMonthlyLimitPerMember
number
allowPartialApplicationOnLimit
boolean
maxTransactionsPerMember
number
Array of objects (CampaignLimitRuleDto)

Unified campaign limit rules — one entry per (scope, type, period, ledgerAccountKey) combination. Combine multiple rules to express e.g. {transactions, everything, 3} + {transactions, monthly, 1} + {points, monthly, 50000}. An event must pass every rule of its type to qualify. A points rule may target a specific account via ledgerAccountKey; omit it to target the program's default account. Prefer this over the deprecated maxTransactionsPerMember and pointsMonthlyLimitPerMember fields.

minSpendValue
number
customAttributes
object
smartRewards
object
validFrom
string <date-time>
validTo
string <date-time>
required
Array of objects (RewardConfigurationDto)

Array of reward configurations

loyaltyProgramKey
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "active": true,
  • "name": "string",
  • "description": "string",
  • "pictureUrl": "string",
  • "type": "string",
  • "tags": [
    ],
  • "enabledTopics": [
    ],
  • "audienceKeys": [
    ],
  • "daysOfWeek": [
    ],
  • "locationCodes": [
    ],
  • "loyaltyTierKeys": [
    ],
  • "eventType": "string",
  • "pointsMonthlyLimitPerMember": 0,
  • "allowPartialApplicationOnLimit": true,
  • "maxTransactionsPerMember": 0,
  • "limitRules": [
    ],
  • "minSpendValue": 0,
  • "customAttributes": { },
  • "smartRewards": { },
  • "validFrom": "2019-08-24T14:15:22Z",
  • "validTo": "2019-08-24T14:15:22Z",
  • "rewards": [
    ],
  • "loyaltyProgramKey": "string"
}

Response samples

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

Custom Effects

List all custom effects for the organization

Authorizations:
bearer

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "totalCount": 0
}

Create a new custom effect

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string <= 255 characters

Display name of the custom effect

description
string

Optional description

smartEffectKey
required
string <= 255 characters /^[a-z0-9]+(?:-[a-z0-9]+)*$/

Slugified key (kebab-case lowercase, auto-generated from name but user-editable)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "smartEffectKey": "string"
}

Response samples

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

Get a custom effect by key

Authorizations:
bearer
path Parameters
smartEffectKey
required
string

Responses

Response samples

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

Update an existing custom effect

Authorizations:
bearer
path Parameters
smartEffectKey
required
string
Request Body schema: application/json
required
name
string <= 255 characters
description
string
active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "active": true
}

Response samples

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

Member Purchase Orders

List member's purchase orders

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

fromDate
string <date-time>

Filter purchase orders from this date

toDate
string <date-time>

Filter purchase orders up to this date

includeItems
boolean

Include purchase order items in the response

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/purchase-orders?page=0&limit=10' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Get purchase order stats for a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
period
required
string
Enum: "days" "weeks" "months" "current-week" "current-month" "current-quarter" "current-year" "previous-week" "previous-month" "previous-quarter" "previous-year" "last-month" "last-year"

Period type. Relative: days, weeks, months (require periodCount). Current (to date): current-week, current-month, current-quarter, current-year. Previous (full period): previous-week, previous-month, previous-quarter, previous-year, last-month, last-year.

last
number >= 1
Default: 30

Number of periods to look back (only for relative periods: days, weeks, months). Ignored for absolute periods. Max 6 months equivalent.

Responses

Response samples

Content type
application/json
{
  • "period": "string",
  • "last": 0,
  • "totals": {
    },
  • "daily": [
    ]
}

Get a member's purchase order by ID

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
orderId
required
string

Responses

Request samples 


curl -X 'GET' \
  'https://api.sandbox.qurable.io/v2/members/{loyaltyMemberId}/purchase-orders/{orderId}' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

Member Payments

Get payment stats for a member

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
query Parameters
period
required
string
Enum: "days" "weeks" "months" "current-week" "current-month" "current-quarter" "current-year" "previous-week" "previous-month" "previous-quarter" "previous-year" "last-month" "last-year"

Period type. Relative: days, weeks, months (require periodCount). Current (to date): current-week, current-month, current-quarter, current-year. Previous (full period): previous-week, previous-month, previous-quarter, previous-year, last-month, last-year.

last
number >= 1
Default: 30

Number of periods to look back (only for relative periods: days, weeks, months). Ignored for absolute periods. Max 6 months equivalent.

Responses

Response samples

Content type
application/json
{
  • "period": "string",
  • "last": 0,
  • "totals": {
    },
  • "daily": [
    ]
}

Event Triggers

List all event triggers

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

type
string
Enum: "WebHook" "EntityChangeWebhook" "AsyncTrackWebhook"

Filter by trigger type

active
boolean

Filter by active status

name
string <= 255 characters

Filter by trigger name

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new event trigger

Authorizations:
bearer
Request Body schema: application/json
required
type
required
string
Enum: "WebHook" "EntityChangeWebhook" "AsyncTrackWebhook"

Trigger type

name
required
string <= 255 characters

Human-readable trigger name

required
object

Trigger settings: destination URL, optional version, event filter, and custom headers. If supplied on update, the entire settings object must be valid (including url); partial settings objects are not supported.

active
boolean

Whether the trigger is active. Defaults to true

Responses

Request samples

Content type
application/json
{
  • "type": "WebHook",
  • "name": "string",
  • "settings": {},
  • "active": true
}

Response samples

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

Get an event trigger by key

Authorizations:
bearer
path Parameters
triggerKey
required
string

Responses

Response samples

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

Update an event trigger by key

Authorizations:
bearer
path Parameters
triggerKey
required
string
Request Body schema: application/json
required
type
string
Enum: "WebHook" "EntityChangeWebhook" "AsyncTrackWebhook"

Trigger type

name
string <= 255 characters

Human-readable trigger name

object

Trigger settings: destination URL, optional version, event filter, and custom headers. If supplied on update, the entire settings object must be valid (including url); partial settings objects are not supported.

active
boolean

Whether the trigger is active. Defaults to true

Responses

Request samples

Content type
application/json
{
  • "type": "WebHook",
  • "name": "string",
  • "settings": {},
  • "active": true
}

Response samples

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

Tier Rules

Create or update tier-segment configuration with tier mappings

Validates that each tier's segment BigQuery window aligns with the configured schedules. Use ?validation=strict (default) to block invalid configs, ?validation=loose to save with warnings, or ?validation=skip to bypass.

Authorizations:
bearer
query Parameters
validation
string
Enum: "strict" "loose" "skip"

Segment/schedule alignment validation. Default: strict. strict = errors block, warnings returned; loose = errors downgraded to warnings; skip = no validation.

Request Body schema: application/json
required
object (TierAudienceScheduleDto)
object (TierAudienceScheduleDto)
downgradeGraceCycle
boolean
Default: false

Give members one full downgrade cycle to re-qualify before downgrading

evaluationReference
string
Default: "calendar"
Enum: "calendar" "enrollment"
active
boolean
Default: true
upgradePaused
boolean
Default: false
downgradePaused
boolean
Default: false
required
Array of objects (TierAudienceMappingDto)

Segment mapping for each non-base tier

Responses

Request samples

Content type
application/json
{
  • "upgradeSchedule": {
    },
  • "downgradeSchedule": {
    },
  • "downgradeGraceCycle": false,
  • "evaluationReference": "calendar",
  • "active": true,
  • "upgradePaused": false,
  • "downgradePaused": false,
  • "tiers": [
    ]
}

Get tier-segment configuration with tier mappings

Authorizations:
bearer

Responses

Remove tier-segment configuration and all tier mappings

Authorizations:
bearer

Responses

List tier evaluations with filters

Authorizations:
bearer
query Parameters
status
string
Enum: "pending" "completed" "skipped" "failed"
mode
string
Enum: "upgrade" "downgrade" "requalified"
currentTierKey
string
calculatedTierKey
string
fromDate
string

ISO date (default: 30 days ago)

toDate
string

ISO date (default: today)

sortBy
string
Enum: "date" "currentTier" "calculatedTier"

Default: date

sortOrder
string
Enum: "asc" "desc"

Default: desc

page
number
limit
number

Responses

Get evaluation summary with totals by status and tier

Authorizations:
bearer
query Parameters
fromDate
string

ISO date (default: 30 days ago)

toDate
string

ISO date (default: today)

Responses

Tier Lock

Lock a member's tier to prevent automated changes

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string
Request Body schema: application/json
required
lockedUntil
string

Auto-unlock date. Omit for indefinite lock

reason
string

Reason for locking

Responses

Request samples

Content type
application/json
{
  • "lockedUntil": "string",
  • "reason": "string"
}

Unlock a member's tier

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string

Responses

Get member's current tier status with lock and grace info

Authorizations:
bearer
path Parameters
loyaltyMemberId
required
string

Responses

Insights

List available stored queries

Returns the active stored-query catalog with each query's parameter contract (name, label, type, multiple, required, default) for form rendering. The underlying SQL is never returned. Pass an optional comma-separated keys query param to restrict the result to specific stored queries (unknown keys are ignored), and/or allowWidgets (true/false) to filter on the widget-allowed flag.

Authorizations:
bearer
query Parameters
keys
Array of strings
Example: keys=members-by-signup-date,members-by-churn-score

Optional comma-separated list of stored-query keys to filter the catalog by (at most 1000). Unknown keys are ignored. Omit to return the full active catalog.

allowWidgets
boolean
Example: allowWidgets=true

Optional filter on the allowWidgets flag. true returns only widget-allowed queries, false only disallowed ones; omit for all.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a stored query by key

Returns a single active stored query's metadata and parameter contract. The underlying SQL is never returned. 404 if the key is unknown or inactive.

Authorizations:
bearer
path Parameters
key
required
string

Responses

Response samples

Content type
application/json
{
  • "key": "members-by-signup-date",
  • "name": "Members by signup date",
  • "description": "string",
  • "type": "oltp",
  • "params": [
    ],
  • "allowWidgets": true
}

Execute a stored query

Runs the stored query with the supplied parameters and offset pagination. Organization scope is always derived from the authenticated token. Returns a tabular columns + rows result with pagination metadata.

Authorizations:
bearer
path Parameters
key
required
string
Request Body schema: application/json
required
object

Parameter values keyed by parameter name. Omitted params fall back to their declared default; optional params with no default are treated as 'no filter'. Scalars take a single value; multiple params take an array.

pageSize
number [ 1 .. 1000 ]
Default: 50

Page size for offset pagination. Defaults to 50, clamped to 1000.

pageToken
string

Opaque cursor for the next page — copy metadata.nextPageToken from the previous response. Omit on the first page. Encodes a row offset; treat it as opaque.

Responses

Request samples

Content type
application/json
{
  • "params": {
    },
  • "pageSize": 50,
  • "pageToken": "string"
}

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "rows": [
    ],
  • "metadata": {
    }
}

Export a warehouse stored query to CSV (async)

Runs a warehouse stored query to completion and writes the full result as a single GZIP-compressed CSV to cloud storage via a BigQuery export job. Returns immediately with an exportId; poll the status endpoint until the export is COMPLETED to obtain a download URL. Only warehouse stored queries are supported (400 otherwise).

Authorizations:
bearer
path Parameters
key
required
string
Request Body schema: application/json
required
object

Parameter values keyed by parameter name. Omitted params fall back to their declared default; optional params with no default are treated as 'no filter'. Scalars take a single value; multiple params take an array.

property name*
additional property
any

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "exportId": "sqx_01JABCDEF...",
  • "status": "RUNNING",
  • "createdAt": "2019-08-24T14:15:22Z"
}

Get the status of a stored-query export

Returns the current state of an export. While running, the underlying warehouse job is polled. Once COMPLETED, a short-lived signed file.downloadUrl is returned (re-poll to refresh an expired URL). The CSV is deleted 24h after creation.

Authorizations:
bearer
path Parameters
exportId
required
string

Responses

Response samples

Content type
application/json
{
  • "exportId": "sqx_01JABCDEF...",
  • "storedQueryKey": "members-by-churn-score",
  • "status": "PENDING",
  • "rowCount": 0,
  • "bytesProcessed": 0,
  • "file": {
    },
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "errorMessage": "string",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Execute a grouped report query against the data warehouse

Long grouped report: dimensions form the GROUP BY key and measures are aggregated per group, yielding one output row per distinct dimension tuple. Desugars to a single grouped warehouse query. Supports execute, validate (dry-run), and export (long result to CSV) modes. Organization scope is always derived from the authenticated token.

Authorizations:
bearer
Request Body schema: application/json
required
required
object

Query definition.

mode
string
Default: "execute"
Enum: "execute" "validate" "export"

Execution mode. execute returns the long result; validate dry-runs the compiled SQL (soft result with valid + error); export writes the long result asynchronously to CSV and returns an exportId to poll.

Responses

Request samples

Content type
application/json
{
  • "definition": {
    },
  • "mode": "execute"
}

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "rows": [
    ],
  • "metadata": {
    }
}

Insights Query MCP

Insights query MCP endpoint (JSON-RPC 2.0, stateless)

Model Context Protocol server for building report queries. Accepts a single JSON-RPC request and returns a single JSON-RPC response (200). A JSON-RPC notification (no id) is accepted with 202 and no body, per the Streamable HTTP transport. JSON-RPC batches (request arrays) are NOT supported — send one request per call. Supported methods: initialize, ping, tools/list, tools/call.

Authorizations:
bearer
Request Body schema: application/json
required
jsonrpc
required
string
method
required
string
id
object
params
object

Responses

Request samples

Content type
application/json
{
  • "jsonrpc": "string",
  • "method": "string",
  • "id": { },
  • "params": { }
}

Segment Management

Create a new segment

Creates a new segment with an automatically linked list-matcher audience. The segment defines membership refresh schedules and configuration.

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

Name of the segment

description
string <= 1000 characters

Description of the segment

refreshType
string (SegmentRefreshType)
Default: "once"
Enum: "once" "daily" "weekly" "monthly"

The refresh schedule for BigQuery segments. ONCE: run once, then stop. DAILY/WEEKLY/MONTHLY: recurring. Ignored for CSV import segments.

autoRefreshEnabled
boolean
Default: true

Whether scheduled auto-refresh is enabled for the new BigQuery segment. Defaults to true.

tags
string

Tags associated with the segment

definition
object

DSL-based audience definition for complex segmentation queries

Responses

Request samples

Content type
application/json
{
  • "name": "VIP Customers",
  • "description": "High-value customers with over $1000 in purchases",
  • "refreshType": "once",
  • "autoRefreshEnabled": true,
  • "tags": "VIP,High-value",
  • "definition": {
    }
}

Response samples

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

Get all segments for the organization

Retrieves a paginated list of segments with support for filtering by active status and searching by name/description.

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

autoRefreshEnabled
boolean
Example: autoRefreshEnabled=true

Filter by whether scheduled auto-refresh is enabled. Excludes CSV imports (auto-refresh is not applicable).

refreshType
string
Enum: "once" "daily" "weekly" "monthly"

Filter by exact refresh type (once, daily, weekly, monthly)

search
string
Example: search=VIP

Search segments by name or description

tags
string
Example: tags=VIP,High-value

Filter segments that contain any of the provided tags

segmentType
string
Enum: "bigquery" "csv_import"

Filter by segment type

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Get a segment by key

Authorizations:
bearer
path Parameters
segmentKey
required
string

Segment key

Responses

Response samples

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

Update a segment

Updates segment properties. Changes to name and description are automatically synchronized to the linked audience.

Authorizations:
bearer
path Parameters
segmentKey
required
string
Example: seg_01H9X8Y7Z6P5Q4R3S2T1V0W9

Unique segment identifier

Request Body schema: application/json
required
version
number >= 1

Segment version number for optimistic locking

Responses

Request samples

Content type
application/json
{
  • "version": 2
}

Response samples

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

Audience List

Get a set of members from an audience with pagination support

Authorizations:
bearer
path Parameters
audienceKey
required
string

Audience key

query Parameters
limit
number [ 1 .. 1000 ]
Default: 100
Example: limit=100

Maximum number of members to return (1-1000)

lastEvaluatedKey
string
Example: lastEvaluatedKey=eyJtZW1iZXJJZCI6MTIzLCJhdWRpZW5jZUtleSI6ImF1ZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9

Pagination token from previous response to get next page of results (base64 encoded)

Responses

Response samples

Content type
application/json
{
  • "members": [
    ],
  • "lastEvaluatedKey": "eyJtZW1iZXJJZCI6MTIzLCJhdWRpZW5jZUtleSI6ImF1ZF8wMUFSWjNOREVLVFNWNFJSRkZRNjlHNUZBViJ9",
  • "count": 100
}

Audiences

Get organization's audiences

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

matcherType
string
Enum: "attribute-matcher" "list-matcher" "null-matcher"

Filter by matcher type

active
boolean

Filter audiences by active status. When true, also excludes audiences whose expiresAt is in the past.

search
string
Example: search=VIP customers

Search audiences by name or description

audienceKeys
string
Example: audienceKeys=aud_123,aud_456,aud_789

Filter audiences by specific audience keys (comma-separated)

includeSegmentData
boolean

Include segment data (segmentType) in the response

Responses

Request samples 


      curl -X 'GET' \
      'https://api.sandbox.qurable.io/v2/audiences?page=0&limit=10' \
      -H 'accept: application/json' \
      -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new audience

Authorizations:
bearer
Request Body schema: application/json
required
active
required
boolean
name
required
string
description
string
matcherType
required
string
Enum: "attribute-matcher" "list-matcher" "null-matcher"
AttributeMatcherDto (object)

Matcher configuration. Required when matcherType is attribute-matcher.

segmentKey
string
refreshedAt
string <date-time>
expiresAt
string <date-time>
memberCount
number

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "name": "string",
  • "description": "string",
  • "matcherType": "attribute-matcher",
  • "matcher": {
    },
  • "segmentKey": "string",
  • "refreshedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "memberCount": 0
}

Response samples

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

Check where an audience is referenced

Returns whether the audience is referenced in any campaign, mission, CMS document, coupon book, or survey belonging to the organization. Campaigns of type mission and referral are excluded from the campaign results and reported separately under missions. Includes full details of each reference location. Intended to be called before unpublishing an audience.

Authorizations:
bearer
path Parameters
audienceKey
required
string
Example: aud_01j...

The key of the audience to check

Responses

Response samples

Content type
application/json
{
  • "isReferenced": true,
  • "references": {
    }
}

Get an audience by key

Authorizations:
bearer
path Parameters
audienceKey
required
string

Responses

Request samples 


        curl -X 'GET' \
        'https://api.sandbox.qurable.io/v2/audiences/{audienceKey}' \
        -H 'accept: application/json' \
        -H 'Authorization: Bearer {YOUR_TOKEN}'

Response samples

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

Update an existing audience

Authorizations:
bearer
path Parameters
audienceKey
required
string
Request Body schema: application/json
required
active
boolean
name
string
description
string
matcherType
string
Enum: "attribute-matcher" "list-matcher" "null-matcher"
AttributeMatcherDto (object)

Matcher configuration. Required when matcherType is attribute-matcher.

segmentKey
string
refreshedAt
string <date-time>
expiresAt
string <date-time>
memberCount
number

Responses

Request samples

Content type
application/json
{
  • "active": true,
  • "name": "string",
  • "description": "string",
  • "matcherType": "attribute-matcher",
  • "matcher": {
    },
  • "segmentKey": "string",
  • "refreshedAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z",
  • "memberCount": 0
}

Response samples

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

Segment Definitions

Get the semantic data model

Returns the semantic data model definition including available facts, dimensions, and their attributes. This model can be used to construct segment definitions. The model may be customized per organization based on custom semantic model configuration.

Authorizations:
bearer

Responses

Response samples

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

Estimate member count for a segment definition

Estimates the number of members that would match the given segment definition. Also returns the total organization member count and the percentage of members that match.

Authorizations:
bearer
Request Body schema: application/json
required
definition
required
object

Unified audience DSL. Estimate is intentionally projection-free: the endpoint always produces member-keyed rows and rejects any request that includes projections, picks a non-audience model, or sets projectedDimension to something incoherent with the model's root dim. from must be omitted or members (the only audience model). Analytics models belong to POST /v2/insights/query.

previewAttributes
Array of strings

Optional member-row preview. When provided, the response also includes preview: up to 50 sample members matching the audience, projecting these attributes. Must be DIRECT, non-internal member attributes (e.g. loyaltyMemberId, name, country). The count is unaffected.

Responses

Request samples

Content type
application/json
{
  • "definition": {
    },
  • "previewAttributes": [
    ]
}

Response samples

Content type
application/json
{
  • "estimation": {
    },
  • "preview": [
    ]
}

Get available values for a dimension

Returns paginated and searchable values for a specific dimension within the organization context. Supported dimensions: memberGender, memberType, memberTag, tier, purchaseLocation, purchaseTag. Supports pagination (page, limit) and case-insensitive search by name.

Authorizations:
bearer
path Parameters
dimensionKey
required
string
query Parameters
page
number >= 1
Default: 1
Example: page=1

Page number (1-indexed)

limit
number [ 1 .. 1000 ]
Default: 100
Example: limit=100

Items per page

search
string
Example: search=gold

Search term for dimension value names (case-insensitive)

Responses

Response samples

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

CSV Import

Create CSV import segment with presigned URL

Creates a new CSV import segment and returns a presigned S3 URL for uploading the CSV file

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string <= 255 characters

Segment name

description
string <= 1000 characters

Segment description

fileName
required
string

CSV file name

fileSize
required
number [ 1 .. 104857600 ]

File size in bytes

identifierColumn
required
string

CSV column name containing member identifiers

identifierType
required
string
Enum: "loyaltyMemberId" "publicLoyaltyMemberId" "email" "memberId" "govId"

Type of identifier in the CSV column

Responses

Request samples

Content type
application/json
{
  • "name": "Employee List Q1 2025",
  • "description": "Quarterly employee list update",
  • "fileName": "employees.csv",
  • "fileSize": 1048576,
  • "identifierColumn": "email",
  • "identifierType": "email"
}

Response samples

Content type
application/json
{}

Upload CSV to existing segment

Generates a presigned S3 URL for uploading a new CSV file to an existing CSV import segment

Authorizations:
bearer
path Parameters
segmentKey
required
string

Segment key

Request Body schema: application/json
required
fileName
required
string

CSV file name

fileSize
required
number [ 1 .. 104857600 ]

File size in bytes

identifierColumn
required
string

CSV column name containing member identifiers

identifierType
required
string
Enum: "loyaltyMemberId" "publicLoyaltyMemberId" "email" "memberId" "govId"

Type of identifier in the CSV column

Responses

Request samples

Content type
application/json
{
  • "fileName": "employees.csv",
  • "fileSize": 1048576,
  • "identifierColumn": "email",
  • "identifierType": "email"
}

Response samples

Content type
application/json
{}

List all CSV import jobs for a segment

Returns all import jobs for the given segment, ordered by creation date (newest first)

Authorizations:
bearer
path Parameters
segmentKey
required
string

Segment key

query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Get CSV import job status

Returns the current status and progress of a CSV import job

Authorizations:
bearer
path Parameters
segmentKey
required
string

Segment key

jobId
required
string

Job ID

Responses

Response samples

Content type
application/json
{
  • "segment": {
    },
  • "job": {
    }
}

Activation Targets

List activation targets for the organization. By default returns active targets only.

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

activeOnly
boolean

When true, only active (non-deleted) targets are returned. Defaults to true.

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new activation target.

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string [ 1 .. 120 ] characters

Display name for the target. Unique per organization.

targetType
required
string
Value: "webhook"

Target type. Only webhook is a creatable target — grant_points is a targetless job action, not a target.

required
object

Type-specific configuration. Validated by the target type registry on the server side; reject as 422 with field-level details on mismatch.

projectionFields
Array of strings

Optional projection contract: list of member-attribute paths this receiver supports (e.g. ["email", "name", "customAttributes.tier"]). Jobs targeting this target must project a subset; specifying a field outside this list at job create/update returns 422. An empty array / omitted means "no contract declared" — jobs may project any path in the global whitelist.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "targetType": "webhook",
  • "config": { },
  • "projectionFields": [
    ]
}

Response samples

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

Fetch a single activation target by id.

Authorizations:
bearer
path Parameters
id
required
string

Responses

Response samples

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

Update name and/or config of an existing target. The target type cannot be changed once set.

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
name
string [ 1 .. 120 ] characters

Display name for the target. Unique per organization.

object

Type-specific configuration. Validated by the target type registry on the server side; reject as 422 with field-level details on mismatch.

projectionFields
Array of strings

Optional projection contract: list of member-attribute paths this receiver supports (e.g. ["email", "name", "customAttributes.tier"]). Jobs targeting this target must project a subset; specifying a field outside this list at job create/update returns 422. An empty array / omitted means "no contract declared" — jobs may project any path in the global whitelist.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "config": { },
  • "projectionFields": [
    ]
}

Response samples

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

Soft-delete an activation target. Refused with 409 if any non-terminal job still references the target.

Authorizations:
bearer
path Parameters
id
required
string

Responses

Activation Jobs

List activation jobs for the organization.

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

targetId
string

Filter by activation target id.

actionType
string

Filter by delivery action (e.g. webhook, grant_points, grant_coupon) so each UI scopes the shared jobs list to its own type. Free string — decoupled from the supported-type list.

active
boolean

Filter by active state (defaults to all).

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new activation job. For AUDIENCE-sourced jobs, seeds the first execution row and enqueues the snapshot materialization. For EXPLICIT_MEMBERS jobs, only the configuration is persisted — executions are created on demand by POST /:id/execute.

Authorizations:
bearer
Request Body schema: application/json
required
targetId
string

Delivery target for a target-backed action (webhook). Omit for a targetless action, in which case actionType is required.

actionType
string
Enum: "webhook" "grant_points" "grant_coupon"

Targetless action to run (grant_points or grant_coupon). Required when targetId is omitted; ignored otherwise.

name
required
string [ 1 .. 120 ] characters
required
object

Where the member list comes from. AUDIENCE materializes a snapshot of the audience and reuses it across executions; EXPLICIT_MEMBERS accepts a caller-supplied member list per execution via the explicit-execute endpoint.

object
projectionFields
Array of strings

Flat list of projection paths. Must be a subset of the target's projectionFields contract; otherwise 422. Empty / omitted = use the target's full contract at delivery time.

object

Free-form per-job config. For webhook targets, the renderable text (keys per the target's messageSchema — title/description for notification, subject/htmlBody/preheader for email) may embed {{ field }} placeholders resolved per member at delivery; any placeholder referencing a non-whitelisted field is rejected with 422.

Responses

Request samples

Content type
application/json
{
  • "targetId": "string",
  • "actionType": "webhook",
  • "name": "string",
  • "source": {
    },
  • "scheduleConfig": { },
  • "projectionFields": [
    ],
  • "runConfig": { }
}

Response samples

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

Execute an EXPLICIT_MEMBERS job against a caller-supplied member list. Creates one execution directly in RUNNING (bypassing the scheduler READY-promotion), seeds tracking rows, and enqueues delivery. Rejected (409) for AUDIENCE-sourced jobs.

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
memberIds
required
Array of strings [ 1 .. 1000 ] items

Loyalty member ids to deliver in this execution. Duplicates are deduplicated server-side. Inactive members are marked SKIPPED on the first claim; a member missing from the read replica gets one retry (replica-lag tolerance) and is marked SKIPPED if the following claim still cannot find it.

Responses

Request samples

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

Response samples

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

Fetch a single activation job by id.

Authorizations:
bearer
path Parameters
id
required
string

Responses

Response samples

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

Update an activation job's configuration.

Authorizations:
bearer
path Parameters
id
required
string
Request Body schema: application/json
required
name
string [ 1 .. 120 ] characters
object

Update the membership source. Changing type between AUDIENCE and EXPLICIT_MEMBERS is rejected (409) because it would invalidate any in-flight executions; only the audienceKey may change within AUDIENCE.

object
projectionFields
Array of strings

Flat list of projection paths. Must be a subset of the target's contract; otherwise 422.

object

Free-form per-job config. For webhook targets, the renderable text (keys per the target's messageSchema — title/description for notification, subject/htmlBody/preheader for email) may embed {{ field }} placeholders resolved per member at delivery; any placeholder referencing a non-whitelisted field is rejected with 422.

active
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "source": {
    },
  • "scheduleConfig": { },
  • "projectionFields": [
    ],
  • "runConfig": { },
  • "active": true
}

Response samples

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

Soft-delete (deactivate) an activation job.

Authorizations:
bearer
path Parameters
id
required
string

Responses

List executions (runs) of an activation job.

Authorizations:
bearer
path Parameters
id
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Default: 100
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

status
Array of strings
Items Enum: "PENDING_MATERIALIZATION" "READY" "RUNNING" "COMPLETED" "PARTIALLY_FAILED" "FAILED" "CANCELLED"

Filter by status. Repeat to combine: ?status=COMPLETED&status=PARTIALLY_FAILED.

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Fetch a single execution by id.

Authorizations:
bearer
path Parameters
id
required
string
executionId
required
string

Responses

Response samples

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

List the per-member tracking rows for an execution. Combine with `?status=FAILED` to triage partially failed executions.

Authorizations:
bearer
path Parameters
id
required
string
executionId
required
string
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 500 ]
Default: 100
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

status
Array of strings
Items Enum: "PENDING" "IN_FLIGHT" "DELIVERED" "FAILED" "SKIPPED"

Filter by tracking status. Most useful as ?status=FAILED for triage of partially failed executions.

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Ledgers

Gets a single Ledger for the current organization.

Authorizations:
bearer
path Parameters
ledgerKey
required
string
header Parameters
X-Q-Forwarded-Org
string

Organization Key

X-Q-Forwarded-User
string

User Key

Responses

Response samples

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

Updates a single Ledger in the current organization.

Authorizations:
bearer
path Parameters
ledgerKey
required
string
header Parameters
X-Q-Forwarded-Org
string

Organization Key

X-Q-Forwarded-User
string

User Key

Request Body schema: application/json
required
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "Main Loyalty Program Ledger",
  • "description": "This is the main Loyalty Program Ledger"
}

Response samples

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

Gets all Ledgers for the current organization.

Authorizations:
bearer
query Parameters
page
number >= 0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

header Parameters
X-Q-Forwarded-Org
string

Organization Key

X-Q-Forwarded-User
string

User Key

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Creates a single Ledger in the current organization.

Authorizations:
bearer
header Parameters
X-Q-Forwarded-Org
string

Organization Key

X-Q-Forwarded-User
string

User Key

Request Body schema: application/json
required
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "Main Loyalty Program Ledger",
  • "description": "This is the main Loyalty Program Ledger"
}

Response samples

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

Ledger Accounts

Gets all Ledger's Accounts

Authorizations:
bearer
path Parameters
ledgerKey
required
string
query Parameters
page
number >= 0

The page number for pagination

limit
number [ 1 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

name
string
ledgerAccountKey
string

Ledger Account Key

alias
string

Account Alias

header Parameters
X-Q-Forwarded-Org
string

Organization Key

X-Q-Forwarded-User
string

User Key

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Creates a single Ledger Account

Authorizations:
bearer
path Parameters
ledgerKey
required
string
header Parameters
X-Q-Forwarded-Org
string

Organization Key

X-Q-Forwarded-User
string

User Key

Request Body schema: application/json
required
alias
string

Account alias for easier lookup

name
required
string
active
required
boolean
isCurrency
boolean

Optional Is a currency? for account

decimals
number

Optional decimals

formatString
string

Optional Format string for points

maxSupply
number

Max points supply available (max allowed 18446744073709)

isRevolving
required
boolean
pointTrackingEnabled
boolean
syncAlgorand
required
boolean

Enable algorand blockchain syncing

expiresInMonths
number

Points expiration in months

Array of objects (ExpirationPolicyDto)

Expiration policies for the account

overdraftLimit
number

Outstanding-debt cap for overdraft on this account. NULL or <= 0 disables overdraft. > 0 enables it (only on revolving accounts; pending transfers are not supported when overdraft is enabled).

isDefaultAccount
boolean

Is default account for ledger

Responses

Request samples

Content type
application/json
{
  • "alias": "string",
  • "name": "Main Ledger Account",
  • "active": true,
  • "isCurrency": true,
  • "decimals": 0,
  • "formatString": "string",
  • "maxSupply": 0,
  • "isRevolving": true,
  • "pointTrackingEnabled": true,
  • "syncAlgorand": true,
  • "expiresInMonths": 0,
  • "expirationPolicies": [
    ],
  • "overdraftLimit": 0,
  • "isDefaultAccount": true
}

Response samples

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

Gets a single Ledger Account

Authorizations:
bearer
path Parameters
ledgerKey
required
string
ledgerAccountKey
required
string
header Parameters
X-Q-Forwarded-Org
string

Organization Key

X-Q-Forwarded-User
string

User Key

Responses

Response samples

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

Updates a single Ledger Account

Authorizations:
bearer
path Parameters
ledgerKey
required
string
ledgerAccountKey
required
string
header Parameters
X-Q-Forwarded-Org
string

Organization Key

X-Q-Forwarded-User
string

User Key

Request Body schema: application/json
required
alias
string

Account alias for easier lookup

name
string
active
boolean
isCurrency
boolean

Optional Is a currency? for account

decimals
number

Optional decimals

formatString
string

Optional Format string for points

isRevolving
boolean
pointTrackingEnabled
boolean
syncAlgorand
boolean

Enable algorand blockchain syncing

expiresInMonths
number

Points expiration in months

Array of objects (ExpirationPolicyDto)

Expiration policies for the account

overdraftLimit
number

Outstanding-debt cap for overdraft on this account. NULL or <= 0 disables overdraft. > 0 enables it (only on revolving accounts; pending transfers are not supported when overdraft is enabled).

isDefaultAccount
boolean

Is default account for ledger

Responses

Request samples

Content type
application/json
{
  • "alias": "string",
  • "name": "Main Ledger Account",
  • "active": true,
  • "isCurrency": true,
  • "decimals": 0,
  • "formatString": "string",
  • "isRevolving": true,
  • "pointTrackingEnabled": true,
  • "syncAlgorand": true,
  • "expiresInMonths": 0,
  • "expirationPolicies": [
    ],
  • "overdraftLimit": 0,
  • "isDefaultAccount": true
}

Response samples

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

Updates a single Ledger Account's Supply

Use an empty maxSupply or body {} to increase to an infinite supply.

Authorizations:
bearer
path Parameters
ledgerKey
required
string
ledgerAccountKey
required
string
header Parameters
X-Q-Forwarded-Org
string

Organization Key

X-Q-Forwarded-User
string

User Key

Request Body schema: application/json
required
externalEventDate
string <date-time>

Optional Reference Event Date

systemUniqueKey
string

System Unique Key for tracking

externalId
string

Event Id for tracking

description
string
tags
Array of arrays
maxSupply
number

Max points supply available (max allowed 18446744073709)

Responses

Request samples

Content type
application/json
{
  • "externalEventDate": "2019-08-24T14:15:22Z",
  • "systemUniqueKey": "string",
  • "externalId": "string",
  • "description": "string",
  • "tags": [
    ],
  • "maxSupply": 0
}

Response samples

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

Tiers

List of Tiers

Authorizations:
bearer
query Parameters
page
number >= 0
Deprecated
Example: page=0

[Deprecated] The page number for pagination. Paging is being phased out for tier lists.

limit
number [ 1 .. 25 ]
Deprecated
Example: limit=10

[Deprecated] The limit of items to return per page. Paging is being phased out for tier lists.

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

loyaltyTierKey
string

Loyalty Tier Key

onlyActive
boolean

Only active loyalty tiers

loyaltyProgramKey
string

Loyalty Program Key

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a Tier

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string

Descriptive name for this Level.

active
required
boolean
minRequiredPoints
required
number

Minimun balance in Point Accrual Account to move to this Tier Level

tierOrder
required
number

Order between all the program tiers.

customAttributes
object
pictureUrl
string

Descriptive image url for this tier.

isDefault
boolean

Boolean to set tier as default

loyaltyProgramKey
string

Loyalty Program Key. Defaults to the default program if omitted.

Responses

Request samples

Content type
application/json
{
  • "name": "Silver",
  • "active": true,
  • "minRequiredPoints": 1000,
  • "tierOrder": 1,
  • "customAttributes": {
    },
  • "pictureUrl": "https://example.com/image.png",
  • "isDefault": true,
  • "loyaltyProgramKey": "string"
}

Response samples

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

Get the default Tier

Authorizations:
bearer
query Parameters
loyaltyProgramKey
required
string

Responses

Response samples

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

Get a Tier

Authorizations:
bearer
path Parameters
loyaltyTierKey
required
string

Responses

Response samples

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

Update a Tier

Authorizations:
bearer
path Parameters
loyaltyTierKey
required
string
Request Body schema: application/json
required
name
required
string

Descriptive name for this Level.

active
required
boolean
minRequiredPoints
required
number

Minimun balance in Point Accrual Account to move to this Tier Level

tierOrder
required
number

Order between all the program tiers.

customAttributes
object
pictureUrl
string

Descriptive image url for this tier.

isDefault
boolean

Boolean to set tier as default

Responses

Request samples

Content type
application/json
{
  • "name": "Silver",
  • "active": true,
  • "minRequiredPoints": 1000,
  • "tierOrder": 1,
  • "customAttributes": {
    },
  • "pictureUrl": "https://example.com/image.png",
  • "isDefault": true
}

Response samples

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

Order Locations

List of Order Locations

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

orderLocationCodes
string

Filter by location codes (comma-separated)

orderLocationLabel
string

Filter by order location label (partial match, case insensitive)

tags
string

Filter by tags (comma-separated, returns locations that contain any of the specified tags)

type
string
Enum: "location" "group"

Filter by location type

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a new Order Location (location or group)

Authorizations:
bearer
Request Body schema: application/json
required
orderLocationCode
required
string

Unique order location code identifier

orderLocationLabel
required
string

Display label for the order location

type
string
Enum: "location" "group"

Type of order location. Defaults to 'location'.

tags
Array of strings

Order location tags

filterTags
Array of strings

Tags filter for group membership (only for type 'group')

filterLabelPattern
string

Label ILIKE pattern filter for matching locations (only for type 'group')

filterExcludedCodes
Array of strings

Location codes to explicitly exclude from the group (only for type 'group')

Responses

Request samples

Content type
application/json
{
  • "orderLocationCode": "argentina",
  • "orderLocationLabel": "Argentina",
  • "type": "location",
  • "tags": [
    ],
  • "filterTags": [
    ],
  • "filterLabelPattern": "%aires%",
  • "filterExcludedCodes": [
    ]
}

Response samples

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

Get Order Location details

Authorizations:
bearer
path Parameters
orderLocationCode
required
string

Responses

Response samples

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

Update an Order Location (validates by stored type)

Authorizations:
bearer
path Parameters
orderLocationCode
required
string
Request Body schema: application/json
required
type
string
Enum: "location" "group"

Type cannot be changed after creation. Sending a different type will return 400.

orderLocationLabel
string

Display label for the order location

tags
Array of strings

Order location tags

filterTags
Array of strings

Tags filter for group membership (only for type 'group')

filterLabelPattern
string

Label ILIKE pattern filter for matching locations (only for type 'group')

filterExcludedCodes
Array of strings

Location codes to explicitly exclude from the group (only for type 'group')

Responses

Request samples

Content type
application/json
{
  • "type": "location",
  • "orderLocationLabel": "Argentina",
  • "tags": [
    ],
  • "filterTags": [
    ],
  • "filterLabelPattern": "%aires%",
  • "filterExcludedCodes": [
    ]
}

Response samples

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

Delete an Order Location

Authorizations:
bearer
path Parameters
orderLocationCode
required
string

Responses

Resolve location codes to their full group chains

Authorizations:
bearer
Request Body schema: application/json
required
codes
required
Array of strings

List of order location codes to resolve. Each code must be unique.

Responses

Request samples

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

Response samples

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

Product Categories

List of Product Categories

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

productCategoryCodes
Array of strings
Example: productCategoryCodes=electronics&productCategoryCodes=clothing&productCategoryCodes=food

Filter by product category codes

search
string

Filter by code, label or tags

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a Product Category

Authorizations:
bearer
Request Body schema: application/json
required
productCategoryCode
required
string

Unique product category code

productCategoryLabel
required
string

Human-readable product category label

tags
Array of strings

Product category tags

Responses

Request samples

Content type
application/json
{
  • "productCategoryCode": "electronics",
  • "productCategoryLabel": "Electronics",
  • "tags": [
    ]
}

Response samples

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

Get a Product Category

Authorizations:
bearer
path Parameters
productCategoryCode
required
string

Responses

Response samples

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

Update a Product Category

Authorizations:
bearer
path Parameters
productCategoryCode
required
string
Request Body schema: application/json
required
productCategoryCode
string

Unique product category code

productCategoryLabel
string

Human-readable product category label

tags
Array of strings

Product category tags

Responses

Request samples

Content type
application/json
{
  • "productCategoryCode": "electronics",
  • "productCategoryLabel": "Electronics",
  • "tags": [
    ]
}

Response samples

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

Console – Insights – Dashboards

List dashboards

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

dashboardKey
string
status
string
Enum: "draft" "published" "archived"

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a dashboard

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string
description
string
status
string
Default: "draft"
Enum: "draft" "published" "archived"

Responses

Request samples

Content type
application/json
{
  • "name": "Customer engagement overview",
  • "description": "Tracks weekly engagement KPIs.",
  • "status": "draft"
}

Response samples

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

Get a dashboard with its ordered widgets

Authorizations:
bearer
path Parameters
dashboardKey
required
string

Responses

Response samples

Content type
application/json
{
  • "dashboard": {
    },
  • "widgets": [
    ],
  • "widgetQueryParameters": { }
}

Update a dashboard

Authorizations:
bearer
path Parameters
dashboardKey
required
string
Request Body schema: application/json
required
name
string
description
string
status
string
Enum: "draft" "published" "archived"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "status": "draft"
}

Response samples

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

Delete a dashboard (cascades pivot rows; widgets remain alive)

Authorizations:
bearer
path Parameters
dashboardKey
required
string

Responses

Add an existing widget to the dashboard

Authorizations:
bearer
path Parameters
dashboardKey
required
string
Request Body schema: application/json
required
widgetKey
required
string
widgetOrder
number

Optional 0-based position. If omitted, the widget is appended.

Responses

Request samples

Content type
application/json
{
  • "widgetKey": "string",
  • "widgetOrder": 0
}

Response samples

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

Replace the dashboard's widget set with the provided list

Authorizations:
bearer
path Parameters
dashboardKey
required
string
Request Body schema: application/json
required
required
Array of objects (DashboardWidgetEntryDto)
Array
widgetKey
required
string
widgetOrder
required
number

0-based position within the dashboard.

Responses

Request samples

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

Response samples

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

Remove a widget from this dashboard (widget is not deleted)

Authorizations:
bearer
path Parameters
dashboardKey
required
string
widgetKey
required
string

Responses

Console – Insights – Widgets

List widgets

Authorizations:
bearer
query Parameters
page
number >= 0
Example: page=0

The page number for pagination

limit
number [ 1 .. 100 ]
Example: limit=100

The limit of items to return per page

order
string

Order of results as a comma-separated 'column' with an optional direction. Samples: ?order=col1, ?order=col1,asc or ?order=col1,desc

widgetKey
string
status
string
Enum: "published" "archived"
type
string

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "page": 0,
  • "limit": 0,
  • "results": [
    ]
}

Create a widget (queries may be DSL or stored; stored queries must exist and be widget-eligible)

Authorizations:
bearer
Request Body schema: application/json
required
name
required
string
description
string
type
required
string

Widget visualization type. Free string for now.

query
required
object

Query payload. Either a DSL query ({ definition, parameters? }) or a stored-query pointer ({ storedQueryKey }).

Array of objects (ExportQueryDto)

Optional secondary export queries (max 3). Names must be unique, non-empty, and not 'main'. Never run by execute — only preview/validate operate on them.

params
object

Visualization params, depends on type.

status
string
Default: "published"
Enum: "published" "archived"

Responses

Request samples

Content type
application/json
{
  • "name": "Active members per day",
  • "description": "string",
  • "type": "chart",
  • "query": { },
  • "exportQueries": [
    ],
  • "params": { },
  • "status": "published"
}

Response samples

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

Get a widget

Authorizations:
bearer
path Parameters
widgetKey
required
string

Responses

Response samples

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

Update a widget

Authorizations:
bearer
path Parameters
widgetKey
required
string
Request Body schema: application/json
required
name
string
description
string
type
string
query
object
Array of objects (ExportQueryDto)

Optional secondary export queries (max 3). When provided, replaces the whole set.

params
object
status
string
Enum: "published" "archived"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "string",
  • "query": { },
  • "exportQueries": [
    ],
  • "params": { },
  • "status": "published"
}

Response samples

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

Delete a widget (cascades pivot rows so dashboards lose this widget)

Authorizations:
bearer
path Parameters
widgetKey
required
string

Responses

Preview a query without persisting — the caller sends the exact query to preview (DSL or stored; single page, pageSize ≤ 50, no pageToken)

Authorizations:
bearer
Request Body schema: application/json
required
query
required
object

The single query to preview — DSL ({ definition, parameters? }) or stored ({ storedQueryKey }). The caller sends whichever query (main or an export) it wants to preview; the server dispatches by kind.

parameters
object

Parameter values for the query: overrides for a DSL query.parameters, or the stored query's params (forwarded as-is).

pageSize
number [ 1 .. 50 ]

Number of rows to preview. Default 50. Must be between 1 and 50. Preview is single-page — pagination (pageToken) is not supported.

Responses

Request samples

Content type
application/json
{
  • "query": { },
  • "parameters": { },
  • "pageSize": 1
}

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "rows": [ ],
  • "metadata": {
    }
}

Validate a single widget query without persisting or running it (stored query: existence + widget-eligibility only; DSL: upstream verdict)

Authorizations:
bearer
Request Body schema: application/json
required
query
required
object

The query to validate — DSL ({ definition, parameters? }) or stored ({ storedQueryKey }).

parameters
object

Parameter values applied to DSL queries when resolving them upstream.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "valid": true,
  • "error": "string"
}

Execute a widget's main query and return paginated rows (DSL via insights query; stored via the stored-query proxy)

Authorizations:
bearer
path Parameters
widgetKey
required
string
Request Body schema: application/json
required
pageSize
number [ 1 .. 100 ]

Number of rows per page. Default 100. Must be between 1 and 100.

pageToken
string

Cursor returned by the previous response in metadata.nextPageToken. Omit to start from the first page.

parameters
object

Override values for the parameters declared in query.parameters. Keys must match declared parameter names; values must be primitives (string/number/boolean), and if the parameter declares an allowed values list, the override must be in that list. Missing overrides fall back to the default.

Responses

Request samples

Content type
application/json
{
  • "pageSize": 1,
  • "pageToken": "string",
  • "parameters": { }
}

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "rows": [ ],
  • "metadata": {
    }
}

List the dashboards that contain this widget

Authorizations:
bearer
path Parameters
widgetKey
required
string

Responses

Response samples

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