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 columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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
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" "archived"

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

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

Responses

Request samples

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

Response samples

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

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 columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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

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

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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

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 columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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

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.

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.

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": [
    ],
  • "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.

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": [
    ]
}

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=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

email
string

Filter by email

loyaltyMemberId
string

Filter by loyalty member id

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

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=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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)

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
}

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

Responses

Request samples

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

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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

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"
}

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=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

fromDate
string <date-time>

Optional Reference From Event Date

toDate
string <date-time>

Optional Reference To Event Date

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

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"
}

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=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

fromDate
string <date-time>

Optional Reference From Event Date

toDate
string <date-time>

Optional Reference To Event Date

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 <= 255 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 <= 255 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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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": [
    ]
}

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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
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",
  • "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
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",
  • "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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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) 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. 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) 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. 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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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) 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. 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) 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. 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 .. 25 ]
Example: limit=10

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
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
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": [
    ]
}

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

Execute an ad-hoc insights query against the data warehouse

Projects arbitrary dimensions and metrics with user-defined aliases. Supports filtering, time windows, pagination, estimation, and validate (dry-run) modes. Organization scope is always derived from the authenticated token.

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

Insights definition (unified audience DSL).

from
string <= 64 characters /^[A-Za-z][A-Za-z0-9_]{0,63}$/

Semantic-model key (SQL-style from). Restricts the DSL namespace to the model's exposed facts/dims; for fact-rooted analytics models (ledgerTransactions, paymentsAnalytics) it also pivots the universe on the fact's primary key. Defaults to "members" — the wide audience model, same physical catalog as before, so legacy payloads keep working bit-for-bit. See GET /v2/segment-definitions/semantic-model.models for the catalog.

audience
object

Unified DSL filter tree (AND/OR/NOT). Required in set mode (no projections) — without it there is no audience filter. Optional in rows mode — when omitted, the audience defaults to 'all members of the projected dim in the organization', and the rows-mode SELECT shapes the result via projections / window / havingFilters. Children may omit the type discriminator: dimension is inferred from a dimension field (no fact), metric is inferred from a fact field.

logic
object
Deprecated

Deprecated alias of audience (same shape). Sending both audience and logic returns 400 with a clear message.

projectedDimension
string

Universe dimension. When set without projections, returns a single column: the entityKeyColumn of this dim (e.g. member → member_id). Mutually exclusive with projections. Defaults to the model's root dim — "member" for the default members model; for fact-rooted analytics models (ledgerTransactions, paymentsAnalytics) the default is the model key itself. If you set it explicitly, it must match the model's root.

projections
Array of objects

Multi-column projections (rows mode). Mutually exclusive with projectedDimension.

havingFilters
Array of objects

Post-aggregation filters (HAVING).

required
object
window
object

Global time window for fact-based metric projections.

orderBy
Array of objects

Result ordering. Each entry must reference a projection alias.

pageSize
number [ 1 .. 10000 ]
Default: 100

Keyset page size. Caps row count for mode: "execute" and doubles as the first-page size for keyset pagination. The server appends the projected dim's entity-key column as a tiebreaker on orderBy, so pages chain stably even when the caller's primary ordering has ties. Replaces the legacy limit / offset pair (both removed — sending them returns 400 from the request validator).

pageToken
string

Keyset cursor for the next page — copy metadata.nextPageToken from the previous response. Plain opaque string; clients should treat it as such (the server may change the encoding without warning). Omit on the first page. Requires pageSize.

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

Execution mode. execute returns rows; estimate returns an approximate count; validate compiles the SQL and runs a warehouse dry-run (no data scanned, no rows returned) — use it as a pre-flight check before sending the real query. The dry-run response surfaces validity, an estimatedBytesProcessed hint, and the warehouse error message if the SQL is invalid. Cross-field rules: samplingPercent requires projections (rows mode); samplingPercent + mode: "estimate" is rejected because the count would be ambiguous.

samplingPercent
number [ 1 .. 99 ]

Sampled preview for ad-hoc reports (rows mode only). Integer percent (1..99). Returns ~N% of the matching universe; the audience filter still runs against the full dataset, but only the sampled subset feeds the report's joins, aggregations, and sorts. Sampling is deterministic per member id (a given member is either always in or always out for a fixed samplingPercent), so pagination is stable across calls. Rejected when projections is empty (set mode) or mode = "estimate". Compose with mode = "execute" for fast row previews; the dry-run mode (mode = "validate") accepts it too and compiles the sampled SQL without executing.

approximate
boolean

Opt into approximate distinct counts. When true, every COUNT_DISTINCT aggregation (in projections, metric conditions, and having filters) is answered by a sketch with ~1% relative error instead of an exact dedupe. Auto-enabled by mode = "estimate" (the count itself IS approximate); pass false to override and force exact COUNT(DISTINCT) even in estimate mode. Composes with every mode and with samplingPercent. Useful for previews on large universes where ~1% error is acceptable in exchange for materially faster aggregations.

Responses

Request samples

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

Response samples

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

Insights MCP

Insights MCP endpoint (JSON-RPC 2.0, stateless)

Model Context Protocol server for building insights 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. 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.

isActive
boolean
Deprecated
Default: true

Deprecated: use autoRefreshEnabled instead. Maps 1:1 — isActive: false sets autoRefreshEnabled: false, isActive: true sets autoRefreshEnabled: true.

disableList
boolean
Deprecated
Default: false

Deprecated: toggle the audience directly via PUT /audiences/:audienceKey { active } instead. Kept for backward compatibility — ignored on create, and only honored on update; when true on update, sets the linked audience's active to false.

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,
  • "isActive": true,
  • "disableList": false,
  • "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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

isActive
boolean
Deprecated
Example: isActive=true

Deprecated: use autoRefreshEnabled query instead. isActive=true returns scheduled BigQuery segments AND CSV imports (preserving the pre-refactor list contract); isActive=false returns only paused BigQuery segments. The explicit autoRefreshEnabled filter is stricter and excludes CSV imports in both modes.

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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": {
    }
}

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. Optional from defaults to "members"; audience models today are members, membersLedgerActivity, membersWalletBalance, membersPurchase, membersPayments, membersCouponActivity, membersCouponBalance. Analytics models belong to POST /v2/insights/query.

Responses

Request samples

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

Response samples

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

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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. V1 supports webhook only.

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 .. 25 ]
Example: limit=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

targetId
string

Filter by activation target id.

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
required
string
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

Responses

Request samples

Content type
application/json
{
  • "targetId": "string",
  • "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; members missing from the read replica are retried up to the target's maxAttempts (replica-lag tolerance) and then marked SKIPPED only if still missing after the attempt budget.

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
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=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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=10

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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 columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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

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": [
    ],
  • "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
required
string
active
required
boolean
isCurrency
boolean

Optional Is a currency? for account

decimals
number

Optional decimals

formatString
string

Optional Format string for points

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

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": [
    ],
  • "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

The page number for pagination

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

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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

The page number for pagination

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

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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

The page number for pagination

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

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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
productCategoryLabel
string

Human-readable product category label

tags
Array of strings

Product category tags

Responses

Request samples

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

Response samples

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

Console – Insights – Dashboards

List dashboards

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 columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

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

The page number for pagination

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

The limit of items to return per page

order
string

Order of columns in result in the format 'column,asc|desc?'. Samples: ?order=col1 or ?order=col1,asc

widgetKey
string
status
string
Enum: "published" "archived"
type
string
source
string
Enum: "live" "warehouse"

Responses

Response samples

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

Create a widget (warehouse only — live widgets cannot be created via API)

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

Widget visualization type. Free string for now.

source
required
string
Enum: "live" "warehouse"

How the query JSONB should be interpreted. live = raw SQL; warehouse = DSL JSON for the semantic model.

query
required
object

Query payload. Shape depends on source: SQL attribute (TBD) for live, DSL JSON for warehouse.

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",
  • "source": "live",
  • "query": { },
  • "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 (rejected if existing widget has source=live)

Authorizations:
bearer
path Parameters
widgetKey
required
string
Request Body schema: application/json
required
name
string
description
string
type
string
source
string
Enum: "live" "warehouse"
query
object
params
object
status
string
Enum: "published" "archived"

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "type": "string",
  • "source": "live",
  • "query": { },
  • "params": { },
  • "status": "published"
}

Response samples

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

Delete a widget (rejected if source=live; otherwise cascades pivot rows so dashboards lose this widget)

Authorizations:
bearer
path Parameters
widgetKey
required
string

Responses

Preview a warehouse widget query without persisting (single page; live source rejected)

Authorizations:
bearer
Request Body schema: application/json
required
source
required
string
Enum: "live" "warehouse"

Widget source. Only 'warehouse' is accepted — 'live' is rejected (live SQL is internal).

query
required
object

Query payload — same shape as create. query.parameters declares parameters (defaults + optional type/label/values); query.definition is the warehouse DSL with {{name}} placeholders.

parameters
object

Override values for the parameters declared in query.parameters. Same rules as execute overrides.

pageSize
number [ 1 .. 100 ]

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

Responses

Request samples

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

Response samples

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

Execute a warehouse widget query and return paginated rows (live widgets are rejected)

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": [
    ]
}