Loyalty and Engagement — API Reference

Win the loyalty of your customers with promotions and personalized offers

127 endpoints across 9 tags.

Uniquely identified methods include a self-contained OpenAPI YAML export for use by tools and language models.

Promotions

GET /v4/promotions/promotion/get-for-client — Get a Profile's promotions as Profile

/api-reference/loyalty-and-engagement#tag/Promotions/operation/GetAClientsPromotions

Self-contained method YAML

A Profile can retrieve a list of all its promotions, assigned or activated. By default, only non-expired promotions are retrieved.

IMPORTANT:

  • As a result of this request, the targetSegments of all the matching promotions are checked. If this results in checking more than 100 unique segments, any segments above this limit may be ignored.
  • The endpoint is limited to 25000 requests per minute (per workspace).

API consumers: Profile (Client), Anonymous Profile

Parameters

NameInTypeRequiredDescription
sortquerystringoptionalThe sorting order of the response. You can sort by any combination of the following attributes: headerName: promotion header name name: promotion name code: promotion code startAt: time when the promotion starts createdAt: time when the promotion was created updatedAt: time when the promotion was last updated expireAt: time when the promotion expires requireRedeemedPoints: how many loyalty points are needed to redeem the promotion type: type of the promotion priority: priority of the promotion status : status of the promotion for the Profile You can sort ascending (default) or descending by adding asc or desc after the parameter, separated by a comma. Example: sort=requireRedeemedPoints&sort=expireAt,asc&sort=status,desc
statusqueryarray<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>optionalFilter by promotion status
presentOnlyquerybooleanoptionalWhen set to: true, the response includes only promotions that are currently active (startAt later than now or null, expireAt later than now or null) false, the response includes the above and also promotions that are expired or will become active in the future.
displayableOnlyquerybooleanoptionalWhen set to true, promotions which are not currently active are included in response, according to date range defined in promotion fields displayFrom and displayTo.
tagNamesqueryarray<string>optionalFilter the response to promotions with a certain tag or tags
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
checkGlobalActivationLimitsquerybooleanoptionalFlag to indicate if global limits should be checked
includeVouchersquerybooleanoptionalWhen true, promotion with defined vouchers will also have list of assigned vouchers. When false, vouchers will not be fetched.
storeIdsquerystringoptionalLimits the response to data from particular stores, identified by IDs.

Responses

StatusDescription
200 application/jsonAn array of promotions
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/get-for-client?sort=requireRedeemedPoints%2Cdesc&status=SOME_ARRAY_VALUE&presentOnly=true&displayableOnly=true&tagNames=SOME_ARRAY_VALUE&limit=100&page=4&includeMeta=false&checkGlobalActivationLimits=true&includeVouchers=false&storeIds=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /v4/promotions/promotion/duplicate — Duplicate existing promotion

/api-reference/loyalty-and-engagement#tag/Promotions/operation/duplicatePromotion

Self-contained method YAML

You can duplicate an existing promotion.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: PROMOTIONS_DUPLICATE_PROMOTIONS_CREATE

User role permission required: campaigns_promotions: create

Request body (required)

application/json · promotions-duplicatePromotionRequest

Provide only one of the parameters.

FieldTypeRequiredDescription
uuidstringoptionalPromotion UUID
codestringoptionalPromotion code

Responses

StatusDescription
200 application/jsonPromotion duplicated
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonPromotion not found
500Internal Server Error

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/duplicate \
  --header 'content-type: application/json' \
  --data '{"uuid":"string","code":"string"}'

POST /v4/promotions/promotion/activate — Activate a promotion

/api-reference/loyalty-and-engagement#tag/Promotions/operation/ActivateAPromotion

Self-contained method YAML

A Profile can change the status of a promotion from assigned to active, the promotion can now be applied to a purchase.

API consumers: Profile (Client), Anonymous Profile

Request body (required)

application/json · promotions-promotionActivation

FieldTypeRequiredDescription
keyenum<"uuid", "code">requiredType of promotion identifier
valuestringrequiredValue of the selected identifier
pointsToUseintegeroptionalHow many points should be converted to digital money and stored as ready to redeem in transactions in digital cashback promotions.

Responses

StatusDescription
200 application/jsonPromotion activated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonProfile, promotion, or related resource not found
409 application/jsonWaiting for profile lock release
412 application/jsonAlready activated/Already redeemed/Activation limit reached/Promotion not started/Promotion expired
422 application/jsonGlobal Activation limit reached
423 application/jsonProfile promotions blocked
500General error

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/activate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"key":"code","value":"7893467834GG","pointsToUse":100}'

POST /v4/promotions/promotion/batch-activate — Batch activate promotions

/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchActivate

Self-contained method YAML

A Profile can change the status of a number of promotions from assigned to active, the promotion can now be applied to a purchase. This method can't be used to activate promotions which require voucher assignment. You need to activate such promotions individually.

API consumers: Profile (Client), Anonymous Profile

Request body (required)

application/json · array<promotions-promotionActivation>

Responses

StatusDescription
200 application/jsonPromotions activated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonProfile, promotion, or related resource not found
409 application/jsonWaiting for profile lock release
412 application/jsonAlready activated/Already redeemed/Activation limit reached/Promotion not started/Promotion expired
423 application/jsonProfile promotions blocked
500General error

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/batch-activate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"key":"code","value":"7893467834GG","pointsToUse":100}]'

POST /v4/promotions/promotion/deactivate — Deactivate a promotion

/api-reference/loyalty-and-engagement#tag/Promotions/operation/DeactivateAPromotion

Self-contained method YAML

A Profile can change the status of an activated promotion back to assigned.

API consumers: Profile (Client), Anonymous Profile

Request body (required)

application/json · promotions-promotionActivation

FieldTypeRequiredDescription
keyenum<"uuid", "code">requiredType of promotion identifier
valuestringrequiredValue of the selected identifier
pointsToUseintegeroptionalHow many points should be converted to digital money and stored as ready to redeem in transactions in digital cashback promotions.

Responses

StatusDescription
200 application/jsonPromotion deactivated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonPromotion deactivation is forbidden due to promotion setup.
404 application/jsonNot Found
429 application/jsonWaiting for profile lock release

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/deactivate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"key":"code","value":"7893467834GG","pointsToUse":100}'

POST /v4/promotions/promotion/batch-deactivate — Batch deactivate promotions

/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchDeactivate

Self-contained method YAML

A Profile can change the status of a number of activated promotions back to assigned.

API consumers: Profile (Client), Anonymous Profile

Request body (required)

application/json · array<promotions-promotionActivation>

Responses

StatusDescription
200 application/jsonPromotions deactivated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found
429 application/jsonWaiting for profile lock release

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/batch-deactivate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"key":"code","value":"7893467834GG","pointsToUse":100}]'

POST /v4/promotions/promotion/deactivate-all-for-client/{identifierType}/{identifierValue} — Deactivate all promotions for a Profile as Workspace

/api-reference/loyalty-and-engagement#tag/Promotions/operation/deactivateAllPromotions

Self-contained method YAML

You can deactivate all promotions assigned to a Profile.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_DEACTIVATE_PROMOTIONS_UPDATE

User role permission required: campaigns_promotions: update

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier
returnCodesquerybooleanoptionalReturn deactivated codes
lockPointsquerybooleanoptionalLock profile points during the deactivation process
excludeTagsqueryarray<string>optionalPromotions with the tags included in this list will not be deactivated

Responses

StatusDescription
200 application/jsonAll promotions deactivated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonProfile not found

Example request (cURL)

curl --request POST \
  --url 'https://api.synerise.com/v4/promotions/promotion/deactivate-all-for-client/email/%7BidentifierValue%7D?returnCodes=true&lockPoints=true&excludeTags=SOME_ARRAY_VALUE'

POST /v4/promotions/promotion/redeem — Redeem a promotion

/api-reference/loyalty-and-engagement#tag/Promotions/operation/RedeemAPromotion

Self-contained method YAML

You can redeem a promotion and loyalty points.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_REDEEM_PROMOTIONS_CREATE

User role permission required: campaigns_promotions: create

Request body (required)

application/json · promotions-RedeemPromotionsRequest

FieldTypeRequiredDescription
codestringrequiredPromotion code
clientKeyenum<"externalId", "clientId", "email", "phone", …>requiredType of profile identifier
clientKeyValuestringrequiredValue of the selected identifier
quantityintegeroptionalQuantity of redeemed items
sourceIdstringoptionalThe source of redemption. It should be unique for the source of promotion to ensure that redemptions are successfully deduplicated when retried. Example: a concatenation of receipt ID and index of the discounted transaction line on the receipt.
orderIdstringoptionalReceipt ID for which the promotion was redeemed. It's required when using step promotions. The order ID will be used to check if requirements of granting a step promotion are fulfilled.
lockIdentifierstringoptionalIdentifier of the "promotion requested" lock which will be released when the promotion is redeemed. This kind of lock blocks a profile from requesting new promotions and can be applied when using the Get Profile promotions by a custom filter endpoint.

Responses

StatusDescription
201 application/jsonPromotion redeemed successfully
209 application/jsonPromotion is already redeemed
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot found error
409 application/jsonWaiting for profile lock release
412 application/jsonUnprocessable redemption
423 application/jsonProfile promotions blocked

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/redeem \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"code":"75d9090f-06ac-46a2-a0ce-4b8eb287efb9","clientKey":"clientId","clientKeyValue":"434428563"}'

POST /v4/promotions/promotion/batch-redeem — Batch redeem promotions

/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchRedeemPromotions

Self-contained method YAML

You can redeem up to 100 promotions and loyalty points relevant to them.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_BATCH_REDEEM_PROMOTIONS_CREATE

User role permission required: campaigns_promotions: create

Request body (required)

application/json · array<promotions-RedeemPromotionsRequest>

Responses

StatusDescription
201 application/jsonPromotion redeemed successfully
209 application/jsonPromotion is already redeemed
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot found error
409 application/jsonWaiting for profile lock release
412 application/jsonUnprocessable redemption
423 application/jsonProfile promotions blocked

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/batch-redeem \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"code":"75d9090f-06ac-46a2-a0ce-4b8eb287efb9","clientKey":"clientId","clientKeyValue":"434428563"}]'

GET /v4/promotions/v2/promotion/get-for-client/{identifierType}/{identifierValue} — Get a Profile's promotions as Workspace (v2)

/api-reference/loyalty-and-engagement#tag/Promotions/operation/GetAllClientPromotionsV2

Self-contained method YAML

A Workspace can retrieve a list of a profile's promotions. By default, only non-expired promotions are retrieved.

IMPORTANT:

  • As a result of this request, the targetSegments of all the matching promotions are checked. If this results in checking more than 100 unique segments, any segments above this limit may be ignored.
  • The endpoint is limited to 25000 requests per minute (per workspace).

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_LIST_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier
sortquerystringoptionalThe sorting order of the response. You can sort by any combination of the following attributes: headerName: promotion header name name: promotion name code: promotion code startAt: time when the promotion starts createdAt: time when the promotion was created updatedAt: time when the promotion was last updated expireAt: time when the promotion expires requireRedeemedPoints: how many loyalty points are needed to redeem the promotion type: type of the promotion priority: priority of the promotion status : status of the promotion for the Profile You can sort ascending (default) or descending by adding asc or desc after the parameter, separated by a comma. Example: sort=requireRedeemedPoints&sort=expireAt,asc&sort=status,desc
statusqueryarray<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>optionalFilter by promotion status
presentOnlyquerybooleanoptionalWhen set to: true, the response includes only promotions that are currently active (startAt later than now or null, expireAt later than now or null) false, the response includes the above and also promotions that are expired or will become active in the future.
displayableOnlyquerybooleanoptionalWhen set to true, promotions which are not currently active are included in response, according to date range defined in promotion fields displayFrom and displayTo.
tagNamesqueryarray<string>optionalFilter the response to promotions with a certain tag or tags
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
fieldsqueryarray<enum<"uuid", "code", "status", "type", …>>optionalReturn only specified promotion fields. If fields is not specified, all fields are returned.
promotionUuidsquerystringoptionalFilters the response data by a list of promotion UUIDs.
checkGlobalActivationLimitsquerybooleanoptionalFlag to indicate if global limits should be checked
includeVouchersquerybooleanoptionalWhen true, promotion with defined vouchers will also have list of assigned vouchers. When false, vouchers will not be fetched.
storeIdsquerystringoptionalLimits the response to data from particular stores, identified by IDs.

Responses

StatusDescription
200 application/jsonAn array of promotions
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonProfile not found

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/v2/promotion/get-for-client/email/%7BidentifierValue%7D?sort=requireRedeemedPoints%2Cdesc&status=SOME_ARRAY_VALUE&presentOnly=true&displayableOnly=true&tagNames=SOME_ARRAY_VALUE&limit=100&page=4&includeMeta=false&fields=uuid%2CrequireRedeemedPoints%2CrequireRedeemedPoints%2CpossibleRedeems%2Cstatus%2CcurrentRedeemedQuantity%2ClastingAt&promotionUuids=fc1ee5bf-ad97-47a8-a474-e1b6e755ff38%2Caabaed4e-4ee7-44d5-b079-445a017ec6fe&checkGlobalActivationLimits=true&includeVouchers=false&storeIds=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/get-item-for-client/{identifierType}/{identifierValue} — View promotion details as Profile

/api-reference/loyalty-and-engagement#tag/Promotions/operation/ViewPromotionDetailsAsClient

Self-contained method YAML

A Profile can view all the details of an assigned or activated promotion.

API consumers: Profile (Client), Anonymous Profile

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"uuid", "code">requiredThe promotion identifier to use for the request
identifierValuepathstringrequiredThe value of the selected identifier
lastingOnlyquerybooleanoptionalWhen set to true, shows promotions/vouchers that are currently active and those that are still inactivated. (lastingAt set to null or lastingAt in future)

Responses

StatusDescription
200 application/jsonDetails of a promotion
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/get-item-for-client/%7BidentifierType%7D/%7BidentifierValue%7D?lastingOnly=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/get-item-for-client-no-data/{identifierType}/{identifierValue} — View promotion details as Profile

/api-reference/loyalty-and-engagement#tag/Promotions/operation/ViewPromotionDetailsAsClientNoData

Self-contained method YAML

A Profile can view all the details of an assigned or activated promotion.

API consumers: Profile (Client), Anonymous Profile

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"uuid", "code">requiredThe promotion identifier to use for the request
identifierValuepathstringrequiredThe value of the selected identifier

Responses

StatusDescription
200 application/jsonDetails of a promotion
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/promotions/promotion/get-item-for-client-no-data/%7BidentifierType%7D/%7BidentifierValue%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/list — View Workspace promotions

/api-reference/loyalty-and-engagement#tag/Promotions/operation/ViewBusinessProfilePromotions

Self-contained method YAML

You can retrieve a list of all promotions defined in your Workspaces. It includes configured promotions, ready to be used or already in use.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_LIST_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
storeCatalogquerystringoptionalLimits the response to data from stores included in a catalog.
storeIdsquerystringoptionalLimits the response to data from particular stores, identified by IDs.
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
orderFieldNamequeryenum<"createdAt", "headerName", "code", "startAt", …>optionalName of the parameter used for sorting
orderqueryenum<"asc", "desc">optionalSorting order
queryquerystringoptionalA string to search for in the headerName parameter or fragment of UUID.
promotionUuidsquerystringoptionalFilters the response data by a list of promotion UUIDs.
targetByTypequerystringoptionalA combination of target and type, for example [SEGMENT]=ACTIVE

Responses

StatusDescription
200 application/jsonAn array of promotions
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/list?limit=100&page=4&storeCatalog=SOME_STRING_VALUE&storeIds=SOME_STRING_VALUE&includeMeta=false&orderFieldName=SOME_STRING_VALUE&order=SOME_STRING_VALUE&query=SOME_STRING_VALUE&promotionUuids=fc1ee5bf-ad97-47a8-a474-e1b6e755ff38%2Caabaed4e-4ee7-44d5-b079-445a017ec6fe&targetByType=%5BSEGMENT%5D%3DACTIVE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/diff-list — View recently updated promotions

/api-reference/loyalty-and-engagement#tag/Promotions/operation/ViewBusinessProfilePromotionsDiff

Self-contained method YAML

You can retrieve a list of promotions that were updated. You can filter, sort, and paginate the results.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_DIFF_LIST_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
storeCatalogquerystringoptionalLimits the response to data from stores included in a catalog.
storeIdsquerystringoptionalLimits the response to data from particular stores, identified by IDs.
targetqueryarray<enum<"ALL", "SEGMENT">>optionalThe target of the promotion
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
presentOnlyquerybooleanoptionalWhen set to: true, the response includes only promotions that are currently active (startAt later than now or null, expireAt later than now or null) false, the response includes the above and also promotions that are expired or will become active in the future.
visibilityStatusqueryarray<enum<"DRAFT", "PUBLISH", "HIDDEN">>optionalVisibility status
upsertTimestampquerystringoptionalDefines the date since which the differences are shown. If not defined, defaults to infinity.
orderFieldNamequeryenum<"createdAt", "headerName", "code", "startAt", …>optionalName of the parameter used for sorting
orderqueryenum<"asc", "desc">optionalSorting order
queryquerystringoptionalA string to search for in the headerName parameter or fragment of UUID.

Responses

StatusDescription
200 application/jsonAn array of promotions. If a promotion was deleted, the deletedAt field is included
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/diff-list?limit=100&page=4&storeCatalog=SOME_STRING_VALUE&storeIds=SOME_STRING_VALUE&target=SOME_ARRAY_VALUE&includeMeta=false&presentOnly=true&visibilityStatus=SOME_ARRAY_VALUE&upsertTimestamp=SOME_STRING_VALUE&orderFieldName=SOME_STRING_VALUE&order=SOME_STRING_VALUE&query=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/get-for-client/{identifierType}/{identifierValue} — Get a Profile's promotions as Workspace (deprecated)

/api-reference/loyalty-and-engagement#tag/Promotions/operation/GetAllClientPromotions

Self-contained method YAML

Deprecated. Use /v2/promotion/get-for-client/{identifierType}/{identifierValue} instead.

A Workspace can retrieve a list of all promotions assigned to a Profile.

IMPORTANT:

  • As a result of this request, the targetSegments of all the matching promotions are checked. If this results in checking more than 100 unique segments, any segments above this limit may be ignored.
  • The endpoint does not support redemption limits per client for Multi-buy promotions (promotions with redeemQuantityPerActivation greater than 1). For redemption limits, please use /v2/promotion/get-for-client/{identifierType}/{identifierValue}.
  • The endpoint is limited to 25000 requests per minute (per workspace).

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_LIST_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier
sortquerystringoptionalThe sorting order of the response. You can sort by any combination of the following attributes: headerName: promotion header name name: promotion name code: promotion code startAt: time when the promotion starts createdAt: time when the promotion was created updatedAt: time when the promotion was last updated expireAt: time when the promotion expires requireRedeemedPoints: how many loyalty points are needed to redeem the promotion type: type of the promotion priority: priority of the promotion status : status of the promotion for the Profile You can sort ascending (default) or descending by adding asc or desc after the parameter, separated by a comma. Example: sort=requireRedeemedPoints&sort=expireAt,asc&sort=status,desc
statusqueryarray<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>optionalFilter by promotion status. If not provided, defaults to ACTIVE. If status is not provided and no promotions are active, the response is an empty array.
tagNamesqueryarray<string>optionalFilter the response to promotions with a certain tag or tags
targetqueryarray<enum<"ALL", "SEGMENT">>optionalThe target of the promotion
typequeryarray<enum<"GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL">>optionalPromotion type
presentOnlyquerybooleanoptionalWhen set to: true, the response includes only promotions that are currently active (startAt later than now or null, expireAt later than now or null) false, the response includes the above and also promotions that are expired or will become active in the future.
lastingOnlyquerybooleanoptionalWhen set to true, shows promotions/vouchers that are currently active and those that are still inactivated. (lastingAt set to null or lastingAt in future)
displayableOnlyquerybooleanoptionalWhen set to true, promotions which are not currently active are included in response, according to date range defined in promotion fields displayFrom and displayTo.
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
includeVouchersquerybooleanoptionalWhen true, promotion with defined vouchers will also have list of assigned vouchers. When false, vouchers will not be fetched.
storeIdsquerystringoptionalLimits the response to data from particular stores, identified by IDs.

Responses

StatusDescription
200 application/jsonAn array of promotions
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonProfile not found

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/get-for-client/email/%7BidentifierValue%7D?sort=requireRedeemedPoints%2Cdesc&status=SOME_ARRAY_VALUE&tagNames=SOME_ARRAY_VALUE&target=SOME_ARRAY_VALUE&type=SOME_ARRAY_VALUE&presentOnly=true&lastingOnly=true&displayableOnly=true&limit=100&page=4&includeMeta=false&includeVouchers=false&storeIds=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/get-for-client-possible-to-redeem/{identifierType}/{identifierValue} — Get redeemable promotions of a Profile

/api-reference/loyalty-and-engagement#tag/Promotions/operation/GetRedeemablePromotions

Self-contained method YAML

Retrieve all redeemable promotions related to a Profile.

IMPORTANT:

  • As a result of this request, the targetSegments of all the matching promotions are checked. If this results in checking more than 100 unique segments, any segments above this limit may be ignored.
  • The endpoint is limited to 25000 requests per minute (per workspace).

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_REDEEM_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier
sortquerystringoptionalThe sorting order of the response. You can sort by any combination of the following attributes: headerName: promotion header name name: promotion name code: promotion code startAt: time when the promotion starts createdAt: time when the promotion was created updatedAt: time when the promotion was last updated expireAt: time when the promotion expires requireRedeemedPoints: how many loyalty points are needed to redeem the promotion type: type of the promotion priority: priority of the promotion status : status of the promotion for the Profile You can sort ascending (default) or descending by adding asc or desc after the parameter, separated by a comma. Example: sort=requireRedeemedPoints&sort=expireAt,asc&sort=status,desc
presentOnlyquerybooleanoptionalWhen set to: true, the response includes only promotions that are currently active (startAt later than now or null, expireAt later than now or null) false, the response includes the above and also promotions that are expired or will become active in the future.
lastingOnlyquerybooleanoptionalWhen set to true, shows promotions/vouchers that are currently active and those that are still inactivated. (lastingAt set to null or lastingAt in future)
displayableOnlyquerybooleanoptionalWhen set to true, promotions which are not currently active are included in response, according to date range defined in promotion fields displayFrom and displayTo.
statusqueryarray<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>optionalFilter by promotion status
typequeryarray<enum<"GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL">>optionalPromotion type
statusByTypequerystringoptionalA combination of status and type, for example [CUSTOM]=ACTIVE
targetByTypequerystringoptionalA combination of target and type, for example [SEGMENT]=ACTIVE
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
targetqueryarray<enum<"ALL", "SEGMENT">>optionalThe target of the promotion
storeIdsquerystringoptionalLimits the response to data from particular stores, identified by IDs.

Responses

StatusDescription
200 application/jsonAn array of promotions
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/get-for-client-possible-to-redeem/email/%7BidentifierValue%7D?sort=requireRedeemedPoints%2Cdesc&presentOnly=true&lastingOnly=true&displayableOnly=true&status=SOME_ARRAY_VALUE&type=SOME_ARRAY_VALUE&statusByType=%5BCUSTOM%5D%3DACTIVE&targetByType=%5BSEGMENT%5D%3DACTIVE&includeMeta=false&page=4&limit=100&target=SOME_ARRAY_VALUE&storeIds=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/{identifierType}/{identifierValue} — Get promotion details as Workspace

/api-reference/loyalty-and-engagement#tag/Promotions/operation/GetPromotionDetailsAsBusinessProfile

Self-contained method YAML

Retrieve the details of a promotion by its code.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_DETAILS_FOR_PROFILE_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"uuid", "code">requiredThe promotion identifier to use for the request
identifierValuepathstringrequiredThe value of the selected identifier

Responses

StatusDescription
200 application/jsonDetails of a promotion
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/promotions/promotion/%7BidentifierType%7D/%7BidentifierValue%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

PUT /v4/promotions/promotion/{identifierType}/{identifierValue} — Update a promotion

/api-reference/loyalty-and-engagement#tag/Promotions/operation/UpdateAPromotion

Self-contained method YAML

You can update an existing promotion. Include only the fields that you want to change. Inserting a null value overwrites an existing value.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_DETAILS_FOR_PROFILE_PROMOTIONS_UPDATE

User role permission required: campaigns_promotions: update

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"uuid", "code">requiredThe promotion identifier to use for the request
identifierValuepathstringrequiredThe value of the selected identifier

Request body (required)

application/json · promotions-promotionDataCreate

FieldTypeRequiredDescription
visibilityStatusenum<"DRAFT", "PUBLISH", "HIDDEN">optionalProfile-oriented status of the promotion.
typeenum<"MEMBERS_ONLY", "HANDBILL", "CUSTOM", "GENERAL">optionalPromotion type
redeemLimitPerClientintegeroptionalLimit how many times a Profile can redeem this promotion.
redeemQuantityPerActivationintegeroptionalHow many times per activation a multibuy promotion can be redeemed
redeemLimitGlobalintegeroptionalLimit the total of redemptions by all Profiles
redeemTypeenum<"FULL", "PARTIAL">optionalPromotion redemption type
detailsobjectoptionalPromotion details
discountTypeenum<"PERCENT", "POINTS", "AMOUNT", "NONE", …>optionalThe type of discount
discountValuenumberoptionalHow much discount to apply
discountModeenum<"STATIC", "STEP">optionalPromotion discount mode
discountModeDetailsobjectoptionalApplies only when "discountMode": "STEP".
preDiscountValuenumberoptionalIn single-item promotions, this is the price of the item before the discount. This is in regular units of currency. For example, if the currency is USD and preDiscountValue is set to 1.2, the price before discount is 1 dollar and 20 cents.
requireRedeemedPointsnumberoptionalHow many loyalty points are needed to activate the promotion
headerNamestringoptionalName displayed in Synerise Web UI
headerDescriptionstringoptionalDescription displayed in Synerise Web UI
namestringoptionalPromotion name displayed to viewers
headlinestringoptionalPromotion headline displayed to viewers
descriptionstringoptionalDetails of the promotion displayed to viewers
imagesarray<object>optionalImages and thumbnails for the promotion
tagsarray<object>optionalAn array of tags. IMPORTANT: To be able to use a tag for promotions, you must first assign the tag to a directory with "type":"promotion". If the directory type does not exist, create it using this endpoint. Then create a directory of that type and assign tags to it.
startAtstringoptionalTime when the promotion becomes available. Defaults to current time.
expireAtstringoptionalTime when the promotion ends for all profiles. Defaults to current time. Has to be greater than startAt
displayFromstringoptionalTime when the promotion becomes displayable. Defaults to null.
displayTostringoptionalTime when the promotion stops being displayed for users. Defaults to null. Has to be greater than displayFrom.
lastingTimeintegeroptionalDuration of the promotion in seconds. This countdown starts when the profile activates a promotion and is individual for each profile.
paramsobjectoptionalA JSON object with any custom parameters of type string, object, array.
itemScopeenum<"LINE_ITEM", "BASKET">optionalThe scope of of the promotion. LINE_ITEM is a promotion used for certain items in the basket BASKET is a promotion that applies to the entire basket
minBasketValuenumberoptionalMinimal basket value required to trigger the application of the promotion. This is the basket value after calculating other promotions that apply to the items in the basket. minBasketValue must be lower than maxBasketValue.
maxBasketValuenumberoptionalThe maximum basket value to apply the promotion to. Any amount above the maximum is not discounted. This is the basket value after calculating other promotions that apply to the items in the basket. maxBasketValue must be greater than minBasketValue Example: The maximum basket value is set to 500 USD. The discount is 10%. A basket's total is 700 USD. The discount is 50 USD.
catalogstringoptionalID of the item catalog that the promotion applies to
catalogItemTypeenum<"ALL", "SELECTED", "FILTERED", "QUERY">optional If set to "ALL", define the catalog in the catalog field and set catalogIndexItems to null. If set to "SELECTED", define the catalog in the catalog field and provide a list of catalog items in catalogIndexItems. If set to "FILTERED", define the catalog in the catalog field and provide a list of catalog filter ids in catalogFilterIds. If set to "QUERY", define the catalog in the catalog field and provide an inline RSQL expression in catalogFilterQuery.
catalogIndexItemsarray<string>optional'An array of items from the catalog to be included in the promotion if catalogItemType is set to SELECTED. If catalogItemType is set to ALL, set catalogIndexItems to null.'
catalogFilterIdsarray<string>optional'An array of catalog filter IDs to be executed to fetch catalog items if catalogItemType is set to FILTERED. If catalogItemType is set to ALL, set catalogFilterIds to null.'
catalogFilterQuerystringoptionalAn RSQL expression that the Catalogs API resolves to matching catalog items when catalogItemType is set to QUERY. This field is required when catalogItemType is set to QUERY. A catalog must also be defined. Otherwise, set this field to null. Structure An expression consists of one or more rules joined by: ; — AND , — OR RSQL expressions are case-insensitive. Attribute predicates Operator Type Meaning Example == string / number / boolean Equals category==shampoo != string / number Does not equal brand!=Nivea =in=(a,b,…) string Value is in the set sku=in=(SKU1,SKU2) =out=(a,b,…) string Value is not in the set brand=out=(Nivea,Dove) =contains= string Value contains the specified string brand=contains=nike =startsWith= string Value starts with the specified string brand=startsWith=nik =endsWith= string Value ends with the specified string brand=endsWith=ike > / =gt= number Greater than price>2 >= / =gte= number Greater than or equal to price>=2 < / =lt= number Less than price<2 <= / =lte= number Less than or equal to price<=2 Important: Attributes used in the expression must be indexed in the catalog. Read more about indexing catalogs.
excludeCatalogstringoptionalID of the item catalog that the promotion should exclude
excludeCatalogItemTypeenum<"ALL", "SELECTED", "FILTERED", "QUERY">optional If set to "ALL", define the catalog in the excludeCatalog field and set excludeCatalogIndexItems to null. If set to "SELECTED", define the catalog in the excludeCatalog field and provide a list of catalog items in excludeCatalogIndexItems. If set to "FILTERED", define the catalog in the excludeCatalog field and provide a list of catalog filter ids in excludeCatalogFilterIds. If set to "QUERY", define the catalog in the excludeCatalog field and provide an inline RSQL expression in excludeCatalogFilterQuery.
excludeCatalogIndexItemsarray<string>optional'An array of items from the catalog to be excluded in the promotion if excludeCatalogItemType is set to SELECTED. If excludeCatalogItemType is set to ALL, set excludeCatalogIndexItems to null.'
excludeCatalogFilterIdsarray<string>optional'An array of catalog filter IDs to be executed to fetch catalog items to exclude if excludeCatalogItemType is set to FILTERED. If excludeCatalogItemType is set to ALL, set excludeCatalogFilterIds to null.'
excludeCatalogFilterQuerystringoptional'An inline RSQL expression resolved by Catalogs into the catalog items to exclude if excludeCatalogItemType is set to QUERY. Required (and excludeCatalog must be defined) when excludeCatalogItemType is QUERY; otherwise set to null.'
activationLimitGlobalTypeenum<"RELATIVE", "LIFETIME">optionalPromotion activation limit type LIFETIME – No additional configuration required. The limit applies to the entire lifespan of the promotion. * RELATIVE – Requires specifying a relative time window (number of minutes from the current time).
activationLimitGlobalLimitintegeroptionalLimit the total of activations by all Profiles within given time unit.
activationLimitGlobalRelativeMinutesintegeroptionalUsed only when type is RELATIVE. Defines how many minutes back from the current time the limit applies.
storeCatalogstringoptionalID of the store catalog that the promotion applies to
storeItemTypeenum<"ALL", "SELECTED">optionalDefines if the promotion is available for the entire store catalog or only certain stores (listed in storeIds).
storeIdsarray<string>optionalAn array of stores from the store catalog where the promotion is available if storeItemType is set to SELECTED
targetTypeenum<"ALL", "SEGMENT">optionalIf this field is set to "SEGMENT", you must provide a list of segments in targetSegment.
targetSegmentarray<string>optionalThis field applies only when targetType is set to "SEGMENT".
priceintegeroptionalIn single-item promotions, this is the price of the item in the smallest unit of currency. For example, if the currency is USD and price is 120, the price is 1 dollar and 20 cents.
priorityintegeroptionalDefines the promotion's priority, used both for display order and to order candidate promotions when they are selected during handbill and checkout assignment. Values are ordered ascending, so a lower number means a higher priority and 1 is the highest. When the per-slot read limit or the AI request cap truncates the candidate list, the higher-priority (lower-numbered) promotions are the ones kept. Promotions that share the same priority have no further guaranteed ordering between them, so when a truncation boundary falls inside a group of equal priority it is not defined which of them are kept — assign distinct priorities to the promotions that must always win.
voucherPoolobjectoptionalSettings for assigning codes from a voucher pool when the promotion is activated. When this is used, a promotion can only be redeemed once per activation.
importHashstringoptionalHash of the import

Responses

StatusDescription
200 application/jsonPromotion updated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/v4/promotions/promotion/%7BidentifierType%7D/%7BidentifierValue%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"visibilityStatus":"DRAFT","type":"MEMBERS_ONLY","redeemLimitPerClient":0,"redeemQuantityPerActivation":8388607,"redeemLimitGlobal":0,"redeemType":"FULL","details":{"discountType":{"name":"BOGO","outerScope":true,"requiredItemsCount":2,"requiredItems":{"catalog":"221","catalogItemType":"FILTERED","catalogIndexItems":[],"catalogFilterIds":["f978b20f-7156-40ed-99c2-3af62b76af12"],"catalogFilterQuery":"color==green;price=lt=100"},"discountedItemsCount":1},"cashbackSettings":{"exchangeRate":0.0001,"limits":{"minPoints":10,"maxPoints":1000,"maxTransactionAmount":20,"maxTransactionPercentage":50}}},"discountType":"PERCENT","discountValue":0,"discountMode":"STATIC","discountModeDetails":{"steps":[{"discountValue":0,"usageThreshold":0}],"discountUsageTrigger":"TRANSACTION"},"preDiscountValue":0,"requireRedeemedPoints":0,"headerName":"string","headerDescription":"string","name":"string","headline":"string","description":"string","images":[{"url":"https://www.snrcdn.net/upload/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/1537188683527-el-ipadpro.png","type":"image"}],"tags":[{"hash":"6f54671d-157f-4c4e-a577-11fac3111293"}],"startAt":"2019-08-24T14:15:22Z","expireAt":"2019-08-24T14:15:22Z","displayFrom":"string","displayTo":"string","lastingTime":0,"params":{},"itemScope":"LINE_ITEM","minBasketValue":null,"maxBasketValue":null,"catalog":"221","catalogItemType":"FILTERED","catalogIndexItems":[],"catalogFilterIds":["f978b20f-7156-40ed-99c2-3af62b76af12"],"catalogFilterQuery":"color==green;price=lt=100","excludeCatalog":["311"],"excludeCatalogItemType":"SELECTED","excludeCatalogIndexItems":["29727276"],"excludeCatalogFilterIds":[],"excludeCatalogFilterQuery":"brand==acme","activationLimitGlobalType":"RELATIVE","activationLimitGlobalLimit":1,"activationLimitGlobalRelativeMinutes":null,"storeCatalog":"string","storeItemType":"ALL","storeIds":["string"],"targetType":"ALL","targetSegment":["string"],"price":0,"priority":250,"voucherPool":{"enabled":false,"uuid":"095be615-a8ad-4c33-8e9c-c7612fbf6c9f","transferable":false},"importHash":"ced8a4ad-6d6e-48ca-a663-3fb07e6216a9"}'

GET /v4/promotions/promotion/get-for-client-by-custom-settings/{identifierType}/{identifierValue} — Get Profile promotions by a custom filter

/api-reference/loyalty-and-engagement#tag/Promotions/operation/GetClientPromotionsByACustomFilter

Self-contained method YAML

Retrieve a list of promotions related to a Profile by a custom, pre-defined filter.

The filter is maintained by your backend administrator.

IMPORTANT:

  • As a result of this request, the targetSegments of all the matching promotions are checked. If this results in checking more than 100 unique segments, any segments above this limit may be ignored.
  • The endpoint is limited to 25000 requests per minute (per workspace).

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_GET_FOR_CLIENT_BY_CUSTOM_SETTINGS_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
lockIdentifierquerystringoptionalIdentifier of the lock which will be created with this request. The lock disables the profile's possibility to fetch promotion lists. This lock will be active until one of those conditions is met: the TTL (configured with the settings endpoint) expires. it is removed using the Release "promotion requested" lock endpoint. a promotion is redeemed and this lock's identifier is provided with the redemption request.

Responses

StatusDescription
200 application/jsonAn array of promotions
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
409 application/jsonWaiting for profile lock release

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/get-for-client-by-custom-settings/email/%7BidentifierValue%7D?page=4&limit=100&lockIdentifier=6561d87b-2697-46ad-8f9a-0550736b86e3' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /v4/promotions/promotion/activate-for-client/{identifierType}/{identifierValue} — Activate a promotion as Workspace

/api-reference/loyalty-and-engagement#tag/Promotions/operation/ActivateAPromotionAsProfile

Self-contained method YAML

You can change the status of a Profile's promotion from assigned to active, the promotion can now be applied to a purchase.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_ACTIVATE_PROMOTIONS_UPDATE

User role permission required: campaigns_promotions: update

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier

Request body (required)

application/json · promotions-promotionActivation

FieldTypeRequiredDescription
keyenum<"uuid", "code">requiredType of promotion identifier
valuestringrequiredValue of the selected identifier
pointsToUseintegeroptionalHow many points should be converted to digital money and stored as ready to redeem in transactions in digital cashback promotions.

Responses

StatusDescription
200 application/jsonPromotion activated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found
409 application/jsonWaiting for profile lock release
412 application/jsonAlready activated/Already redeemed/Activation limit reached/Promotion not started/Promotion expired
422 application/jsonGlobal Activation limit reached
423 application/jsonProfile promotions blocked
500General error

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/activate-for-client/email/%7BidentifierValue%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"key":"code","value":"7893467834GG","pointsToUse":100}'

POST /v4/promotions/promotion/batch-activate-for-client/{identifierType}/{identifierValue} — Batch activate promotions as Workspace

/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchActivateAsProfile

Self-contained method YAML

You can change the status of a number of Profile's promotions promotion from assigned to active, the promotion can now be applied to a purchase. This method can't be used to activate promotions which require voucher assignment. You need to activate such promotions individually.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_BATCH_ACTIVATE_PROMOTIONS_UPDATE

User role permission required: campaigns_promotions: update

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier

Request body (required)

application/json · array<promotions-promotionActivation>

Responses

StatusDescription
200 application/jsonPromotions activated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found
409 application/jsonWaiting for profile lock release
412 application/jsonAlready activated/Already redeemed/Activation limit reached/Promotion not started/Promotion expired
500General error

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/batch-activate-for-client/email/%7BidentifierValue%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"key":"code","value":"7893467834GG","pointsToUse":100}]'

POST /v4/promotions/promotion/deactivate-for-client/{identifierType}/{identifierValue} — Deactivate a promotion as Workspace

/api-reference/loyalty-and-engagement#tag/Promotions/operation/DeactivateAPromotionProfile

Self-contained method YAML

You can change the status of a Profile's activated promotion back to assigned.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_DEACTIVATE_PROMOTIONS_UPDATE

User role permission required: campaigns_promotions: update

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier

Request body (required)

application/json · promotions-promotionActivation

FieldTypeRequiredDescription
keyenum<"uuid", "code">requiredType of promotion identifier
valuestringrequiredValue of the selected identifier
pointsToUseintegeroptionalHow many points should be converted to digital money and stored as ready to redeem in transactions in digital cashback promotions.

Responses

StatusDescription
200 application/jsonPromotion deactivated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found
429 application/jsonWaiting for profile lock release

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/deactivate-for-client/email/%7BidentifierValue%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"key":"code","value":"7893467834GG","pointsToUse":100}'

POST /v4/promotions/promotion/batch-deactivate-for-client/{identifierType}/{identifierValue} — Batch deactivate promotions

/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchDeactivateAsProfile

Self-contained method YAML

You can change the status of a number of Profile's activated promotions back to assigned.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_BATCH_DEACTIVATE_PROMOTIONS_UPDATE

User role permission required: campaigns_promotions: update

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier

Request body (required)

application/json · array<promotions-promotionActivation>

Responses

StatusDescription
200 application/jsonPromotions deactivated
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found
429 application/jsonWaiting for profile lock release

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/batch-deactivate-for-client/email/%7BidentifierValue%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"key":"code","value":"7893467834GG","pointsToUse":100}]'

POST /v4/promotions/promotion — Create a promotion

/api-reference/loyalty-and-engagement#tag/Promotions/operation/CreateAPromotion

Self-contained method YAML

You can create a new promotion in the Synerise application.

If you don't enter a code or UUID, they are generated automatically.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_PROMOTIONS_CREATE

User role permission required: campaigns_promotions: create

Request body (required)

application/json · promotions-promotionDataCreate

FieldTypeRequiredDescription
visibilityStatusenum<"DRAFT", "PUBLISH", "HIDDEN">optionalProfile-oriented status of the promotion.
typeenum<"MEMBERS_ONLY", "HANDBILL", "CUSTOM", "GENERAL">optionalPromotion type
redeemLimitPerClientintegeroptionalLimit how many times a Profile can redeem this promotion.
redeemQuantityPerActivationintegeroptionalHow many times per activation a multibuy promotion can be redeemed
redeemLimitGlobalintegeroptionalLimit the total of redemptions by all Profiles
redeemTypeenum<"FULL", "PARTIAL">optionalPromotion redemption type
detailsobjectoptionalPromotion details
discountTypeenum<"PERCENT", "POINTS", "AMOUNT", "NONE", …>optionalThe type of discount
discountValuenumberoptionalHow much discount to apply
discountModeenum<"STATIC", "STEP">optionalPromotion discount mode
discountModeDetailsobjectoptionalApplies only when "discountMode": "STEP".
preDiscountValuenumberoptionalIn single-item promotions, this is the price of the item before the discount. This is in regular units of currency. For example, if the currency is USD and preDiscountValue is set to 1.2, the price before discount is 1 dollar and 20 cents.
requireRedeemedPointsnumberoptionalHow many loyalty points are needed to activate the promotion
headerNamestringoptionalName displayed in Synerise Web UI
headerDescriptionstringoptionalDescription displayed in Synerise Web UI
namestringoptionalPromotion name displayed to viewers
headlinestringoptionalPromotion headline displayed to viewers
descriptionstringoptionalDetails of the promotion displayed to viewers
imagesarray<object>optionalImages and thumbnails for the promotion
tagsarray<object>optionalAn array of tags. IMPORTANT: To be able to use a tag for promotions, you must first assign the tag to a directory with "type":"promotion". If the directory type does not exist, create it using this endpoint. Then create a directory of that type and assign tags to it.
startAtstringoptionalTime when the promotion becomes available. Defaults to current time.
expireAtstringoptionalTime when the promotion ends for all profiles. Defaults to current time. Has to be greater than startAt
displayFromstringoptionalTime when the promotion becomes displayable. Defaults to null.
displayTostringoptionalTime when the promotion stops being displayed for users. Defaults to null. Has to be greater than displayFrom.
lastingTimeintegeroptionalDuration of the promotion in seconds. This countdown starts when the profile activates a promotion and is individual for each profile.
paramsobjectoptionalA JSON object with any custom parameters of type string, object, array.
itemScopeenum<"LINE_ITEM", "BASKET">optionalThe scope of of the promotion. LINE_ITEM is a promotion used for certain items in the basket BASKET is a promotion that applies to the entire basket
minBasketValuenumberoptionalMinimal basket value required to trigger the application of the promotion. This is the basket value after calculating other promotions that apply to the items in the basket. minBasketValue must be lower than maxBasketValue.
maxBasketValuenumberoptionalThe maximum basket value to apply the promotion to. Any amount above the maximum is not discounted. This is the basket value after calculating other promotions that apply to the items in the basket. maxBasketValue must be greater than minBasketValue Example: The maximum basket value is set to 500 USD. The discount is 10%. A basket's total is 700 USD. The discount is 50 USD.
catalogstringoptionalID of the item catalog that the promotion applies to
catalogItemTypeenum<"ALL", "SELECTED", "FILTERED", "QUERY">optional If set to "ALL", define the catalog in the catalog field and set catalogIndexItems to null. If set to "SELECTED", define the catalog in the catalog field and provide a list of catalog items in catalogIndexItems. If set to "FILTERED", define the catalog in the catalog field and provide a list of catalog filter ids in catalogFilterIds. If set to "QUERY", define the catalog in the catalog field and provide an inline RSQL expression in catalogFilterQuery.
catalogIndexItemsarray<string>optional'An array of items from the catalog to be included in the promotion if catalogItemType is set to SELECTED. If catalogItemType is set to ALL, set catalogIndexItems to null.'
catalogFilterIdsarray<string>optional'An array of catalog filter IDs to be executed to fetch catalog items if catalogItemType is set to FILTERED. If catalogItemType is set to ALL, set catalogFilterIds to null.'
catalogFilterQuerystringoptionalAn RSQL expression that the Catalogs API resolves to matching catalog items when catalogItemType is set to QUERY. This field is required when catalogItemType is set to QUERY. A catalog must also be defined. Otherwise, set this field to null. Structure An expression consists of one or more rules joined by: ; — AND , — OR RSQL expressions are case-insensitive. Attribute predicates Operator Type Meaning Example == string / number / boolean Equals category==shampoo != string / number Does not equal brand!=Nivea =in=(a,b,…) string Value is in the set sku=in=(SKU1,SKU2) =out=(a,b,…) string Value is not in the set brand=out=(Nivea,Dove) =contains= string Value contains the specified string brand=contains=nike =startsWith= string Value starts with the specified string brand=startsWith=nik =endsWith= string Value ends with the specified string brand=endsWith=ike > / =gt= number Greater than price>2 >= / =gte= number Greater than or equal to price>=2 < / =lt= number Less than price<2 <= / =lte= number Less than or equal to price<=2 Important: Attributes used in the expression must be indexed in the catalog. Read more about indexing catalogs.
excludeCatalogstringoptionalID of the item catalog that the promotion should exclude
excludeCatalogItemTypeenum<"ALL", "SELECTED", "FILTERED", "QUERY">optional If set to "ALL", define the catalog in the excludeCatalog field and set excludeCatalogIndexItems to null. If set to "SELECTED", define the catalog in the excludeCatalog field and provide a list of catalog items in excludeCatalogIndexItems. If set to "FILTERED", define the catalog in the excludeCatalog field and provide a list of catalog filter ids in excludeCatalogFilterIds. If set to "QUERY", define the catalog in the excludeCatalog field and provide an inline RSQL expression in excludeCatalogFilterQuery.
excludeCatalogIndexItemsarray<string>optional'An array of items from the catalog to be excluded in the promotion if excludeCatalogItemType is set to SELECTED. If excludeCatalogItemType is set to ALL, set excludeCatalogIndexItems to null.'
excludeCatalogFilterIdsarray<string>optional'An array of catalog filter IDs to be executed to fetch catalog items to exclude if excludeCatalogItemType is set to FILTERED. If excludeCatalogItemType is set to ALL, set excludeCatalogFilterIds to null.'
excludeCatalogFilterQuerystringoptional'An inline RSQL expression resolved by Catalogs into the catalog items to exclude if excludeCatalogItemType is set to QUERY. Required (and excludeCatalog must be defined) when excludeCatalogItemType is QUERY; otherwise set to null.'
activationLimitGlobalTypeenum<"RELATIVE", "LIFETIME">optionalPromotion activation limit type LIFETIME – No additional configuration required. The limit applies to the entire lifespan of the promotion. * RELATIVE – Requires specifying a relative time window (number of minutes from the current time).
activationLimitGlobalLimitintegeroptionalLimit the total of activations by all Profiles within given time unit.
activationLimitGlobalRelativeMinutesintegeroptionalUsed only when type is RELATIVE. Defines how many minutes back from the current time the limit applies.
storeCatalogstringoptionalID of the store catalog that the promotion applies to
storeItemTypeenum<"ALL", "SELECTED">optionalDefines if the promotion is available for the entire store catalog or only certain stores (listed in storeIds).
storeIdsarray<string>optionalAn array of stores from the store catalog where the promotion is available if storeItemType is set to SELECTED
targetTypeenum<"ALL", "SEGMENT">optionalIf this field is set to "SEGMENT", you must provide a list of segments in targetSegment.
targetSegmentarray<string>optionalThis field applies only when targetType is set to "SEGMENT".
priceintegeroptionalIn single-item promotions, this is the price of the item in the smallest unit of currency. For example, if the currency is USD and price is 120, the price is 1 dollar and 20 cents.
priorityintegeroptionalDefines the promotion's priority, used both for display order and to order candidate promotions when they are selected during handbill and checkout assignment. Values are ordered ascending, so a lower number means a higher priority and 1 is the highest. When the per-slot read limit or the AI request cap truncates the candidate list, the higher-priority (lower-numbered) promotions are the ones kept. Promotions that share the same priority have no further guaranteed ordering between them, so when a truncation boundary falls inside a group of equal priority it is not defined which of them are kept — assign distinct priorities to the promotions that must always win.
voucherPoolobjectoptionalSettings for assigning codes from a voucher pool when the promotion is activated. When this is used, a promotion can only be redeemed once per activation.
importHashstringoptionalHash of the import

Responses

StatusDescription
201 application/jsonPromotion created
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"visibilityStatus":"DRAFT","type":"MEMBERS_ONLY","redeemLimitPerClient":0,"redeemQuantityPerActivation":8388607,"redeemLimitGlobal":0,"redeemType":"FULL","details":{"discountType":{"name":"BOGO","outerScope":true,"requiredItemsCount":2,"requiredItems":{"catalog":"221","catalogItemType":"FILTERED","catalogIndexItems":[],"catalogFilterIds":["f978b20f-7156-40ed-99c2-3af62b76af12"],"catalogFilterQuery":"color==green;price=lt=100"},"discountedItemsCount":1},"cashbackSettings":{"exchangeRate":0.0001,"limits":{"minPoints":10,"maxPoints":1000,"maxTransactionAmount":20,"maxTransactionPercentage":50}}},"discountType":"PERCENT","discountValue":0,"discountMode":"STATIC","discountModeDetails":{"steps":[{"discountValue":0,"usageThreshold":0}],"discountUsageTrigger":"TRANSACTION"},"preDiscountValue":0,"requireRedeemedPoints":0,"headerName":"string","headerDescription":"string","name":"string","headline":"string","description":"string","images":[{"url":"https://www.snrcdn.net/upload/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/1537188683527-el-ipadpro.png","type":"image"}],"tags":[{"hash":"6f54671d-157f-4c4e-a577-11fac3111293"}],"startAt":"2019-08-24T14:15:22Z","expireAt":"2019-08-24T14:15:22Z","displayFrom":"string","displayTo":"string","lastingTime":0,"params":{},"itemScope":"LINE_ITEM","minBasketValue":null,"maxBasketValue":null,"catalog":"221","catalogItemType":"FILTERED","catalogIndexItems":[],"catalogFilterIds":["f978b20f-7156-40ed-99c2-3af62b76af12"],"catalogFilterQuery":"color==green;price=lt=100","excludeCatalog":["311"],"excludeCatalogItemType":"SELECTED","excludeCatalogIndexItems":["29727276"],"excludeCatalogFilterIds":[],"excludeCatalogFilterQuery":"brand==acme","activationLimitGlobalType":"RELATIVE","activationLimitGlobalLimit":1,"activationLimitGlobalRelativeMinutes":null,"storeCatalog":"string","storeItemType":"ALL","storeIds":["string"],"targetType":"ALL","targetSegment":["string"],"price":0,"priority":250,"voucherPool":{"enabled":false,"uuid":"095be615-a8ad-4c33-8e9c-c7612fbf6c9f","transferable":false},"importHash":"ced8a4ad-6d6e-48ca-a663-3fb07e6216a9"}'

DELETE /v4/promotions/promotion — Delete a promotion

/api-reference/loyalty-and-engagement#tag/Promotions/operation/DeleteAPromotion

Self-contained method YAML

This method is used to delete an existing promotion. It can be used by a backend business administrator.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_PROMOTIONS_DELETE

User role permission required: campaigns_promotions: delete

Request body (required)

application/json · promotions-promotionDataDelete

FieldTypeRequiredDescription
valuestringrequiredCode of the promotion to delete

Responses

StatusDescription
200 application/jsonPromotion deleted
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonProfile, promotion, or related resource not found
409 application/jsonWaiting for profile lock release

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/v4/promotions/promotion \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"value":"string"}'

POST /v4/promotions/promotion/create-or-update — Create or update a promotion

/api-reference/loyalty-and-engagement#tag/Promotions/operation/CreateOrUpdateAPromotion

Self-contained method YAML

You can use this endpoint to create a new promotion or update an existing one that matches the UUID or promotion code that you send.

When updating an existing promotion include only the fields that you want to change. Inserting a null value overwrites an existing value.

API consumers: Workspace (Business Profile), Synerise User

API key permissions required (at least one): PROMOTIONS_PROMOTIONS_CREATE, PROMOTIONS_PROMOTIONS_UPDATE

User role permission required: campaigns_promotions: create

Request body (required)

application/json · promotions-promotionDataCreateOrUpdate

FieldTypeRequiredDescription
uuidstringoptionalUnique UUIDv4.
codestringoptionalUnique code
visibilityStatusenum<"DRAFT", "PUBLISH", "HIDDEN">optionalProfile-oriented status of the promotion.
typeenum<"MEMBERS_ONLY", "HANDBILL", "CUSTOM", "GENERAL">optionalPromotion type
redeemLimitPerClientintegeroptionalLimit how many times a Profile can redeem this promotion.
redeemQuantityPerActivationintegeroptionalHow many times per activation a multibuy promotion can be redeemed
redeemLimitGlobalintegeroptionalLimit the total of redemptions by all Profiles
redeemTypeenum<"FULL", "PARTIAL">optionalPromotion redemption type
discountTypeenum<"PERCENT", "POINTS", "AMOUNT", "NONE", …>optionalThe type of discount
detailsobjectoptionalPromotion details
discountValuenumberoptionalHow much discount to apply
discountModeenum<"STATIC", "STEP">optionalPromotion discount mode
discountModeDetailsobjectoptionalApplies only when "discountMode": "STEP".
preDiscountValuenumberoptionalIn single-item promotions, this is the price of the item before the discount. This is in regular units of currency. For example, if the currency is USD and preDiscountValue is set to 1.2, the price before discount is 1 dollar and 20 cents.
requireRedeemedPointsnumberoptionalHow many loyalty points are needed to activate the promotion
headerNamestringoptionalName displayed in Synerise Web UI
headerDescriptionstringoptionalDescription displayed in Synerise Web UI
namestringoptionalPromotion name displayed to viewers
headlinestringoptionalPromotion headline displayed to viewers
descriptionstringoptionalDetails of the promotion displayed to viewers
imagesarray<object>optionalImages and thumbnails for the promotion
tagsarray<object>optionalAn array of tags. IMPORTANT: To be able to use a tag for promotions, you must first assign the tag to a directory with "type":"promotion". If the directory type does not exist, create it using this endpoint. Then create a directory of that type and assign tags to it.
startAtstringoptionalTime when the promotion becomes available. Defaults to current time.
expireAtstringoptionalTime when the promotion ends for all profiles. Defaults to current time. Has to be greater than startAt
displayFromstringoptionalTime when the promotion becomes displayable. Defaults to null.
displayTostringoptionalTime when the promotion stops being displayed for users. Defaults to null. Has to be greater than displayFrom.
lastingTimeintegeroptionalDuration of the promotion in seconds. This countdown starts when the profile activates a promotion and is individual for each profile.
paramsobjectoptionalA JSON object with any custom parameters of type string, object, array.
itemScopeenum<"LINE_ITEM", "BASKET">optionalThe scope of of the promotion. LINE_ITEM is a promotion used for certain items in the basket BASKET is a promotion that applies to the entire basket
minBasketValuenumberoptionalMinimal basket value required to trigger the application of the promotion. This is the basket value after calculating other promotions that apply to the items in the basket. minBasketValue must be lower than maxBasketValue.
maxBasketValuenumberoptionalThe maximum basket value to apply the promotion to. Any amount above the maximum is not discounted. This is the basket value after calculating other promotions that apply to the items in the basket. maxBasketValue must be greater than minBasketValue Example: The maximum basket value is set to 500 USD. The discount is 10%. A basket's total is 700 USD. The discount is 50 USD.
catalogstringoptionalID of the item catalog that the promotion applies to
catalogItemTypeenum<"ALL", "SELECTED", "FILTERED", "QUERY">optional If set to "ALL", define the catalog in the catalog field and set catalogIndexItems to null. If set to "SELECTED", define the catalog in the catalog field and provide a list of catalog items in catalogIndexItems. If set to "FILTERED", define the catalog in the catalog field and provide a list of catalog filter ids in catalogFilterIds. If set to "QUERY", define the catalog in the catalog field and provide an inline RSQL expression in catalogFilterQuery.
catalogIndexItemsarray<string>optional'An array of items from the catalog to be included in the promotion if catalogItemType is set to SELECTED. If catalogItemType is set to ALL, set catalogIndexItems to null.'
catalogFilterIdsarray<string>optional'An array of catalog filter IDs to be executed to fetch catalog items if catalogItemType is set to FILTERED. If catalogItemType is set to ALL, set catalogFilterIds to null.'
catalogFilterQuerystringoptionalAn RSQL expression that the Catalogs API resolves to matching catalog items when catalogItemType is set to QUERY. This field is required when catalogItemType is set to QUERY. A catalog must also be defined. Otherwise, set this field to null. Structure An expression consists of one or more rules joined by: ; — AND , — OR RSQL expressions are case-insensitive. Attribute predicates Operator Type Meaning Example == string / number / boolean Equals category==shampoo != string / number Does not equal brand!=Nivea =in=(a,b,…) string Value is in the set sku=in=(SKU1,SKU2) =out=(a,b,…) string Value is not in the set brand=out=(Nivea,Dove) =contains= string Value contains the specified string brand=contains=nike =startsWith= string Value starts with the specified string brand=startsWith=nik =endsWith= string Value ends with the specified string brand=endsWith=ike > / =gt= number Greater than price>2 >= / =gte= number Greater than or equal to price>=2 < / =lt= number Less than price<2 <= / =lte= number Less than or equal to price<=2 Important: Attributes used in the expression must be indexed in the catalog. Read more about indexing catalogs.
excludeCatalogstringoptionalID of the item catalog that the promotion should exclude
excludeCatalogItemTypeenum<"ALL", "SELECTED", "FILTERED", "QUERY">optional If set to "ALL", define the catalog in the excludeCatalog field and set excludeCatalogIndexItems to null. If set to "SELECTED", define the catalog in the excludeCatalog field and provide a list of catalog items in excludeCatalogIndexItems. If set to "FILTERED", define the catalog in the excludeCatalog field and provide a list of catalog filter ids in excludeCatalogFilterIds. If set to "QUERY", define the catalog in the excludeCatalog field and provide an inline RSQL expression in excludeCatalogFilterQuery.
excludeCatalogIndexItemsarray<string>optional'An array of items from the catalog to be excluded in the promotion if excludeCatalogItemType is set to SELECTED. If excludeCatalogItemType is set to ALL, set excludeCatalogIndexItems to null.'
excludeCatalogFilterIdsarray<string>optional'An array of catalog filter IDs to be executed to fetch catalog items to exclude if excludeCatalogItemType is set to FILTERED. If excludeCatalogItemType is set to ALL, set excludeCatalogFilterIds to null.'
excludeCatalogFilterQuerystringoptional'An inline RSQL expression resolved by Catalogs into the catalog items to exclude if excludeCatalogItemType is set to QUERY. Required (and excludeCatalog must be defined) when excludeCatalogItemType is QUERY; otherwise set to null.'
storeCatalogstringoptionalID of the store catalog that the promotion applies to
storeItemTypeenum<"ALL", "SELECTED">optionalDefines if the promotion is available for the entire store catalog or only certain stores (listed in storeIds).
storeIdsarray<string>optionalAn array of stores from the store catalog where the promotion is available if storeItemType is set to SELECTED
targetTypeenum<"ALL", "SEGMENT">optionalIf this field is set to "SEGMENT", you must provide a list of segments in targetSegment.
targetSegmentarray<string>optionalThis field applies only when targetType is set to "SEGMENT".
priceintegeroptionalIn single-item promotions, this is the price of the item in the smallest unit of currency. For example, if the currency is USD and price is 120, the price is 1 dollar and 20 cents.
priorityintegeroptionalDefines the promotion's priority, used both for display order and to order candidate promotions when they are selected during handbill and checkout assignment. Values are ordered ascending, so a lower number means a higher priority and 1 is the highest. When the per-slot read limit or the AI request cap truncates the candidate list, the higher-priority (lower-numbered) promotions are the ones kept. Promotions that share the same priority have no further guaranteed ordering between them, so when a truncation boundary falls inside a group of equal priority it is not defined which of them are kept — assign distinct priorities to the promotions that must always win.
voucherPoolobjectoptionalSettings for assigning codes from a voucher pool when the promotion is activated. When this is used, a promotion can only be redeemed once per activation.
importHashstringoptionalHash of the import

Responses

StatusDescription
200 application/jsonPromotion updated
201 application/jsonPromotion created
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/promotion/create-or-update \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"uuid":"string","code":"string","visibilityStatus":"DRAFT","type":"MEMBERS_ONLY","redeemLimitPerClient":0,"redeemQuantityPerActivation":8388607,"redeemLimitGlobal":0,"redeemType":"FULL","discountType":"PERCENT","details":{"discountType":{"name":"BOGO","outerScope":true,"requiredItemsCount":2,"requiredItems":{"catalog":"221","catalogItemType":"FILTERED","catalogIndexItems":[],"catalogFilterIds":["f978b20f-7156-40ed-99c2-3af62b76af12"],"catalogFilterQuery":"color==green;price=lt=100"},"discountedItemsCount":1},"cashbackSettings":{"exchangeRate":0.0001,"limits":{"minPoints":10,"maxPoints":1000,"maxTransactionAmount":20,"maxTransactionPercentage":50}}},"discountValue":0,"discountMode":"STATIC","discountModeDetails":{"steps":[{"discountValue":0,"usageThreshold":0}],"discountUsageTrigger":"TRANSACTION"},"preDiscountValue":0,"requireRedeemedPoints":0,"headerName":"string","headerDescription":"string","name":"string","headline":"string","description":"string","images":[{"url":"https://www.snrcdn.net/upload/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/1537188683527-el-ipadpro.png","type":"image"}],"tags":[{"hash":"6f54671d-157f-4c4e-a577-11fac3111293"}],"startAt":"2019-08-24T14:15:22Z","expireAt":"2019-08-24T14:15:22Z","displayFrom":"string","displayTo":"string","lastingTime":0,"params":{},"itemScope":"LINE_ITEM","minBasketValue":null,"maxBasketValue":null,"catalog":"221","catalogItemType":"FILTERED","catalogIndexItems":[],"catalogFilterIds":["f978b20f-7156-40ed-99c2-3af62b76af12"],"catalogFilterQuery":"color==green;price=lt=100","excludeCatalog":["311"],"excludeCatalogItemType":"SELECTED","excludeCatalogIndexItems":["29727276"],"excludeCatalogFilterIds":[],"excludeCatalogFilterQuery":"brand==acme","storeCatalog":"string","storeItemType":"ALL","storeIds":["string"],"targetType":"ALL","targetSegment":["string"],"price":0,"priority":250,"voucherPool":{"enabled":false,"uuid":"095be615-a8ad-4c33-8e9c-c7612fbf6c9f","transferable":false},"importHash":"ced8a4ad-6d6e-48ca-a663-3fb07e6216a9"}'

POST /v4/promotions/voucher/batch-redeem — Batch redeem vouchers

/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchRedeemVouchers

Self-contained method YAML

You can redeem up to 100 vouchers.

API consumers: Profile (Client), Anonymous Profile

User role permission required: campaigns_promotions: create

Request body (required)

application/json · promotions-RedeemVouchersRequest

Responses

StatusDescription
200 application/jsonVouchers redeemed
207 application/jsonSome vouchers couldn't be redeemed

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/voucher/batch-redeem \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"voucherKey":"code","voucherValue":"75d9090f-06ac-46a2-a0ce-4b8eb287efb9","options":{"quantity":1,"sourceId":"75d9090f-06ac-46a2-a0ce-4b8eb287efb9-1","orderId":"75d9090f-06ac-46a2-a0ce-4b8eb287efb9-1","lockIdentifier":"75d9090f-06ac-46a2-a0ce-4b8eb287efb9"}}]'

POST /v4/promotions/voucher/batch-redeem-for-profile — Batch redeem vouchers for profiles

/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchRedeemVouchersForProfile

Self-contained method YAML

You can redeem up to 100 vouchers.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_BATCH_REDEEM_VOUCHERS_PROMOTIONS_CREATE

User role permission required: campaigns_promotions: create

Request body (required)

application/json · promotions-RedeemVouchersForProfileRequest

Responses

StatusDescription
200 application/jsonVouchers redeemed
207 application/jsonSome vouchers couldn't be redeemed

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/voucher/batch-redeem-for-profile \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[{"profileKey":"clientId","profileValue":"434428563","voucherKey":"code","voucherValue":"434428563","options":{"quantity":2,"sourceId":"3f0a1670-eb63-43f1-a6b8-895a74621964-3","orderId":"3f0a1670-eb63-43f1-a6b8-895a74621964"}}]'

POST /v4/promotions/v2/promotion/batch — Batch import promotions

/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchImportPromotions

Self-contained method YAML

Submit a batch of promotions for asynchronous import (upsert). Items are validated individually and queued for processing. Returns 202 if all items are valid, or 207 if some fail validation.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_IMPORT_PROMOTIONS_CREATE

User role permission required: campaigns_promotions: create

Request body (required)

application/json · promotions-PromotionImportBatchRequest

FieldTypeRequiredDescription
dataarray<promotions-promotionImportData>requiredArray of promotion objects to import (upsert)
extraobjectoptionalImport metadata

Responses

StatusDescription
202 application/jsonAll items accepted for processing
207 application/jsonSome items failed validation
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/v2/promotion/batch \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"data":[{"uuid":"string","code":"string","visibilityStatus":"DRAFT","type":"MEMBERS_ONLY","redeemLimitPerClient":0,"redeemQuantityPerActivation":8388607,"redeemLimitGlobal":0,"redeemType":"FULL","autoRedeem":true,"activationLimitGlobalType":"RELATIVE","activationLimitGlobalLimit":1,"activationLimitGlobalRelativeMinutes":null,"discountType":"PERCENT","details":{"discountType":{"name":"BOGO","outerScope":true,"requiredItemsCount":2,"requiredItems":{"catalog":"221","catalogItemType":"FILTERED","catalogIndexItems":[],"catalogFilterIds":["f978b20f-7156-40ed-99c2-3af62b76af12"],"catalogFilterQuery":"color==green;price=lt=100"},"discountedItemsCount":1},"cashbackSettings":{"exchangeRate":0.0001,"limits":{"minPoints":10,"maxPoints":1000,"maxTransactionAmount":20,"maxTransactionPercentage":50}}},"discountValue":0,"discountMode":"STATIC","discountModeDetails":{"steps":[{"discountValue":0,"usageThreshold":0}],"discountUsageTrigger":"TRANSACTION"},"preDiscountValue":0,"requireRedeemedPoints":0,"headerName":"string","headerDescription":"string","name":"string","headline":"string","description":"string","images":[{"url":"https://www.snrcdn.net/upload/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/1537188683527-el-ipadpro.png","type":"image"}],"tags":[{"hash":"6f54671d-157f-4c4e-a577-11fac3111293"}],"metric":"string","startAt":"2019-08-24T14:15:22Z","expireAt":"2019-08-24T14:15:22Z","displayFrom":"string","displayTo":"string","lastingTime":0,"params":{},"itemScope":"LINE_ITEM","minBasketValue":null,"maxBasketValue":null,"catalog":"string","catalogItemType":"FILTERED","catalogIndexItems":["string"],"catalogFilterIds":["string"],"catalogFilterQuery":"color==green;price=lt=100","excludeCatalog":"string","excludeCatalogItemType":"SELECTED","excludeCatalogIndexItems":["string"],"excludeCatalogFilterIds":["string"],"excludeCatalogFilterQuery":"brand==acme","storeCatalog":"string","storeItemType":"ALL","storeIds":["string"],"targetType":"ALL","targetSegment":["string"],"price":0,"priority":250,"voucherPool":{"enabled":false,"uuid":"095be615-a8ad-4c33-8e9c-c7612fbf6c9f","transferable":false}}],"extra":{"importHash":"string"}}'

DELETE /v4/promotions/v2/promotion/batch — Batch delete promotions

/api-reference/loyalty-and-engagement#tag/Promotions/operation/BatchDeletePromotions

Self-contained method YAML

Submit a batch of promotion codes for asynchronous deletion. Items are validated individually and queued for processing . Returns 202 if all items are valid, or 207 if some fail validation.
This method doesn't check if a promotion with the provide code exists.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_IMPORT_PROMOTIONS_DELETE

User role permission required: campaigns_promotions: delete

Request body (required)

application/json · promotions-PromotionDeleteBatchRequest

FieldTypeRequiredDescription
dataarray<promotions-PromotionDeleteItem>requiredArray of objects with promotion code to delete
extraobjectoptionalAdditional metadata

Responses

StatusDescription
202 application/jsonAll items accepted for processing
207 application/jsonSome items failed validation
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/v4/promotions/v2/promotion/batch \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"data":[{"code":"string"}],"extra":{"importHash":"string"}}'

POST /v4/promotions/v2/sale/process-sale/{identifierType}/{identifierValue} — Process basket

/api-reference/loyalty-and-engagement#tag/Promotions/operation/processSale_POST

Self-contained method YAML

Assign promotions to a basket and recalculate item values after discount.

This method DOES NOT redeem any promotions or create a transaction.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_SALE_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier

Request body

application/json · promotions-processSaleReq

FieldTypeRequiredDescription
operationIdintegerrequiredOperation ID
clientDateTimestringrequiredOperation's start time
terminalobjectrequiredData about the terminal that is the transaction's source
transactionMetricobjectrequiredMetadata of the transaction
finalValuestringrequiredThe total cost of all items in the basket, after discounts, including tax
transactionItemsarray<promotions-transactionItemWithoutGrants>requiredArray of transaction items
transactionAdditionalItemsarray<promotions-transactionAdditionalItem>requiredArray of additional items in the transaction
promotionsToActivatearray<promotions-promotionActivationProcessSale>optionalArray of promotions to activate during the sale process

Responses

StatusDescription
200 application/jsonBasket processed
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/v2/sale/process-sale/email/%7BidentifierValue%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"operationId":0,"clientDateTime":"2019-08-24T14:15:22Z","terminal":{"storeId":"string","posId":0},"transactionMetric":{"posTransactionId":0,"beginDateTime":null,"globalTransactionId":"string"},"finalValue":"string","transactionItems":[{"seqNo":0,"articleRef":"string","quantity":"3.231","evidPrice":"34.23","finalPrice":"30.23","finalValue":"123.23"}],"transactionAdditionalItems":[{"seqNo":0,"type":"COUPON","code":"string"}],"promotionsToActivate":[{"key":"code","value":"7893467834GG","pointsToUse":100}]}'

POST /v4/promotions/sale/process-checkout/{identifierType}/{identifierValue} — Process checkout on POS

/api-reference/loyalty-and-engagement#tag/Promotions/operation/processCheckout_POST

Self-contained method YAML

Assign checkout handbill coupons for a profile, based on items in the basket and historical transactions.

This method DOES NOT redeem any promotions or create a transaction.

IMPORTANT: When assigning handbill promotions, candidate promotions are bounded by configurable limits: at most 40,000 candidates are read per handbill slot (ordered by priority), and the total number of candidates sent to the recommendation (AI) engine in a single request is capped at 45,000. If the combined candidates across all slots exceed the AI request cap, each slot is reduced proportionally to the number of candidates it contributed, but never below a configurable per-slot floor (default 1,000), so the smallest slots are left intact.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_SALE_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier

Request body

application/json · promotions-processCheckoutReq

FieldTypeRequiredDescription
operationIdintegerrequiredOperation ID
clientDateTimestringrequiredOperation's start time
terminalobjectrequiredData about the terminal that is the transaction's source
transactionMetricobjectrequiredMetadata of the transaction
finalValuestringrequiredThe total cost of all items in the basket, after discounts, including tax
transactionItemsarray<promotions-transactionItemWithoutGrants>requiredArray of transaction items
transactionAdditionalItemsarray<promotions-transactionAdditionalItem>requiredArray of additional items in the transaction
paymentsReportobjectrequiredPayment information

Responses

StatusDescription
200 application/jsonPOS checkout processed
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/sale/process-checkout/email/%7BidentifierValue%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"operationId":0,"clientDateTime":"2019-08-24T14:15:22Z","terminal":{"storeId":"string","posId":0},"transactionMetric":{"posTransactionId":0,"beginDateTime":null,"globalTransactionId":"string"},"finalValue":"string","transactionItems":[{"seqNo":0,"articleRef":"string","quantity":"3.231","evidPrice":"34.23","finalPrice":"30.23","finalValue":"123.23"}],"transactionAdditionalItems":[{"seqNo":0,"type":"COUPON","code":"string"}],"paymentsReport":{"paymentItems":[{"seqNo":0,"type":0,"name":"string","amount":"string","hashCode":"string"}]}}'

POST /v4/promotions/v2/sale/process-anonymous-sale — Process anonymous Profile's basket

/api-reference/loyalty-and-engagement#tag/Promotions/operation/processAnonymousSale_POST

Self-contained method YAML

Assign promotions to a basket and recalculate item values after discount.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_SALE_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Request body

application/json · promotions-processSaleReq

FieldTypeRequiredDescription
operationIdintegerrequiredOperation ID
clientDateTimestringrequiredOperation's start time
terminalobjectrequiredData about the terminal that is the transaction's source
transactionMetricobjectrequiredMetadata of the transaction
finalValuestringrequiredThe total cost of all items in the basket, after discounts, including tax
transactionItemsarray<promotions-transactionItemWithoutGrants>requiredArray of transaction items
transactionAdditionalItemsarray<promotions-transactionAdditionalItem>requiredArray of additional items in the transaction
promotionsToActivatearray<promotions-promotionActivationProcessSale>optionalArray of promotions to activate during the sale process

Responses

StatusDescription
200 application/jsonBasket processed
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
428 application/jsonProperty discountSourceType in sale settings is not defined

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/v2/sale/process-anonymous-sale \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"operationId":0,"clientDateTime":"2019-08-24T14:15:22Z","terminal":{"storeId":"string","posId":0},"transactionMetric":{"posTransactionId":0,"beginDateTime":null,"globalTransactionId":"string"},"finalValue":"string","transactionItems":[{"seqNo":0,"articleRef":"string","quantity":"3.231","evidPrice":"34.23","finalPrice":"30.23","finalValue":"123.23"}],"transactionAdditionalItems":[{"seqNo":0,"type":"COUPON","code":"string"}],"promotionsToActivate":[{"key":"code","value":"7893467834GG","pointsToUse":100}]}'

POST /v4/promotions/sale/process-anonymous-checkout — Process anonymous Profile's checkout on POS

/api-reference/loyalty-and-engagement#tag/Promotions/operation/processAnonymousCheckout_POST

Self-contained method YAML

Assign checkout handbill coupons for anonymous profile, based on items in basket and historical transactions.

IMPORTANT: When assigning handbill promotions, candidate promotions are bounded by configurable limits: at most 40,000 candidates are read per handbill slot (ordered by priority), and the total number of candidates sent to the recommendation (AI) engine in a single request is capped at 45,000. If the combined candidates across all slots exceed the AI request cap, each slot is reduced proportionally to the number of candidates it contributed, but never below a configurable per-slot floor (default 1,000), so the smallest slots are left intact.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_SALE_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Request body

application/json · promotions-processCheckoutReq

FieldTypeRequiredDescription
operationIdintegerrequiredOperation ID
clientDateTimestringrequiredOperation's start time
terminalobjectrequiredData about the terminal that is the transaction's source
transactionMetricobjectrequiredMetadata of the transaction
finalValuestringrequiredThe total cost of all items in the basket, after discounts, including tax
transactionItemsarray<promotions-transactionItemWithoutGrants>requiredArray of transaction items
transactionAdditionalItemsarray<promotions-transactionAdditionalItem>requiredArray of additional items in the transaction
paymentsReportobjectrequiredPayment information

Responses

StatusDescription
200 application/jsonPOS checkout processed
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/sale/process-anonymous-checkout \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"operationId":0,"clientDateTime":"2019-08-24T14:15:22Z","terminal":{"storeId":"string","posId":0},"transactionMetric":{"posTransactionId":0,"beginDateTime":null,"globalTransactionId":"string"},"finalValue":"string","transactionItems":[{"seqNo":0,"articleRef":"string","quantity":"3.231","evidPrice":"34.23","finalPrice":"30.23","finalValue":"123.23"}],"transactionAdditionalItems":[{"seqNo":0,"type":"COUPON","code":"string"}],"paymentsReport":{"paymentItems":[{"seqNo":0,"type":0,"name":"string","amount":"string","hashCode":"string"}]}}'

Vouchers

POST /v4/vouchers/item/assign — Assign a voucher from a pool to Profile

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/AssignAVoucherFromAPoolToAClient

Self-contained method YAML

Assign a voucher code from an existing pool to a Profile.

API consumers: Profile (Client), Anonymous Profile, Incognito Profile

User role permission required: assets_code_pool: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body (required)

application/json · vouchers-voucherActionRequestAsClientReq

FieldTypeRequiredDescription
poolUuidstringrequiredUUID of the voucher pool
clientUuidstringoptionalUUID of the Profile. This field is ignored.

Responses

StatusDescription
201 application/jsonCode assigned
416 application/jsonRange Not Satisfiable

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/vouchers/item/assign \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"poolUuid":"faec32b0-c343-4362-ba32-c6148c649da4","clientUuid":"17243772-008a-42e1-ba37-c3807cebde8f"}'

GET /v4/vouchers/item/get-assigned — Get assigned vouchers

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/GetAssignedVouchers

Self-contained method YAML

Retrieve all vouchers assigned to a Profile.

API consumers: Profile (Client), Anonymous Profile, Incognito Profile

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Responses

StatusDescription
200 application/jsonAn array of vouchers

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/vouchers/item/get-assigned \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

POST /v4/vouchers/item/get-or-assign — Get or assign and get voucher as Profile

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/GetOrAssignAndGetVoucherAsClient

Self-contained method YAML

Retrieve the code assigned to a Profile. If no code was assigned earlier, the method assigns one.

For each Profile, the same code is retrieved every time. This can be used, for example, to retrieve unique codes used to identify a Profile.

API consumers: Profile (Client), Anonymous Profile, Incognito Profile

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body (required)

application/json · vouchers-voucherActionRequestAsClientReq

FieldTypeRequiredDescription
poolUuidstringrequiredUUID of the voucher pool
clientUuidstringoptionalUUID of the Profile. This field is ignored.

Responses

StatusDescription
200 application/jsonDetails of the code
416 application/jsonRange Not Satisfiable

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/vouchers/item/get-or-assign \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"poolUuid":"faec32b0-c343-4362-ba32-c6148c649da4","clientUuid":"17243772-008a-42e1-ba37-c3807cebde8f"}'

POST /v4/vouchers/item — Create a voucher

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/CreateAVoucher

Self-contained method YAML

Create a single code and store it in a pool.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_CREATE

User role permission required: assets_code_pool: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body (required)

application/json · vouchers-voucherData

FieldTypeRequiredDescription
poolUuidstringrequiredUUID of the voucher pool
clientUuidstringoptionalUUID of the Profile
clientIdintegeroptionalID of the Profile
codestringoptionalVoucher code Must match the pattern: ^.{0,36}$
expireInstringoptionalDate when the voucher expires.
redeemAtstringoptionalTime when the voucher was redeemed. Defaults to current time when redeeming.
assignedAtstringoptionalTime when the voucher was assigned. Defaults to current time when assigning.
statusenum<"ASSIGNED", "UNASSIGNED", "REDEEMED", "CANCELED">optionalVoucher status
createdAtstringoptionalTime when the voucher was created.
updatedAtstringoptionalTime when the voucher was last updated.

Responses

StatusDescription
201 application/jsonVoucher created

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/vouchers/item \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"poolUuid":"faec32b0-c343-4362-ba32-c6148c649da4","clientUuid":"07243772-008a-42e1-ba37-c3807cebde8f","clientId":0,"code":"code123","expireIn":"2019-08-24T14:15:22Z","redeemAt":"2019-08-24T14:15:22Z","assignedAt":"2019-08-24T14:15:22Z","status":"ASSIGNED","createdAt":"2019-08-24T14:15:22Z","updatedAt":"2019-08-24T14:15:22Z"}'

POST /v4/vouchers/item/bulk-create — Bulk create vouchers

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/BulkCreateVouchers

Self-contained method YAML

Create a number of codes and add them to a pool.

WARNING: The request body cannot contain more than 10 000 items or exceed 10 MB in size.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_BULK_CREATE

User role permission required: assets_code_pool: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body

application/json · vouchers-bulkCreateVouchersReq

FieldTypeRequiredDescription
poolUuidstringrequiredUUID of the voucher pool
codeListstringrequiredA list of unique voucher codes, separated by semicolons

Responses

StatusDescription
201 application/jsonVouchers created
400 application/jsonBad Request

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/vouchers/item/bulk-create \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"poolUuid":"faec32b0-c343-4362-ba32-c6148c649da4","codeList":"3845734682364756454534;384574634564545456;567868678345234346748"}'

GET /v4/vouchers/item/list — List all vouchers

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/ListVouchers

Self-contained method YAML

Retrieve all vouchers for a Workspace. You can customize the search.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_LIST_READ

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page

Responses

StatusDescription
200 application/jsonAn array of vouchers

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/vouchers/item/list?limit=100&page=4&includeMeta=false' \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

GET /v4/vouchers/item/{voucherUuid} — View voucher details

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/ViewVoucherDetails

Self-contained method YAML

Retrieve all details of a single code.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_READ

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
voucherUuidpathstringrequiredUUID of the voucher
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Responses

StatusDescription
200 application/jsonDetails of a voucher

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/vouchers/item/29392878-d43f-402e-8297-f63d465cf173 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

PUT /v4/vouchers/item/{voucherUuid} — Update a voucher

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/UpdateAVoucher

Self-contained method YAML

Update an existing code.

If you don't want to change a field, omit it entirely. Sending a null-value field replaces an existing value.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_UPDATE

User role permission required: assets_code_pool: update

Parameters

NameInTypeRequiredDescription
voucherUuidpathstringrequiredUUID of the voucher
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body (required)

application/json · vouchers-voucherData

FieldTypeRequiredDescription
poolUuidstringrequiredUUID of the voucher pool
clientUuidstringoptionalUUID of the Profile
clientIdintegeroptionalID of the Profile
codestringoptionalVoucher code Must match the pattern: ^.{0,36}$
expireInstringoptionalDate when the voucher expires.
redeemAtstringoptionalTime when the voucher was redeemed. Defaults to current time when redeeming.
assignedAtstringoptionalTime when the voucher was assigned. Defaults to current time when assigning.
statusenum<"ASSIGNED", "UNASSIGNED", "REDEEMED", "CANCELED">optionalVoucher status
createdAtstringoptionalTime when the voucher was created.
updatedAtstringoptionalTime when the voucher was last updated.

Responses

StatusDescription
200 application/json
400 application/jsonBad Request

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/v4/vouchers/item/29392878-d43f-402e-8297-f63d465cf173 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"poolUuid":"faec32b0-c343-4362-ba32-c6148c649da4","clientUuid":"07243772-008a-42e1-ba37-c3807cebde8f","clientId":0,"code":"code123","expireIn":"2019-08-24T14:15:22Z","redeemAt":"2019-08-24T14:15:22Z","assignedAt":"2019-08-24T14:15:22Z","status":"ASSIGNED","createdAt":"2019-08-24T14:15:22Z","updatedAt":"2019-08-24T14:15:22Z"}'

DELETE /v4/vouchers/item/{voucherUuid} — Delete a voucher

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/DeleteAVoucher

Self-contained method YAML

Delete an existing code.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_DELETE

User role permission required: assets_code_pool: delete

Parameters

NameInTypeRequiredDescription
voucherUuidpathstringrequiredUUID of the voucher
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Responses

StatusDescription
200 application/jsonVoucher deleted

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/v4/vouchers/item/29392878-d43f-402e-8297-f63d465cf173 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

GET /v4/vouchers/item/{searchKey}/{searchValue} — View voucher details by search key

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/ViewVoucherDetailsBySearchKey

Self-contained method YAML

Retrieve all details of a single voucher. As the key (identifier), you can use the promotion's code or UUID.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_BY_SEARCH_KEY_READ

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
searchKeypathenum<"code", "uuid">requiredThe key type to search by
searchValuepathstringrequiredThe value to search for
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Responses

StatusDescription
200 application/jsonDetails of a voucher

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/vouchers/item/code/29392878-d43f-402e-8297-f63d465cf173 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

POST /v4/vouchers/item/assign-for-client — Assign a voucher to a Profile

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/AssignAVoucherToAClient

Self-contained method YAML

Assign a code to a Profile and retrieve it. Every time this method is used, a different code is assigned.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_ASSIGN_FOR_CLIENT_CREATE

User role permission required: assets_code_pool: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body (required)

application/json · vouchers-voucherActionRequestAsProfileReq

FieldTypeRequiredDescription
poolUuidstringrequiredUUID of the voucher pool
clientUuidstringrequiredUUID of the Profile

Responses

StatusDescription
201 application/jsonVoucher assigned
416 application/jsonPool empty, expired, not found, or Profile not found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/vouchers/item/assign-for-client \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"poolUuid":"faec32b0-c343-4362-ba32-c6148c649da4","clientUuid":"07243772-008a-42e1-ba37-c3807cebde8f"}'

GET /v4/vouchers/item/get-assigned-for-client/{clientUuid} — Get vouchers assigned to a Profile (deprecated)

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/GetVouchersAssignedToAClient

Self-contained method YAML

Get all codes assigned to a Profile.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_ASSIGN_FOR_CLIENT_READ

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
clientUuidpathstringrequiredUUID of the Profile
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Responses

StatusDescription
200 application/jsonAn array of vouchers

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/vouchers/item/get-assigned-for-client/e9e6840b-b9d4-4c7b-8191-9c4f9e751c76 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

POST /v4/vouchers/item/get-or-assign-for-client — Get or assign and get voucher as Workspace (deprecated)

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/GetOrAssignAndGetVoucherAsBusinessProfile

Self-contained method YAML

Retrieve the code assigned to a profile. If no code was assigned earlier, the method assigns one.

For each profile, the same code is retrieved every time. This can be used, for example, to retrieve unique codes used to identify a profile.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_ASSIGN_FOR_CLIENT_CREATE

User role permission required: assets_code_pool: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body (required)

application/json · vouchers-voucherActionRequestAsProfileReq

FieldTypeRequiredDescription
poolUuidstringrequiredUUID of the voucher pool
clientUuidstringrequiredUUID of the Profile

Responses

StatusDescription
200 application/jsonDetails of a voucher
416 application/jsonPool empty, expired, not found, or Profile not found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/vouchers/item/get-or-assign-for-client \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"poolUuid":"faec32b0-c343-4362-ba32-c6148c649da4","clientUuid":"07243772-008a-42e1-ba37-c3807cebde8f"}'

GET /v4/vouchers/item/get-assigned-for-client/by-identifier — Get vouchers assigned to a Profile by identifier

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/GetVouchersAssignedToAClientByIdentifier

Self-contained method YAML

Get all codes assigned to a Profile.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_ASSIGN_FOR_CLIENT_READ

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required
clientIdentifierNamequeryenum<"id", "uuid", "email", "custom_identify">requiredThe Profile identifier to use for the request.
clientIdentifierValuequerystringrequiredThe value of the selected profile identifier

Responses

StatusDescription
200 application/jsonAn array of vouchers
400 application/jsonBad Request
416 application/jsonInvalid parameter

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/vouchers/item/get-assigned-for-client/by-identifier?clientIdentifierName=custom_identify&clientIdentifierValue=custom_identify_123456' \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

POST /v4/vouchers/item/get-or-assign-for-client/by-identifier — Get or assign and get voucher as Workspace

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/GetOrAssignAndGetVoucherByIdentifierAsBusinessProfile

Self-contained method YAML

Retrieve the code assigned to a profile. If no code was assigned earlier, the method assigns one (it uses the provided profile identifier).

For each profile, the same code is retrieved every time. This can be used, for example, to retrieve unique codes used to identify a profile.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_ASSIGN_FOR_CLIENT_CREATE

User role permission required: assets_code_pool: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required
clientIdentifierNamequeryenum<"id", "uuid", "email", "custom_identify">requiredThe Profile identifier to use for the request.

Request body (required)

application/json · vouchers-voucherActionRequestByClientIdentifierAsProfileReq

FieldTypeRequiredDescription
poolUuidstringrequiredUUID of the voucher pool
clientIdentifierValuerequiredValue of the profile identifier. For example clientIdentifierValue=custom_identify_1234

Responses

StatusDescription
200 application/jsonDetails of a voucher
416 application/jsonPool empty, expired, not found, or Profile not found

Example request (cURL)

curl --request POST \
  --url 'https://api.synerise.com/v4/vouchers/item/get-or-assign-for-client/by-identifier?clientIdentifierName=custom_identify' \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"poolUuid":"faec32b0-c343-4362-ba32-c6148c649da4","clientIdentifierValue":"custom_identify_1234"}'

POST /v4/vouchers/item/assign-for-client/by-identifier — Assign and get voucher as Workspace

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/AssignAndGetVoucherByIdentifierAsBusinessProfile

Self-contained method YAML

Assign a code to a profile and retrieve it. Every time this method is used, a different code is assigned.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_ASSIGN_FOR_CLIENT_CREATE

User role permission required: assets_code_pool: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required
clientIdentifierNamequeryenum<"id", "uuid", "email", "custom_identify">requiredThe Profile identifier to use for the request.

Request body (required)

application/json · vouchers-voucherActionRequestByClientIdentifierAsProfileReq

FieldTypeRequiredDescription
poolUuidstringrequiredUUID of the voucher pool
clientIdentifierValuerequiredValue of the profile identifier. For example clientIdentifierValue=custom_identify_1234

Responses

StatusDescription
201 application/jsonVoucher assigned
416 application/jsonPool empty, expired, not found, or Profile not found

Example request (cURL)

curl --request POST \
  --url 'https://api.synerise.com/v4/vouchers/item/assign-for-client/by-identifier?clientIdentifierName=custom_identify' \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"poolUuid":"faec32b0-c343-4362-ba32-c6148c649da4","clientIdentifierValue":"custom_identify_1234"}'

POST /v4/vouchers/item/redeem — Redeem a voucher

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/RedeemAVoucher

Self-contained method YAML

Redeem a code.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_REDEEM_CREATE

User role permission required: assets_code_pool: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body (required)

application/json · vouchers-voucherRedeemReq

FieldTypeRequiredDescription
codestringrequiredVoucher code Must match the pattern: ^.{0,36}$

Responses

StatusDescription
200 application/jsonVoucher redeemed
400 application/jsonData format is not valid.

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/vouchers/item/redeem \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"code":"code123"}'

GET /v4/vouchers/pool/list — List pools

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/ListPools

Self-contained method YAML

Retrieve a list of voucher pools.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_POOL_LIST_READ

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
orderFieldNamequeryenum<"name", "startAt", "expireIn", "createdAt">optionalName of the parameter used for sorting. If you include this parameter, you must also send the order parameter.
orderqueryenum<"asc", "desc">optionalSorting order. If you include this parameter, you must also send the orderFieldName parameter.
queryquerystringoptionalFilter by phrase in pool name.
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.

Responses

StatusDescription
200 application/jsonAn array of voucher pools

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/vouchers/pool/list?includeMeta=false&orderFieldName=SOME_STRING_VALUE&order=SOME_STRING_VALUE&query=SOME_STRING_VALUE&limit=100&page=4' \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

POST /v4/vouchers/pool — Create a voucher pool

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/CreateAVoucherPool

Self-contained method YAML

Create a pool for voucher storage.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_POOL_CREATE

User role permission required: assets_code_pool: create

Parameters

NameInTypeRequiredDescription
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body (required)

application/json · vouchers-createAVoucherPoolReq

FieldTypeRequiredDescription
namestringrequiredName of the voucher pool
descriptionstringoptionalA description of the pool
startAtstringoptionalTime when the pool starts functioning. Defaults to current time.
expireInstringrequiredTime when the pool stops functioning. Must be later than startAt.

Responses

StatusDescription
201 application/jsonPool created

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/vouchers/pool \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"name":"string","description":"string","startAt":"2019-08-24T14:15:22Z","expireIn":"2019-08-24T14:15:22Z"}'

GET /v4/vouchers/pool/{poolUuid} — Get pool details

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/GetPoolDetails

Self-contained method YAML

Retrieve the details of a single voucher pool.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_POOL_READ

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
poolUuidpathstringrequiredUUID of the voucher pool
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Responses

StatusDescription
200 application/jsonDetails of a voucher pool

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/vouchers/pool/8465c240-d38e-42f8-af29-b9fa1ed05115 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

PUT /v4/vouchers/pool/{poolUuid} — Update a voucher pool

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/UpdateAVoucherPool

Self-contained method YAML

Update an existing pool of vouchers. If you don't want to change a parameter, omit it entirely.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_POOL_UPDATE

User role permission required: assets_code_pool: update

Parameters

NameInTypeRequiredDescription
poolUuidpathstringrequiredUUID of the voucher pool
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Request body (required)

application/json · vouchers-updateAVoucherPoolReq

FieldTypeRequiredDescription
namestringoptionalName of the voucher pool
descriptionstringoptionalA description of the pool
startAtstringoptionalTime when the pool starts functioning. Defaults to current time.
expireInstringoptionalTime when the pool stops functioning. Must be later than startAt.

Responses

StatusDescription
200 application/jsonVoucher pool

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/v4/vouchers/pool/8465c240-d38e-42f8-af29-b9fa1ed05115 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE' \
  --header 'content-type: application/json' \
  --data '{"name":"string","description":"string","startAt":"2019-08-24T14:15:22Z","expireIn":"2019-08-24T14:15:22Z"}'

DELETE /v4/vouchers/pool/{poolUuid} — Delete a voucher pool

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/DeleteAVoucherPool

Self-contained method YAML

Delete an existing pool of vouchers.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_POOL_DELETE

User role permission required: assets_code_pool: delete

Parameters

NameInTypeRequiredDescription
poolUuidpathstringrequiredUUID of the voucher pool
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Responses

StatusDescription
200 application/jsonVoucher pool deleted

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/v4/vouchers/pool/8465c240-d38e-42f8-af29-b9fa1ed05115 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

GET /v4/vouchers/item/list/{poolUuid} — List vouchers from a pool

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/ListVouchersFromPool

Self-contained method YAML

Retrieve vouchers from a single pool.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_LIST_BY_POOL_READ

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
poolUuidpathstringrequiredUUID of the voucher pool
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page

Responses

StatusDescription
200 application/jsonAn array of vouchers in the pool

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/vouchers/item/list/8465c240-d38e-42f8-af29-b9fa1ed05115?limit=100&page=4&includeMeta=false' \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

DELETE /v4/vouchers/item/list/{poolUuid} — Delete vouchers by poolUuid

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/DeleteVouchersByPoolUuid

Self-contained method YAML

Delete vouchers assigned to pool.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_BY_POOL_DELETE

User role permission required: assets_code_pool: delete

Parameters

NameInTypeRequiredDescription
poolUuidpathstringrequiredUUID of the voucher pool
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Responses

StatusDescription
200 application/jsonVouchers deleted

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/v4/vouchers/item/list/8465c240-d38e-42f8-af29-b9fa1ed05115 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

POST /v4/vouchers/item/count/{poolUuid} — Count vouchers

/api-reference/loyalty-and-engagement#tag/Vouchers/operation/getVouchersCount

Self-contained method YAML

Count (re-calculate) vouchers in a pool, group the results by status.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: VOUCHERS_ITEM_LIST_BY_POOL_READ

User role permission required: assets_code_pool: read

Parameters

NameInTypeRequiredDescription
poolUuidpathstringrequiredUUID of the voucher pool
Acceptheaderenum<"application/json">required
Content-Typeheaderenum<"application/json">required
Api-Versionheaderenum<"4.4", "4.2">required

Responses

StatusDescription
200 application/jsonSet of counters

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/vouchers/item/count/8465c240-d38e-42f8-af29-b9fa1ed05115 \
  --header 'Accept: SOME_STRING_VALUE' \
  --header 'Api-Version: SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Content-Type: SOME_STRING_VALUE'

Handbills

GET /v4/promotions/handbill — Get all handbill configurations

/api-reference/loyalty-and-engagement#tag/Handbills/operation/getAllHandbillConfigs_GET

Self-contained method YAML

Retrieve a list of all handbill configurations available in the current Workspace.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_HANDBILL_READ

User role permission required: campaigns_personalised_promotions: read

Parameters

NameInTypeRequiredDescription
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
sortquerystringoptionalThe sorting order of the response. You can sort by any combination of the following attributes: createdAt: time when the configuration was created updatedAt: time when the configuration was last updated You can sort ascending (default) or descending by adding asc or desc after the parameter, separated by a comma."
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page

Responses

StatusDescription
200 application/jsonList of handbill configurations
401 application/jsonUnauthorized
403 application/jsonForbidden
500General error

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/handbill?limit=100&page=4&sort=createdAt%2Cdesc&includeMeta=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /v4/promotions/handbill — Create handbill configuration

/api-reference/loyalty-and-engagement#tag/Handbills/operation/createHandbillConfiguration_POST

Self-contained method YAML

Create a new handbill configuration for use in handbill-type promotions.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_HANDBILL_CREATE

User role permission required: campaigns_personalised_promotions: create

Request body

application/json · promotions-handbillConfigCreateRequest

FieldTypeRequiredDescription
channelenum<"MOBILE", "CHECK_OUT", "CHECK_IN">requiredChannel of the handbill. CHECK_IN means that the promotions are offered before a purchase. CHECK_OUT means that promotions are offered after a purchase, and can be used in a future transaction. MOBILE is used to deliver promotions to a mobile application.
statusenum<"DRAFT", "ACTIVE", "INACTIVE">requiredStatus of the handbill
namestringrequiredName of the handbill configuration
descriptionstringrequiredDescription of the handbill configuration
controlGroupobjectrequiredDetails of the control group. A control group is the part of profiles who are not offered any promotions so their activity can be compared with promotion-enabled profiles to check a promotion's effectiveness.
variantsarray<object>requiredVariants of the handbill configuration. If you do not want to use variants, send an empty array.

Responses

StatusDescription
201 application/jsonConfiguration created
400 application/jsonJSON is null
401 application/jsonUnauthorized
403 application/jsonForbidden
422 application/jsonRequest payload failed schema validation, for example: missing required value, wrong data type

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/handbill \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"channel":"MOBILE","status":"DRAFT","name":"string","description":"string","controlGroup":{"name":"string","percentage":100},"variants":[{"name":"string","uuid":"095be615-a8ad-4c33-8e9c-c7612fbf6c9f","percentage":100,"ai":{"controlVariant":true,"varietyFactor":0.5,"varietyGroupSize":1,"redistributionFrequencyFactor":0.5,"popularityBoosting":1},"limits":{"limitPerDay":6,"limitExceptions":[{"dayOfWeek":5,"limitPerDay":8}],"limitsPerBasket":[{"basketSize":12,"basketValue":30.5,"condition":"AND"}],"limitExclusion":[{"catalogId":22424,"products":["UGG-BB-PUR-06"],"filters":["7c1fbdf6-dd27-11ea-87d0-0242ac130003"]}]},"activity":{"lastingType":"RELATIVE","lasting":{"unit":"HOURS","value":24},"cronWeekdays":[0,1,6],"cronTime":"12:34","lastingAt":"2019-08-24T14:15:22Z","timeExclusions":{"uuid":"6a177f3e-748f-44d4-ac30-a457a5199685"},"interval":{"every":2,"unit":"WEEKS","anchorDate":"2026-07-05T23:59:00Z"}},"printout":{"template":"|#{promotion.name};#{promotion.discountType == '\''EXACT_PRICE'\'' ? '\''Price'\'':'\''Discount'\''} #{promotion.discountValue} #{promotion.discountType == '\''PERCENT'\''? '\''%'\'' : '\''USD'\''};Valid for;#{moment.utc(coupon.createdAt).tz('\''Europe/Warsaw'\'').format('\''DD.MM.YYYY HH:mm'\'')} - #{moment.utc(coupon.lastingAt).tz('\''Europe/Warsaw'\'').format('\''DD.MM.YYYY HH:mm'\'')};#{promotion.description};Discount for #{coupon.redeemLimit} items.;Single-use coupon. Get extra coupons with the app!","maxLineLength":18,"newLineDelimiter":";"},"types":["MEMBERS_ONLY","HANDBILL"],"excludeByAvailableProducts":true,"slotFilters":{"order":"GIVEN","slots":[{"filterId":"aff0ee0f-f371-4b82-82c6-dc3b96f05c91","limit":5,"distinctFilter":{"filters":[{"field":"brand","maxNumItems":2,"levelRangeModifier":1}],"elastic":true},"fallback":{"filterId":"3f2c9a4e-8b1d-4e5f-9c6a-7d8e9f0a1b2c"}}]},"distinctFilter":{"filters":[{"field":"brand","maxNumItems":2,"levelRangeModifier":1}],"elastic":true}}]}'

GET /v4/promotions/handbill/{handbillUuid} — Get handbill configuration

/api-reference/loyalty-and-engagement#tag/Handbills/operation/getHandbillConfig_GET

Self-contained method YAML

Retrieve the details of a single handbill configuration.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_HANDBILL_READ

User role permission required: campaigns_personalised_promotions: read

Parameters

NameInTypeRequiredDescription
handbillUuidpathstringrequiredUUID of the handbill configuration

Responses

StatusDescription
200 application/jsonHandbill configuration
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/promotions/handbill/%7BhandbillUuid%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

PATCH /v4/promotions/handbill/{handbillUuid} — Update handbill configuration

/api-reference/loyalty-and-engagement#tag/Handbills/operation/updateHandbill_PATCH

Self-contained method YAML

Update an existing handbill configuration.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_HANDBILL_UPDATE

User role permission required: campaigns_personalised_promotions: update

Parameters

NameInTypeRequiredDescription
handbillUuidpathstringrequiredUUID of the handbill configuration

Request body

application/json · promotions-handbillConfigUpdateRequest

FieldTypeRequiredDescription
channelenum<"MOBILE", "CHECK_OUT", "CHECK_IN">optionalChannel of the handbill. CHECK_IN means that the promotions are offered before a purchase. CHECK_OUT means that promotions are offered after a purchase, and can be used in a future transaction. MOBILE is used to deliver promotions to a mobile application.
statusenum<"DRAFT", "ACTIVE", "INACTIVE">optionalStatus of the handbill
namestringoptionalName of the handbill configuration
descriptionstringoptionalDescription of the handbill configuration
controlGroupobjectoptionalDetails of the control group. A control group is the part of profiles who are not offered any promotions so their activity can be compared with promotion-enabled profiles to check a promotion's effectiveness.
variantsarray<object>optionalVariants of the handbill configuration. If you do not want to use variants, send an empty array.

Responses

StatusDescription
200 application/jsonConfiguration updated
400 application/jsonJSON is null
401 application/jsonUnauthorized
403 application/jsonForbidden
422 application/jsonRequest payload failed schema validation, for example: missing required value, wrong data type

Example request (cURL)

curl --request PATCH \
  --url https://api.synerise.com/v4/promotions/handbill/%7BhandbillUuid%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"channel":"MOBILE","status":"DRAFT","name":"string","description":"string","controlGroup":{"name":"string","percentage":100},"variants":[{"name":"string","uuid":"095be615-a8ad-4c33-8e9c-c7612fbf6c9f","percentage":100,"ai":{"controlVariant":true,"varietyFactor":0.5,"varietyGroupSize":1,"redistributionFrequencyFactor":0.5,"popularityBoosting":1},"limits":{"limitPerDay":6,"limitExceptions":[{"dayOfWeek":5,"limitPerDay":8}],"limitsPerBasket":[{"basketSize":12,"basketValue":30.5,"condition":"AND"}],"limitExclusion":[{"catalogId":22424,"products":["UGG-BB-PUR-06"],"filters":["7c1fbdf6-dd27-11ea-87d0-0242ac130003"]}]},"activity":{"lastingType":"RELATIVE","lasting":{"unit":"HOURS","value":24},"cronWeekdays":[0,1,6],"cronTime":"12:34","lastingAt":"2019-08-24T14:15:22Z","timeExclusions":{"uuid":"6a177f3e-748f-44d4-ac30-a457a5199685"},"interval":{"every":2,"unit":"WEEKS","anchorDate":"2026-07-05T23:59:00Z"}},"printout":{"template":"|#{promotion.name};#{promotion.discountType == '\''EXACT_PRICE'\'' ? '\''Price'\'':'\''Discount'\''} #{promotion.discountValue} #{promotion.discountType == '\''PERCENT'\''? '\''%'\'' : '\''USD'\''};Valid for;#{moment.utc(coupon.createdAt).tz('\''Europe/Warsaw'\'').format('\''DD.MM.YYYY HH:mm'\'')} - #{moment.utc(coupon.lastingAt).tz('\''Europe/Warsaw'\'').format('\''DD.MM.YYYY HH:mm'\'')};#{promotion.description};Discount for #{coupon.redeemLimit} items.;Single-use coupon. Get extra coupons with the app!","maxLineLength":18,"newLineDelimiter":";"},"types":["MEMBERS_ONLY","HANDBILL"],"excludeByAvailableProducts":true,"slotFilters":{"order":"GIVEN","slots":[{"filterId":"aff0ee0f-f371-4b82-82c6-dc3b96f05c91","limit":5,"distinctFilter":{"filters":[{"field":"brand","maxNumItems":2,"levelRangeModifier":1}],"elastic":true},"fallback":{"filterId":"3f2c9a4e-8b1d-4e5f-9c6a-7d8e9f0a1b2c"}}]},"distinctFilter":{"filters":[{"field":"brand","maxNumItems":2,"levelRangeModifier":1}],"elastic":true}}]}'

GET /v4/promotions/promotion/get-for-client/handbill/{handbillUuid} — Generate handbill for Profile

/api-reference/loyalty-and-engagement#tag/Handbills/operation/getHandbillForClient_GET

Self-contained method YAML

Assign handbill promotions to a Profile. They can be randomized or suggested by the AI engine.

IMPORTANT:

  • The endpoint is limited to 1000 requests per minute (per workspace).
  • The algorithm that selects promotions for assignment candidates applies all the following filters:
    • Promotions must be of the specified type, assigned to a handbill campaign, and with the PUBLISH status.
    • Promotions must be available for the entire duration of the handbill assignment, considering startAt and expireAt dates. For example, when generating assignments on May 1, 2024 at 9:00 a.m. that are expected to last 3 hours, the algorithm will consider promotions whose startAt date is equal to or earlier than May 1, 2024 9:00 a.m. and expireAt date is equal to or later than May 1, 2024 12:00 p.m.
    • Promotions can't currently be assigned within another handbill campaign.
    • Promotions must match the filter for the slot (if applicable). Promotions are handled by the binoculars service and identified by UUID.
    • Promotions are deduplicated. First they are sorted by priority, then the algorithm rejects promotions with at least one product that occurred earlier. In a special case, if a promotion with a high priority has an extensive catalog of products covering other promotions, it could exclude all promotions with a lower priority.
    • If excludeByAvailableProducts is set to true, the algorithm rejects promotions for items that are available as part of other promotions (regardless of their type)
    • After sorting promotions by priority, the algorithm rejects promotions for segments that occur after the 100th unique segment is encountered. (only 100 segments can be checked per handbill assignment, consider limiting the number of segments and reusing them).
    • After checking the first 100 unique segments, the algorithm rejects promotions for segments that don't match the user.
    • To ensure the correctness of promotion usage and redemption, the algorithm rejects promotions that are currently in the ACTIVE or REDEEMED status.
    • Candidate promotions are gathered per handbill slot. For each slot, at most a configurable number of promotions (default 40,000) is read from the database, ordered by priority ascending (1 = highest); any promotions beyond that limit are not considered for that slot. Promotions sharing the same priority have no guaranteed order between them, so when the limit falls within a group of equal priority it is not defined which of them are kept — assign distinct priorities to control this.
    • When using the AI engine, the total number of candidate promotions sent to the recommendation engine in a single request is capped by a configurable limit (default 45,000). If the combined candidates across all slots exceed this limit, each slot is reduced proportionally to the number of candidates it contributed, but never below a configurable per-slot floor (default 1,000), so the smallest slots are left intact.

API consumers: Profile (Client), Anonymous Profile

Parameters

NameInTypeRequiredDescription
handbillUuidpathstringrequiredUUID of the handbill configuration
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
fieldsqueryarray<enum<"uuid", "code", "status", "type", …>>optionalReturn only specified promotion fields. If fields is not specified, all fields are returned.

Responses

StatusDescription
200 application/jsonA list of handbill-type promotions assigned to this profile
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
409 application/jsonWaiting for profile lock release

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/get-for-client/handbill/%7BhandbillUuid%7D?limit=100&page=4&fields=uuid%2CrequireRedeemedPoints%2CrequireRedeemedPoints%2CpossibleRedeems%2Cstatus%2CcurrentRedeemedQuantity%2ClastingAt' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/get-for-client/handbills — Generate batch of handbills for Profile

/api-reference/loyalty-and-engagement#tag/Handbills/operation/getBatchHandbillForClient_GET

Self-contained method YAML

Assign a batch of handbill promotions to a Profile. They can be randomized or suggested by the AI engine.

IMPORTANT:

  • The endpoint is limited to 1000 requests per minute (per workspace).
  • The algorithm that selects promotions for assignment candidates applies all the following filters:
    • Promotions must be of the specified type, assigned to a handbill campaign, and with the PUBLISH status.
    • Promotions must be available for the entire duration of the handbill assignment, considering startAt and expireAt dates. For example, when generating assignments on May 1, 2024 at 9:00 a.m. that are expected to last 3 hours, the algorithm will consider promotions whose startAt date is equal to or earlier than May 1, 2024 9:00 a.m. and expireAt date is equal to or later than May 1, 2024 12:00 p.m.
    • Promotions can't currently be assigned within another handbill campaign.
    • Promotions must match the filter for the slot (if applicable). Promotions are handled by the binoculars service and identified by UUID.
    • Promotions are deduplicated. First they are sorted by priority, then the algorithm rejects promotions with at least one product that occurred earlier. In a special case, if a promotion with a high priority has an extensive catalog of products covering other promotions, it could exclude all promotions with a lower priority.
    • If excludeByAvailableProducts is set to true, the algorithm rejects promotions for items that are available as part of other promotions (regardless of their type)
    • After sorting promotions by priority, the algorithm rejects promotions for segments that occur after the 100th unique segment is encountered. (only 100 segments can be checked per handbill assignment, consider limiting the number of segments and reusing them).
    • After checking the first 100 unique segments, the algorithm rejects promotions for segments that don't match the user.
    • To ensure the correctness of promotion usage and redemption, the algorithm rejects promotions that are currently in the ACTIVE or REDEEMED status.
    • Candidate promotions are gathered per handbill slot. For each slot, at most a configurable number of promotions (default 40,000) is read from the database, ordered by priority ascending (1 = highest); any promotions beyond that limit are not considered for that slot. Promotions sharing the same priority have no guaranteed order between them, so when the limit falls within a group of equal priority it is not defined which of them are kept — assign distinct priorities to control this.
    • When using the AI engine, the total number of candidate promotions sent to the recommendation engine in a single request is capped by a configurable limit (default 45,000). If the combined candidates across all slots exceed this limit, each slot is reduced proportionally to the number of candidates it contributed, but never below a configurable per-slot floor (default 1,000), so the smallest slots are left intact.

API consumers: Profile (Client), Anonymous Profile

Parameters

NameInTypeRequiredDescription
handbillUuidqueryarray<string>required
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
fieldsqueryarray<enum<"uuid", "code", "status", "type", …>>optionalReturn only specified promotion fields. If fields is not specified, all fields are returned.

Responses

StatusDescription
200 application/jsonA list of handbill-type promotions assigned to this profile
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
409 application/jsonWaiting for profile lock release

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/get-for-client/handbills?handbillUuid=SOME_ARRAY_VALUE&page=4&limit=100&includeMeta=false&fields=uuid%2CrequireRedeemedPoints%2CrequireRedeemedPoints%2CpossibleRedeems%2Cstatus%2CcurrentRedeemedQuantity%2ClastingAt' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/get-for-client/{identifierType}/{identifierValue}/handbill/{handbillUuid} — Generate handbill for Profile and get Profile promotions (deprecated)

/api-reference/loyalty-and-engagement#tag/Handbills/operation/getAssignHandbillForClient_GET

Self-contained method YAML

Deprecated. Use /v2/promotion/get-for-client/{identifierType}/{identifierValue}/handbill/{handbillUuid} instead.

Assign a handbill to a Profile and retrieve a list of promotions assigned to the Profile.

IMPORTANT:

  • The endpoint is limited to 1000 requests per minute (per workspace).
  • The algorithm that selects promotions for assignment candidates applies all the following filters:
    • Promotions must be of the specified type, assigned to a handbill campaign, and with the PUBLISH status.
    • Promotions must be available for the entire duration of the handbill assignment, considering startAt and expireAt dates. For example, when generating assignments on May 1, 2024 at 9:00 a.m. that are expected to last 3 hours, the algorithm will consider promotions whose startAt date is equal to or earlier than May 1, 2024 9:00 a.m. and expireAt date is equal to or later than May 1, 2024 12:00 p.m.
    • Promotions can't currently be assigned within another handbill campaign.
    • Promotions must match the filter for the slot (if applicable). Promotions are handled by the binoculars service and identified by UUID.
    • Promotions are deduplicated. First they are sorted by priority, then the algorithm rejects promotions with at least one product that occurred earlier. In a special case, if a promotion with a high priority has an extensive catalog of products covering other promotions, it could exclude all promotions with a lower priority.
    • If excludeByAvailableProducts is set to true, the algorithm rejects promotions for items that are available as part of other promotions (regardless of their type)
    • After sorting promotions by priority, the algorithm rejects promotions for segments that occur after the 100th unique segment is encountered. (only 100 segments can be checked per handbill assignment, consider limiting the number of segments and reusing them).
    • After checking the first 100 unique segments, the algorithm rejects promotions for segments that don't match the user.
    • To ensure the correctness of promotion usage and redemption, the algorithm rejects promotions that are currently in the ACTIVE or REDEEMED status.
    • Candidate promotions are gathered per handbill slot. For each slot, at most a configurable number of promotions (default 40,000) is read from the database, ordered by priority ascending (1 = highest); any promotions beyond that limit are not considered for that slot. Promotions sharing the same priority have no guaranteed order between them, so when the limit falls within a group of equal priority it is not defined which of them are kept — assign distinct priorities to control this.
    • When using the AI engine, the total number of candidate promotions sent to the recommendation engine in a single request is capped by a configurable limit (default 45,000). If the combined candidates across all slots exceed this limit, each slot is reduced proportionally to the number of candidates it contributed, but never below a configurable per-slot floor (default 1,000), so the smallest slots are left intact.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_FOR_CLIENT_HANDBILL_READ

User role permission required: campaigns_personalised_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier
handbillUuidpathstringrequiredUUID of the handbill configuration
typequeryarray<enum<"GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL">>optionalPromotion type
statusqueryarray<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>optionalFilter by promotion status
visibilityStatusqueryarray<enum<"DRAFT", "PUBLISH", "HIDDEN">>optionalVisibility status
tagNamesqueryarray<string>optionalFilter the response to promotions with a certain tag or tags
targetqueryarray<enum<"ALL", "SEGMENT">>optionalThe target of the promotion
presentOnlyquerybooleanoptionalWhen set to: true, the response includes only promotions that are currently active (startAt later than now or null, expireAt later than now or null) false, the response includes the above and also promotions that are expired or will become active in the future.
lastingOnlyquerybooleanoptionalWhen set to true, shows promotions/vouchers that are currently active and those that are still inactivated. (lastingAt set to null or lastingAt in future)
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
sortquerystringoptionalThe sorting order of the response. You can sort by any combination of the following attributes: createdAt: time when the configuration was created updatedAt: time when the configuration was last updated You can sort ascending (default) or descending by adding asc or desc after the parameter, separated by a comma."
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
fieldsqueryarray<enum<"uuid", "code", "status", "type", …>>optionalReturn only specified promotion fields. If fields is not specified, all fields are returned.

Responses

StatusDescription
200 application/jsonA list of promotions assigned to this profile
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/get-for-client/email/%7BidentifierValue%7D/handbill/%7BhandbillUuid%7D?type=SOME_ARRAY_VALUE&status=SOME_ARRAY_VALUE&visibilityStatus=SOME_ARRAY_VALUE&tagNames=SOME_ARRAY_VALUE&target=SOME_ARRAY_VALUE&presentOnly=true&lastingOnly=true&page=4&limit=100&sort=createdAt%2Cdesc&includeMeta=false&fields=uuid%2CrequireRedeemedPoints%2CrequireRedeemedPoints%2CpossibleRedeems%2Cstatus%2CcurrentRedeemedQuantity%2ClastingAt' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/v2/promotion/get-for-client/{identifierType}/{identifierValue}/handbill/{handbillUuid} — Generate handbill for Profile (v2)

/api-reference/loyalty-and-engagement#tag/Handbills/operation/getHandbillForClientV2_GET

Self-contained method YAML

Assign handbill promotions to a Profile. They can be randomized or suggested by the AI engine.

IMPORTANT:

  • The endpoint is limited to 1000 requests per minute (per workspace).
  • The algorithm that selects promotions for assignment candidates applies all the following filters:
    • Promotions must be of the specified type, assigned to a handbill campaign, and with the PUBLISH status.
    • Promotions must be available for the entire duration of the handbill assignment, considering startAt and expireAt dates. For example, when generating assignments on May 1, 2024 at 9:00 a.m. that are expected to last 3 hours, the algorithm will consider promotions whose startAt date is equal to or earlier than May 1, 2024 9:00 a.m. and expireAt date is equal to or later than May 1, 2024 12:00 p.m.
    • Promotions can't currently be assigned within another handbill campaign.
    • Promotions must match the filter for the slot (if applicable). Promotions are handled by the binoculars service and identified by UUID.
    • Promotions are deduplicated. First they are sorted by priority, then the algorithm rejects promotions with at least one product that occurred earlier. In a special case, if a promotion with a high priority has an extensive catalog of products covering other promotions, it could exclude all promotions with a lower priority.
    • If excludeByAvailableProducts is set to true, the algorithm rejects promotions for items that are available as part of other promotions (regardless of their type)
    • After sorting promotions by priority, the algorithm rejects promotions for segments that occur after the 100th unique segment is encountered. (only 100 segments can be checked per handbill assignment, consider limiting the number of segments and reusing them).
    • After checking the first 100 unique segments, the algorithm rejects promotions for segments that don't match the user.
    • To ensure the correctness of promotion usage and redemption, the algorithm rejects promotions that are currently in the ACTIVE or REDEEMED status.
    • Candidate promotions are gathered per handbill slot. For each slot, at most a configurable number of promotions (default 40,000) is read from the database, ordered by priority ascending (1 = highest); any promotions beyond that limit are not considered for that slot. Promotions sharing the same priority have no guaranteed order between them, so when the limit falls within a group of equal priority it is not defined which of them are kept — assign distinct priorities to control this.
    • When using the AI engine, the total number of candidate promotions sent to the recommendation engine in a single request is capped by a configurable limit (default 45,000). If the combined candidates across all slots exceed this limit, each slot is reduced proportionally to the number of candidates it contributed, but never below a configurable per-slot floor (default 1,000), so the smallest slots are left intact.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_FOR_CLIENT_HANDBILL_READ

User role permission required: campaigns_personalised_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier
handbillUuidpathstringrequiredUUID of the handbill configuration
limitqueryintegeroptionalThe number of items to return per page
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.

Responses

StatusDescription
200 application/jsonA list of handbill-type promotions assigned to this profile
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
409 application/jsonWaiting for profile lock release

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/v2/promotion/get-for-client/email/%7BidentifierValue%7D/handbill/%7BhandbillUuid%7D?limit=100&page=4' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /v4/promotions/promotion/get-for-client/{identifierType}/{identifierValue}/with-handbills — Generate batch handbill for Profile and get Profile promotions

/api-reference/loyalty-and-engagement#tag/Handbills/operation/getAssignHandbillsForClient_GET

Self-contained method YAML

Assign a batch handbill to a Profile and retrieve a list of promotions assigned to the Profile.

IMPORTANT:

  • The endpoint is limited to 1000 requests per minute (per workspace).
  • The algorithm that selects promotions for assignment candidates applies all the following filters:
    • Promotions must be of the specified type, assigned to a handbill campaign, and with the PUBLISH status.
    • Promotions must be available for the entire duration of the handbill assignment, considering startAt and expireAt dates. For example, when generating assignments on May 1, 2024 at 9:00 a.m. that are expected to last 3 hours, the algorithm will consider promotions whose startAt date is equal to or earlier than May 1, 2024 9:00 a.m. and expireAt date is equal to or later than May 1, 2024 12:00 p.m.
    • Promotions can't currently be assigned within another handbill campaign.
    • Promotions must match the filter for the slot (if applicable). Promotions are handled by the binoculars service and identified by UUID.
    • Promotions are deduplicated. First they are sorted by priority, then the algorithm rejects promotions with at least one product that occurred earlier. In a special case, if a promotion with a high priority has an extensive catalog of products covering other promotions, it could exclude all promotions with a lower priority.
    • If excludeByAvailableProducts is set to true, the algorithm rejects promotions for items that are available as part of other promotions (regardless of their type)
    • After sorting promotions by priority, the algorithm rejects promotions for segments that occur after the 100th unique segment is encountered. (only 100 segments can be checked per handbill assignment, consider limiting the number of segments and reusing them).
    • After checking the first 100 unique segments, the algorithm rejects promotions for segments that don't match the user.
    • To ensure the correctness of promotion usage and redemption, the algorithm rejects promotions that are currently in the ACTIVE or REDEEMED status.
    • Candidate promotions are gathered per handbill slot. For each slot, at most a configurable number of promotions (default 40,000) is read from the database, ordered by priority ascending (1 = highest); any promotions beyond that limit are not considered for that slot. Promotions sharing the same priority have no guaranteed order between them, so when the limit falls within a group of equal priority it is not defined which of them are kept — assign distinct priorities to control this.
    • When using the AI engine, the total number of candidate promotions sent to the recommendation engine in a single request is capped by a configurable limit (default 45,000). If the combined candidates across all slots exceed this limit, each slot is reduced proportionally to the number of candidates it contributed, but never below a configurable per-slot floor (default 1,000), so the smallest slots are left intact.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_FOR_CLIENT_HANDBILL_READ

User role permission required: campaigns_personalised_promotions: read

Parameters

NameInTypeRequiredDescription
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier
handbillUuidqueryarray<string>required
typequeryarray<enum<"GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL">>optionalPromotion type
pagequeryintegeroptionalPage number to return for pagination. The first page has the index 1.
limitqueryintegeroptionalThe number of items to return per page
includeMetaquerybooleanoptionalWhen true, pagination metadata is included in the response body. When false, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page
statusqueryarray<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>optionalFilter by promotion status
fieldsqueryarray<enum<"uuid", "code", "status", "type", …>>optionalReturn only specified promotion fields. If fields is not specified, all fields are returned.

Responses

StatusDescription
200 application/jsonA list of promotions assigned to this profile
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/promotion/get-for-client/email/%7BidentifierValue%7D/with-handbills?handbillUuid=SOME_ARRAY_VALUE&type=SOME_ARRAY_VALUE&page=4&limit=100&includeMeta=false&status=SOME_ARRAY_VALUE&fields=uuid%2CrequireRedeemedPoints%2CrequireRedeemedPoints%2CpossibleRedeems%2Cstatus%2CcurrentRedeemedQuantity%2ClastingAt' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Wallet passes

GET /device-hub/wallets/issue — Issue wallet pass

/api-reference/loyalty-and-engagement#tag/Wallet-passes/operation/issueWalletPassUsingGET

Self-contained method YAML

IMPORTANT: This feature is in private preview mode and accessible only on selected workspaces. To get access, contact your account manager or Synerise Support.

Handle issuing a wallet pass.

  • If the platform (IOS, ANDROID) is not specified, the endpoint returns a landing page where the user can choose their OS.
  • If the platform is specified, the endpoint issues a wallet card.

To obtain the parameters required by this endpoint, generate a link with the /wallets/issue/link endpoint. You can also generate the link with Jinjava inserts in communication, for example in push messages or when rendering content from Brickworks.

Authentication: Not required

Parameters

NameInTypeRequiredDescription
clientUuidquerystringoptionalWhen present, also goes into the HMAC payload depending on the wallet pass record configuration. If an UUID was used to generate the link, make sure to use the same UUID when issuing the wallet pass.
issueIdquerystringrequiredPrimary key for the IssueLinkEntity lookup. Returned as part of the link by /wallets/issue/link or a Jinjava insert.
hmacquerystringrequiredBase64url-no-padding HMAC-SHA256 returned as part of the link by /wallets/issue/link or a Jinjava insert.
platformqueryenum<"IOS", "ANDROID">optionalWhen absent, the server renders the HTML landing page. When platform is specified, then wallet pass issuance is performed for selected platform.

Responses

StatusDescription
200 text/html, application/vnd.apple.pkpassOK: Apple .pkpass file or landing page with platform selection
302Found - Issued wallet pass for Android. The Location header points at https://pay.google.com/gp/v/save/<jwt>. Empty body.
400 application/jsonBad Request - Missing/malformed required query parameter, malformed platform enum value, or HMAC verification failed (rendered as the link-error view for the HMAC case).
404 application/jsonNot Found - issueId not found in issue_links (including soft-deleted entries), or the wallet pass record's googleCredentialId does not resolve to a credential for this tenant.
410 application/jsonGone - The issue link has expired.
500 application/jsonInternal Server Error.
502 application/jsonBad Gateway - another service or Google Wallet returned an error or is unreachable.

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/device-hub/wallets/issue?clientUuid=SOME_STRING_VALUE&issueId=SOME_STRING_VALUE&hmac=SOME_STRING_VALUE&platform=SOME_STRING_VALUE'

POST /device-hub/wallets/issue/link — Create wallet pass issue link

/api-reference/loyalty-and-engagement#tag/Wallet-passes/operation/createIssueLinkUsingPOST

Self-contained method YAML

IMPORTANT: This feature is in private preview mode and accessible only on selected workspaces. To get access, contact your account manager or Synerise Support.

Create (or reuse) a wallet issue link for the authenticated workspace. The link's origin is fetched from the given record under the wallet pass template. Calls with the same recordId and expirationTime return the same issueId (and therefore the same HMAC when clientUuid is not included in the signature).

After using this endpoint, use the link from the response as a the request to the /wallets/issue endpoint.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: WALLET_PASSES_UPDATE

User role permission required: campaigns_wallets: update

Request body (required)

application/json · device-hub-IssueLinkCreateRequest

FieldTypeRequiredDescription
clientUuidstringoptionalOptional client UUID; appended as a query param to the link and (if enabled) included in the HMAC payload.
recordIdstringrequiredWallet pass ID (id of the template in the API; part of the URL of the wallet pass details when using the Web Portal) of the template from which you want to generate a pass.
expirationTimestringoptionalOptional ISO-8601 expiration timestamp; persisted with the issue link.
eventParamsobjectoptionalOptional caller-supplied params (string→string) attached to the wallet-pass events generated for this link: walletPass.issued, walletPass.installed and walletPass.installFailed. Persisted as part of the issue link's natural key, so links differing only in these params are deduplicated separately. Reserved event keys (eventUUID, time, uuid, businessProfileId, os) cannot be overridden. Max 20 entries; keys ≤ 64 characters and values ≤ 512 characters.
contextobjectoptionalOptional caller-supplied context (string→string) forwarded to Brickworks as the context object of the record generation performed when the link is clicked, so it shapes the card's content — the record's Jinjava inserts read it as {{ context.key }} (keys that are not plain identifiers must be read as {{ context['my-key'] }}). Snapshotted onto the issued card and replayed on later regenerations (Google object update, Apple pass refresh) so a refreshed pass keeps the same content. Persisted as part of the issue link's natural key, so links differing only in context are deduped separately. Max 20 entries; keys ≤ 64 and values ≤ 512 characters.

Responses

StatusDescription
200 application/jsonOK
400 application/jsonBad Request - Validation failed (missing/invalid recordId, or malformed UUID/Instant)
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found - no such wallet pass template/record for this tenant
500 application/jsonInternal Server Error - unexpected error during request processing
502 application/jsonBad Gateway - external service returned 5xx or is unreachable

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/device-hub/wallets/issue/link \
  --header 'content-type: application/json' \
  --data '{"clientUuid":"c6e70fa5-bbfd-4e2e-9660-1407608fb247","recordId":"0470cfd4-dcf3-4d8c-ac28-58c6deeff25f","expirationTime":"2019-08-24T14:15:22Z","eventParams":{"property1":"string","property2":"string"},"context":{"property1":"string","property2":"string"}}'

POST /device-hub/wallets/update — Update wallet pass

/api-reference/loyalty-and-engagement#tag/Wallet-passes/operation/updateWalletPassUsingPOST

Self-contained method YAML

IMPORTANT: This feature is in private preview mode and accessible only on selected workspaces. To get access, contact your account manager or Synerise Support.

Queue a wallet pass update for asynchronous update. The request is validated and enqueued and the endpoint return the HTTP 202 status. You must provide one profile identifier (clientId or clientUuid, but not both).
The system locates the pass and makes an update request to the associated service: Apple sends an APN background push (the device re-fetches the pass from the web service), Google PATCHes the wallet object.

Each card emits one terminal event per platform — walletPass.updated on success or walletPass.updateFailed on failure, both always carrying the card's specific parameters. Failures add cause=noDevicesFound for an iOS pass with no registered device left (removed or automatic updates off, which are indistinguishable) or error=<message> for any other Apple or Google failure, the sole exception being an iOS pass that was issued but never installed, which is skipped with no event at all.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: WALLET_PASSES_UPDATE

User role permission required: campaigns_wallets: update

Request body (required)

application/json · device-hub-WalletsUpdateRequest

FieldTypeRequiredDescription
clientIdintegeroptionalSynerise profile ID. Mutually exclusive with clientUuid.
clientUuidstringoptionalSynerise profile UUID. Mutually exclusive with clientId.
recordIdstringrequiredWallet pass ID (id of the template in the API; part of the URL of the wallet pass details when using the Web Portal) identifying the pass to update.
platformenum<"IOS", "ANDROID">optionalOptional; restricts the update to a single platform.

Responses

StatusDescription
202Accepted - the update was enqueued and will be processed asynchronously
400 application/jsonBad Request - Validation failed (recordId missing, or not exactly one of clientId/clientUuid)
401 application/jsonUnauthorized
403 application/jsonForbidden
502 application/jsonBad Gateway - failed to enqueue the command

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/device-hub/wallets/update \
  --header 'content-type: application/json' \
  --data '{"clientId":0,"clientUuid":"c6e70fa5-bbfd-4e2e-9660-1407608fb247","recordId":"0470cfd4-dcf3-4d8c-ac28-58c6deeff25f","platform":"IOS"}'

Screen views

GET /schema-service/v3/screen-views/{feedSlug}/generate — Generate screen view from feed

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/generateScreenViewByFeedGetV2

Self-contained method YAML

When this method is called, the Synerise backend finds all screen view campaigns applicable to the JWT context and returns the screen view with the highest priority (1). Inserts are processed. If an insert can't be processed, the returned data is empty.

IMPORTANT: When the request's context is a Workspace or Synerise User JWT, only screen views with the audience set to ALL ("Everyone" in the Synerise Web Application) can be generated.

If the feed doesn't contain any screen views whose audience matches the JWT context of the request, the response is error 404.

API consumers: Workspace (Business Profile), Synerise User, Profile (Client), Anonymous Profile, Incognito Profile

API key permission required: SCHEMA_SERVICE_SCHEMA_READ

User role permission required: assets_docs: read

Parameters

NameInTypeRequiredDescription
feedSlugpathstringrequiredSlug of the screen view feed

Responses

StatusDescription
200 application/jsonProcessed JSON content
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/v3/screen-views/%7BfeedSlug%7D/generate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v3/screen-views/{feedSlug}/generate — Generate screen view from feed

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/generateScreenViewByFeedPostV2

Self-contained method YAML

When this method is called, the Synerise backend finds all screen view campaigns applicable to the JWT context and returns the screen view with the highest priority (1). Inserts are processed. If an insert can't be processed, the returned data is empty.

IMPORTANT: When the request's context is a Workspace or Synerise User JWT, only screen views with the audience set to ALL ("Everyone" in the Synerise Web Application) can be generated.

If the feed doesn't contain any screen views whose audience matches the JWT context of the request, the response is error 404.

API consumers: Workspace (Business Profile), Synerise User, Profile (Client), Anonymous Profile, Incognito Profile

API key permission required: SCHEMA_SERVICE_SCHEMA_READ

User role permission required: assets_docs: read

Parameters

NameInTypeRequiredDescription
feedSlugpathstringrequiredSlug of the screen view feed

Request body

application/json · object

Responses

StatusDescription
200 application/jsonProcessed JSON content
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v3/screen-views/%7BfeedSlug%7D/generate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"property1":"string","property2":"string"}'

POST /schema-service/screen-views/create — Create screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/create-screen-view

Self-contained method YAML

Create a screen view.

API consumer: Synerise User

User role permission required: assets_docs: create

Request body

application/json · schema-service-CreateScreenViewRequest

FieldTypeRequiredDescription
priorityintegerrequiredPriority determines which screen view to show to a customer if their profile matches the conditions of more than one screen view. 1 is the highest priority.
namestringoptionalName of the screen view
directoryIdstringrequiredUUID of a directory. Directories can be used to organize documents and screen views for display in the Synerise Web Application. If you want to organize documents for screen view campaigns, use document groups instead. If you want to organize screen views for display, use screen view feeds instead.
contentobjectrequiredContent of the screen view
audienceobjectrequiredThe profiles (clients) which have access to this resource
scheduleobjectoptionalConfiguration of the schedule
feedIdstringrequiredUUID of the feed where this screen view is assigned.

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screen-views/create \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"priority":99,"name":"string","directoryId":"786c2ec1-fb9a-4593-b705-005b34c18c18","content":{"json":{"property1":null,"property2":null},"documents":["string"],"data":[{"slug":"basket"}],"groups":["43c97b25-4a10-45d0-99b7-d472eea2bb24"],"groupsOrder":false},"audience":{"targetType":"SEGMENT","segments":["string"],"query":"{\"analysis\":{\"title\":\"Unnamed segmentation\",\"description\":\"\",\"unique\":true,\"segments\":[{\"title\":\"Segmentation A\",\"description\":\"\",\"filter\":{\"matching\":true,\"expressions\":[{\"_id\":\"a9b76c8e-34bd-4ac3-be8f-f37041d126bd\",\"name\":\"\",\"type\":\"FUNNEL\",\"matching\":true,\"funnel\":{\"_id\":\"5c759d73-49c6-409f-96a3-b569dff8f8ff\",\"title\":\"Unnamed\",\"completedWithin\":null,\"dateFilter\":{\"type\":\"RELATIVE\",\"offset\":{\"type\":\"DAYS\",\"value\":0},\"duration\":{\"type\":\"DAYS\",\"value\":30}},\"steps\":[{\"_id\":\"78b97ae0-1bc5-45fb-82a4-4f1280cfbdff\",\"title\":\"\",\"action\":{\"id\":944,\"name\":\"page.visit\"},\"eventName\":\"page.visit\",\"expressions\":[]}],\"exact\":false}}]}}]}}"},"schedule":{"enabled":true,"endDate":"2019-08-24T14:15:22Z","endType":"NEVER","parts":[{"startDay":1,"startTime":"08:18:03","endDay":1,"endTime":44283}],"periodType":"ENTIRE","startDate":"2019-08-24T14:15:22Z","startType":"NOW","timezone":"Europe/Warsaw"},"feedId":"30c3a808-1315-453b-94cf-0ccb129b558b"}'

POST /schema-service/v2/screen-views/createNew — Initialize screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/create-new-screen-view

Self-contained method YAML

Create a screen view. It is created as a blank, without any conditions.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Request body (required)

application/json · schema-service-CreateRequest

FieldTypeRequiredDescription
namestringoptionalIf no name is provided, defaults to "Unnamed document" or Screen View Campaign" (depending on what you are initializing).
directorystringoptionalIf no directory is provided, the default directory is used.

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/createNew \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"string","directory":"5277859d-f92c-478c-acab-7680a97fea68"}'

POST /schema-service/v2/screen-views/{screenViewId}/content — Add content to screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/create-screen-view-content

Self-contained method YAML

Add content to a screen view. This overwrites any existing content.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Request body

application/json · schema-service-ScreenViewContent

FieldTypeRequiredDescription
jsonobjectrequiredJSON structure of the screen view. By default, a newly created screen view has the following json value: "collection": "{% screenviewcollection %}" The {% screenviewcollection %} insert is used to pick and display the documents from the documents in documents or groups. If this insert is not used, you must manually insert each document with {% document slug%}.
documentsarray<string>requiredAn array of documents. If groups is used, this array must be empty.
dataarray<any>optionalAn array of documents or Brickworks records
groupsarray<schema-service-DocumentGroupId>requiredAn array of document groups, If documents is used, this array must be empty.
groupsOrderbooleanoptionalBy default, group are ordered for display by their priority. When this field is set to true, they are displayed according to their order in the groups array instead.

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/content \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"json":{"property1":null,"property2":null},"documents":["string"],"data":[{"slug":"basket"}],"groups":["43c97b25-4a10-45d0-99b7-d472eea2bb24"],"groupsOrder":false}'

POST /schema-service/v2/screen-views/{screenViewId}/audience — Add audience to screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/create-screen-view-audience

Self-contained method YAML

Define the audience for a screen view.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Request body

application/json · schema-service-Audience

FieldTypeRequiredDescription
targetTypeenum<"SEGMENT", "QUERY", "ALL">requiredThe method of defining the audience: SEGMENT sets the audience to segmentations whose UUIDs are provided in segments QUERY sets the audience to an analytics query provided in query ALL sets the audience to all profiles in the database
segmentsarray<string>optionalAn array of segmentation IDs. Used with targetType: SEGMENT
querystringoptionalStringified analysis object for the segmentation analytics engine. Used with targetType: QUERY. Refer to the Analytics API Reference.

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/audience \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"targetType":"SEGMENT","segments":["string"],"query":"{\"analysis\":{\"title\":\"Unnamed segmentation\",\"description\":\"\",\"unique\":true,\"segments\":[{\"title\":\"Segmentation A\",\"description\":\"\",\"filter\":{\"matching\":true,\"expressions\":[{\"_id\":\"a9b76c8e-34bd-4ac3-be8f-f37041d126bd\",\"name\":\"\",\"type\":\"FUNNEL\",\"matching\":true,\"funnel\":{\"_id\":\"5c759d73-49c6-409f-96a3-b569dff8f8ff\",\"title\":\"Unnamed\",\"completedWithin\":null,\"dateFilter\":{\"type\":\"RELATIVE\",\"offset\":{\"type\":\"DAYS\",\"value\":0},\"duration\":{\"type\":\"DAYS\",\"value\":30}},\"steps\":[{\"_id\":\"78b97ae0-1bc5-45fb-82a4-4f1280cfbdff\",\"title\":\"\",\"action\":{\"id\":944,\"name\":\"page.visit\"},\"eventName\":\"page.visit\",\"expressions\":[]}],\"exact\":false}}]}}]}}"}'

PUT /schema-service/v2/screen-views/{screenViewId}/priority — Update screen view priority

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/updateScreenViewPriority

Self-contained method YAML

Update priority in a screen view.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Request body

application/json · schema-service-screenViewPriority

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/priority \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data 99

PUT /schema-service/v2/screen-views/{screenViewId}/name — Rename screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/updateNameOfScreenView

Self-contained method YAML

Update the name of a screen view. You can update the names of active screen views.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Request body (required)

application/json · string

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/name \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '"string"'

POST /schema-service/v2/screen-views/{feedSlug}/generate/by/{identifierType} — Preview screen view with a profile context

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/generateScreenViewByIdentifierPostV2

Self-contained method YAML

This endpoint can be used to preview a generated document as a Workspace or Synerise User. To generate the output as a profile (client), use one of the following methods:

When this method is called, the Synerise backend finds all screen view campaigns in the requested feed which are applicable to the profile and returns the screen view with the highest priority (1). Inserts are processed. If an insert can't be processed, the returned data is empty.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_READ

User role permission required: assets_docs: read

Parameters

NameInTypeRequiredDescription
feedSlugpathstringrequiredSlug of the screen view feed
identifierTypepathenum<"id", "uuid", "email", "custom_identify">requiredType of the profile identifier. The value is sent in identifierValue in the request body.

Request body

application/json · object

FieldTypeRequiredDescription
identifierValuestringrequiredValue of the profile identifier selected in identifierType (profile ID is sent as a string)
paramsobjectoptionalAdditional parameters

Responses

StatusDescription
200 application/jsonProcessed JSON content
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BfeedSlug%7D/generate/by/%7BidentifierType%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"identifierValue":"string","params":{"property1":"string","property2":"string"}}'

GET /schema-service/v2/screen-views/feeds — List screen view feeds

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/feed-list

Self-contained method YAML

Returns a list of screen view feeds.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Responses

StatusDescription
200 application/jsonList of feeds
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/v2/screen-views/feeds \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v2/screen-views/feeds — Create screen view feed

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/add-feed

Self-contained method YAML

Create a new screen view feed.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Request body

application/json · schema-service-ScreenViewFeed

FieldTypeRequiredDescription
slugstringrequiredUnique slug of the screen view feed
namestringrequiredName of the screen view feed

Responses

StatusDescription
200 application/jsonFeed created
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/feeds \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"slug":"string","name":"string"}'

GET /schema-service/v2/screen-views — List screen views

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/screen-views-list

Self-contained method YAML

Returns a paginated list of screen views.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
pagequerynumberoptional
limitquerynumberoptionalLimit of items per page
searchquerystringoptionalA string to search for in resource names
directoryIdquerystringoptionalUUID of the directory for filtering the results
statusqueryenum<"DRAFT", "ACTIVE", "SCHEDULED", "PAUSED", …>optional
feedIdquerystringoptional

Responses

StatusDescription
200 application/jsonList of screen views
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/schema-service/v2/screen-views?page=SOME_NUMBER_VALUE&limit=SOME_NUMBER_VALUE&search=SOME_STRING_VALUE&directoryId=SOME_STRING_VALUE&status=SOME_STRING_VALUE&feedId=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /schema-service/v2/screen-views/{screenViewId} — Get screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/get-screen-view

Self-contained method YAML

Retrieve the details of a screen view.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_READ

User role permission required: assets_docs: read

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonDetails of the screen view
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

DELETE /schema-service/v2/screen-views/{screenViewId} — Delete screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/delete-screen-view

Self-contained method YAML

Delete a screen view.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_DELETE

User role permission required: assets_docs: delete

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonScreen view deleted
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v2/screen-views/{screenViewId}/copy — Copy screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/copy-screen-view

Self-contained method YAML

Copy a screen view. The copy receives the DRAFT status, regardless of the status of the original screen view.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonData of the created copy
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/copy \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /schema-service/v2/screen-views/{screenViewId}/predecessors — Get predecessors for screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/screenview-predecessors-get

Self-contained method YAML

Retrieve information about documents or screen views that refer to the requested screen view.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_READ

User role permission required: assets_docs: read

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonEntities which refer to the requested screen view
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/predecessors \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /schema-service/v2/screen-views/{screenViewId}/successors — Get successors for screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/screenview-successors-get

Self-contained method YAML

Retrieve information about documents referenced from the requested screen view.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_READ

User role permission required: assets_docs: read

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonDocuments referenced from the requested screen view
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/successors \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /schema-service/v2/screen-views/directory — List screen view directories

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/directory-list

Self-contained method YAML

Returns a list of screen view directories.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Responses

StatusDescription
200 application/jsonList of directories
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/v2/screen-views/directory \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v2/screen-views/directory — Add screen view directory

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/add-directory

Self-contained method YAML

Create a directory for screen views.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Request body

application/json · schema-service-NewDirectory

FieldTypeRequiredDescription
namestringrequiredName of the directory

Responses

StatusDescription
200 application/jsonDirectory created
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/directory \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"string"}'

POST /schema-service/v2/screen-views/directory/{directoryId} — Rename screen view directory

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/update-name-directory

Self-contained method YAML

Update the name of a screen view directory.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_DELETE

User role permission required: assets_docs: delete

Parameters

NameInTypeRequiredDescription
directoryIdpathstringrequiredUUID of the directory

Request body

application/json · object

FieldTypeRequiredDescription
namestringrequired

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/directory/%7BdirectoryId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"string"}'

DELETE /schema-service/v2/screen-views/directory/{directoryId} — Delete screen view directory

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/deleteDirectory

Self-contained method YAML

Delete a screen view directory. The contents are moved into the default directory.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_DELETE

User role permission required: assets_docs: delete

Parameters

NameInTypeRequiredDescription
directoryIdpathstringrequiredUUID of the directory

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/schema-service/v2/screen-views/directory/%7BdirectoryId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v2/screen-views/{screenViewId}/directory/{directoryId}/attach — Assign screen view to directory

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/attach-screen-views-to-directory

Self-contained method YAML

Assign a screen view to a directory. A screen view can only belong to one directory and using this endpoint overwrites the current assignment.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_DELETE

User role permission required: assets_docs: delete

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
directoryIdpathstringrequiredUUID of the directory

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/directory/%7BdirectoryId%7D/attach \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v2/screen-views/{screenViewId}/feed — Assign screen view to feed

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/create-screen-view-feed

Self-contained method YAML

Assign a screen view to a feed.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Request body

application/json · string

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/feed \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '"497f6eca-6276-4993-bfeb-53cbbbba6f08"'

POST /schema-service/v2/screen-views/feeds/{feedId} — Rename screen view feed

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/update-name-feed

Self-contained method YAML

Update the name of a screen view feed.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
feedIdpathstringrequiredUUID of a screen view feed

Request body

application/json · object

FieldTypeRequiredDescription
namestringrequiredNew name of the feed

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/feeds/%7BfeedId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name":"string"}'

DELETE /schema-service/v2/screen-views/feeds/{feedId} — Delete screen view feed

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/deleteFeed

Self-contained method YAML

Delete a screen view feed. The screen views currently in this feed are moved to the default feed.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_DELETE

User role permission required: assets_docs: delete

Parameters

NameInTypeRequiredDescription
feedIdpathstringrequiredUUID of a screen view feed

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/schema-service/v2/screen-views/feeds/%7BfeedId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/scheduler/entry — Schedule object

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/schedule-object

Self-contained method YAML

Add a schedule to a document or screen view.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Request body

application/json · schema-service-SchedulerRequest

FieldTypeRequiredDescription
externalIdstringoptionalUUID of the screen view or document that the schedule applies to
typeenum<"SCREENVIEW", "DOCUMENT">optionalType of the scheduled object
scheduleobjectoptionalConfiguration of the schedule

Responses

StatusDescription
200 application/jsonSchedule added
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/scheduler/entry \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"externalId":"3200d382-adfe-4314-ab30-798cdd0fcdb5","type":"SCREENVIEW","schedule":{"enabled":true,"endDate":"2019-08-24T14:15:22Z","endType":"NEVER","parts":[{"startDay":1,"startTime":"08:18:03","endDay":1,"endTime":44283}],"periodType":"ENTIRE","startDate":"2019-08-24T14:15:22Z","startType":"NOW","timezone":"Europe/Warsaw"}}'

GET /schema-service/scheduler/entry/{objectType}/{objectId} — Get schedule the schedule of an object

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/getschedule-object

Self-contained method YAML

Get schedule object.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
objectIdpathstringrequiredScreen view or document ID
objectTypepathenum<"SCREENVIEW", "DOCUMENT">requiredObject type

Responses

StatusDescription
200 application/jsonSchedule details
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonObject has no schedule; or an exception occurred.

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/scheduler/entry/%7BobjectType%7D/%7BobjectId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v2/screen-views/{screenViewId}/status/finish — Finish screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/finish-screen-view

Self-contained method YAML

Finish a screen view. A finished document is no longer displayed.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/status/finish \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v2/screen-views/{screenViewId}/status/resume — Resume screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/resume-screen-view

Self-contained method YAML

Resume a screen view that was paused.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/status/resume \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v2/screen-views/{screenViewId}/status/activate — Activate screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/activate-screen-view

Self-contained method YAML

Activate a screen view. It can be displayed to customers.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/status/activate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/v2/screen-views/{screenViewId}/status/pause — Pause screen view

/api-reference/loyalty-and-engagement#tag/Screen-views/operation/pause-screen-view

Self-contained method YAML

Pause a screen view. Until resumed, it can't be displayed to customers.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/v2/screen-views/%7BscreenViewId%7D/status/pause \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Promotions points

POST /v4/promotions/v2/points/transfer — Transfer points to another profile

/api-reference/loyalty-and-engagement#tag/Promotions-points/operation/PointsTransfer

Self-contained method YAML

With this method, a profile can send some of their points to another profile.

API consumers: Profile (Client), Anonymous Profile

Request body

application/json · object

FieldTypeRequiredDescription
pointsAmountintegerrequiredHow many points to send
recipientobjectrequiredIdentifier of the recipient
senderobjectoptionalInformation about the sender
messagestringoptionalA message that the recipient will receive with the points

Responses

StatusDescription
202 application/jsonPoint transfer scheduled
400 application/jsonBad request
404 application/jsonProfile not found
422 application/jsonUnprocessable point transfer
423 application/jsonProfile points lock error

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/v2/points/transfer \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"pointsAmount":1,"recipient":{"clientKey":"clientId","clientKeyValue":"434428563","name":"string"},"sender":{"name":"string"},"message":"string"}'

Promotion settings

GET /v4/promotions/settings — Get settings for current Workspace

/api-reference/loyalty-and-engagement#tag/Promotion-settings/operation/endpointSettingsGetSettingsGET

Self-contained method YAML

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_SETTINGS_PROMOTIONS_READ

User role permission required: campaigns_personalised_promotions: read

Parameters

NameInTypeRequiredDescription
onlyquerystringoptionalReturn only the settings property at this dotted path (e.g. saleSettings.discountOrder.strategy) instead of the whole settings object. Responds with 404 when the property is not defined.
withDefaultsquerybooleanoptionalWhen true, missing values are filled from the server-side defaults before the response is built. Combined with only, a property that has a configured default resolves even when the Workspace has not stored it; a property without a default still responds with 404.

Responses

StatusDescription
200 application/jsonOK
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot Found

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/v4/promotions/settings?only=saleSettings.combineBasketDiscounts&withDefaults=SOME_BOOLEAN_VALUE'

PUT /v4/promotions/settings — Update settings for current Workspace

/api-reference/loyalty-and-engagement#tag/Promotion-settings/operation/endpointSettingsUpdateSettingsPUT

Self-contained method YAML

This method overrides all current settings. If you do not send a setting that currently exists, it will be reverted to default value.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_SETTINGS_PROMOTIONS_UPDATE

User role permission required: campaigns_personalised_promotions: update

Request body

application/json · promotions-promotionsSettingsBody

FieldTypeRequiredDescription
checkoutSettingsobjectoptionalHandbill checkout settings
enableCodeGenerationbooleanoptionalFlag which indicates if promotion code should be generated as ordinal number prefixed with prefix defined in codePrefix
codePrefixstringoptionalPrefix which will be added to promotion code, when enableCodeGeneration is set to true
blockTagstringoptionalTag name which marks a profile as blocked. Blocked profiles do not receive promotions in POS methods and are not allowed to activate new promotions.
expressionstringoptionalExpression UUID which will be used to count the balance of loyalty points in the promotion activation endpoint.
promotionListSettingsobjectoptionalFilter for promotions in /promotion/get-for-client-by-custom-settings/{identifierType}/{identifierValue} method
promotionAssignmentSettingsobjectoptionalFilter for promotions in the /promotion/get-for-client/{identifierType}/{identifierValue}/handbill/{handbillUuid} and /promotion/get-for-client/{identifierType}/{identifierValue}/with-handbills methods. For where fields not defined in the stored settings, the following defaults apply: target: ["ALL", "SEGMENT"], visibilityStatus: ["PUBLISH"], type: ["GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL"], presentOnly: true, lastingOnly: true, displayOnly: false. Precedence (lowest to highest): defaults, stored settings, request query parameters.
restorePointsOnProfileDeactivationbooleanoptionalWhen set to true and you use the method which deactivates all promotions for a profile, the points taken for activation of the promotion will be restored.
allowRedeemCompletionWhenBlockedbooleanoptionalWhen set to true, the profile can complete the redemption of promotions that had been activated before a lock was put on that profile.
saleSettingsobjectoptionalSettings for sales
lockSettingsobjectoptionalSettings for locks
transferSettingsarray<object>optionalSettings for point transfers
cashbackSettingsobjectoptionalSettings for cashback mechanism

Responses

StatusDescription
200 application/jsonOK
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/v4/promotions/settings \
  --header 'content-type: application/json' \
  --data '{"checkoutSettings":{"handbillUuidsForCheckout":["497f6eca-6276-4993-bfeb-53cbbbba6f08"],"codeGeneration":{"prefix":"string","length":36,"crc":true}},"enableCodeGeneration":true,"codePrefix":"SYN","blockTag":"BLOCKED","expression":"8e30707e-988c-498c-a88e-47375a3dcfb5","promotionListSettings":{"setFieldsValues":{},"where":{"excludeIds":[3],"handbillPromotionIds":[3],"visibilityStatus":["DRAFT"],"status":["ASSIGNED"],"statusByType":{"GENERAL":["ASSIGNED"],"CUSTOM":["ASSIGNED"],"MEMBERS_ONLY":["ASSIGNED"],"HANDBILL":["ASSIGNED"]},"target":["ALL"],"targetByType":{"GENERAL":["ALL"],"CUSTOM":["ALL"],"MEMBERS_ONLY":["ALL"],"HANDBILL":["ALL"]},"type":["MEMBERS_ONLY"],"presentOnly":true,"lastingOnly":true,"displayableOnly":true,"checkExistsInTarget":true,"tagNames":["string"]},"fields":["string"],"sort":{"forDBQuery":[{"field":"headerName","direction":"asc"}]},"page":0,"limit":0},"promotionAssignmentSettings":{"setFieldsValues":{},"where":{"excludeIds":[3],"handbillPromotionIds":[3],"visibilityStatus":["DRAFT"],"status":["ASSIGNED"],"statusByType":{"GENERAL":["ASSIGNED"],"CUSTOM":["ASSIGNED"],"MEMBERS_ONLY":["ASSIGNED"],"HANDBILL":["ASSIGNED"]},"target":["ALL"],"targetByType":{"GENERAL":["ALL"],"CUSTOM":["ALL"],"MEMBERS_ONLY":["ALL"],"HANDBILL":["ALL"]},"type":["MEMBERS_ONLY"],"presentOnly":true,"lastingOnly":true,"displayableOnly":true,"checkExistsInTarget":true,"tagNames":["string"]},"fields":["string"],"sort":{"forDBQuery":[{"field":"headerName","direction":"asc"}]},"page":0,"limit":0},"restorePointsOnProfileDeactivation":true,"allowRedeemCompletionWhenBlocked":false,"saleSettings":{"discountSourceType":0,"clientIdCardType":0,"handbillCheckout":"04845f2a-86bf-4319-89c4-1f24d4e1f58e","priceValueBaseStrategy":"CONSTANT","combineBasketDiscounts":false,"discountOrder":{"strategy":"DISCOUNT_VALUE","direction":"asc"},"returnFields":["string"]},"lockSettings":{"promotionRequestedLockTtl":60,"processSalePromotionActivationLockWaitTime":0,"lockPromotionRequestByIdentifier":true},"transferSettings":[{"expression":"2395fc33-f2f0-420c-8e7b-0ac63c3454de","recipient":{"segments":["string"]},"sender":{"segments":["string"]}}],"cashbackSettings":{"exchangeRate":0.0001,"limits":{"minPoints":10,"maxPoints":1000,"maxTransactionAmount":20,"maxTransactionPercentage":50}}}'

Promotion locks

GET /v4/promotions/promotion/locking/check-client — Check account lock

/api-reference/loyalty-and-engagement#tag/Promotion-locks/operation/CheckAccountLock

Self-contained method YAML

You can check if a Profile account is locked due to processing of batch promotion/voucher activations or deactivations.

You must be logged in as the Profile.

API consumers: Profile (Client), Anonymous Profile

Responses

StatusDescription
200 application/jsonInformation about Profile lock
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/promotions/promotion/locking/check-client \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /v4/promotions/lock/create-points-lock-for-client/{identifierType}/{identifierValue} — Create point lock for profile

/api-reference/loyalty-and-engagement#tag/Promotion-locks/operation/endpointLockCreateLockForClientPOST

Self-contained method YAML

Create a point lock for a profile. That profile cannot activate or de-activate promotions based on loyalty points until the lock is released. The profile can still redeem promotions.
This lock is released with the "Release point lock for profile" endpoint or when its TTL (defined in the query parameters) expires.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_LOCK_UPDATE

User role permission required: campaigns_promotions: update

Parameters

NameInTypeRequiredDescription
lockTtlSecquerynumberoptionalLock duration in seconds
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier

Responses

StatusDescription
200 application/jsonLock created
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonProfile not found

Example request (cURL)

curl --request POST \
  --url 'https://api.synerise.com/v4/promotions/lock/create-points-lock-for-client/email/%7BidentifierValue%7D?lockTtlSec=SOME_NUMBER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /v4/promotions/lock/release-points-lock-for-client/{identifierType}/{identifierValue}/{lockIdentifier} — Release point lock for profile

/api-reference/loyalty-and-engagement#tag/Promotion-locks/operation/endpointLockReleaseLockForClientPOST

Self-contained method YAML

Release a point lock from a profile. That profile can now activate and de-activate promotions based on loyalty points.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_LOCK_UPDATE

User role permission required: campaigns_promotions: update

Parameters

NameInTypeRequiredDescription
lockIdentifierpathstringrequiredLock identifier
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier

Responses

StatusDescription
200 application/jsonLock released
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonProfile not found
409 application/jsonLock already exists

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/lock/release-points-lock-for-client/email/%7BidentifierValue%7D/2f01c1b4-4266-41cb-b8d9-fd00457eedef.1640081408119 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /v4/promotions/lock/release-promotion-requested-lock-for-client/{identifierType}/{identifierValue}/{lockIdentifier} — Release "promotion requested" lock from profile

/api-reference/loyalty-and-engagement#tag/Promotion-locks/operation/endpointLockReleasePromotionRequestedLockForClientPOST

Self-contained method YAML

Release a "promotion requested" lock from a profile. That profile can now fetch promotion lists. This kind of lock can be applied when using the Get Profile promotions by a custom filter endpoint.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_LOCK_UPDATE

User role permission required: campaigns_promotions: update

Parameters

NameInTypeRequiredDescription
lockIdentifierpathstringrequiredLock identifier
identifierTypepathenum<"email", "phone", "externalId", "uuid", …>requiredThe Profile identifier to use for the request. externalId is known as customId or custom_identify in other Synerise services.
identifierValuepathstringrequiredThe value of the selected identifier

Responses

StatusDescription
200 application/jsonLock released
400 application/jsonRequest body invalid/malformed/missing elements
401 application/jsonUnauthorized
403 application/jsonForbidden
404 application/jsonNot found

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/v4/promotions/lock/release-promotion-requested-lock-for-client/email/%7BidentifierValue%7D/2f01c1b4-4266-41cb-b8d9-fd00457eedef.1640081408119 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Screen views (legacy)

GET /schema-service/screenViews — Get all screen views (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/listOfScreenViews

Self-contained method YAML

Retrieve a paginated list of all screen view campaigns in the workspace.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: SCHEMA_SERVICE_SCHEMA_READ

User role permission required: assets_docs: read

Parameters

NameInTypeRequiredDescription
limitquerystringrequiredThe maximum number of items to retrieve for pagination
pagequeryintegerrequiredThe number of the page to retrieve
statusqueryenum<"DRAFT", "ACTIVE", "SCHEDULED", "PAUSED", …>optionalFilter the results by screen view status

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/schema-service/screenViews?limit=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE&status=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/screenViews/byKeys — Get screen views by keys (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/listOfScreenViewsByKeys

Self-contained method YAML

Retrieve list of screen view campaigns by keys in the workspace.

API consumer: Synerise User

User role permission required: assets_docs: read

Request body

application/json · array<string>

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screenViews/byKeys \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '["string"]'

GET /schema-service/screenViews/single/{screenViewId}/{screenViewVersion} — Get screen view (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/getScreenViewByVersion

Self-contained method YAML

Retrieve the details of a single screen view campaign.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: SCHEMA_SERVICE_SCHEMA_READ

User role permission required: assets_docs: read

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
screenViewVersionpathstringrequiredVersion of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/screenViews/single/%7BscreenViewId%7D/%7BscreenViewVersion%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /schema-service/screenViews/versions/{screenViewId} — Get screen view versions (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/listOfScreenViewVersions

Self-contained method YAML

Retrieve all versions of a screen view campaign.

API consumers: Synerise User, Workspace (Business Profile)

API key permission required: SCHEMA_SERVICE_SCHEMA_READ

User role permission required: assets_docs: read

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
limitquerystringrequiredThe maximum number of items to retrieve for pagination
pagequeryintegerrequiredThe number of the page to retrieve

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url 'https://api.synerise.com/schema-service/screenViews/versions/%7BscreenViewId%7D?limit=SOME_STRING_VALUE&page=SOME_INTEGER_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /schema-service/screenViews/generate — Generate screen view (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/generateScreenViewGet

Self-contained method YAML

When this method is called, the Synerise backend finds all screen view campaigns applicable to the profile and returns the screen view with the highest priority (1).

API consumers: Workspace (Business Profile), Synerise User, Profile (Client), Anonymous Profile

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Responses

StatusDescription
200 application/jsonProcessed JSON content
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/screenViews/generate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

GET /schema-service/v2/screenViews/generate — Generate screen view (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/generateScreenViewWithAdditionalDataGet

Self-contained method YAML

When this method is called, the Synerise backend finds all screen view campaigns applicable to the profile and returns the screen view with the highest priority (1).

API consumers: Workspace (Business Profile), Synerise User, Profile (Client), Anonymous Profile

API key permission required: SCHEMA_SERVICE_SCHEMA_CREATE

User role permission required: assets_docs: create

Responses

StatusDescription
200 application/jsonProcessed JSON content
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/schema-service/v2/screenViews/generate \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/screenViews/createNew — Initialize screen view (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/initializeScreenViewPost

Self-contained method YAML

Create a new screen view campaign. It is created as a blank, without any conditions.

API consumer: Synerise User

User role permission required: assets_docs: create

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screenViews/createNew \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

POST /schema-service/screenViews/content/{screenViewId}/{screenViewVersion}/copyFromExistingScreenView — Copy content (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/copyContent

Self-contained method YAML

Copy content to a screen view draft from another screen view.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
screenViewVersionpathstringrequiredVersion of the screen view

Request body

application/json · schema-service-versionedScreenViewKey

FieldTypeRequiredDescription
screenViewIdstringoptionalUUID of the screen view
screenViewVersionstringoptionalVersion of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screenViews/content/%7BscreenViewId%7D/%7BscreenViewVersion%7D/copyFromExistingScreenView \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"screenViewId":"481855c5-f86e-453f-a0fa-d34b5a2be745","screenViewVersion":"string"}'

POST /schema-service/screenViews/content/{screenViewId}/{screenViewVersion} — Add content (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/createContent

Self-contained method YAML

Add content to a screen view draft.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
screenViewVersionpathstringrequiredVersion of the screen view

Request body

application/json · schema-service-ScreenViewContent

FieldTypeRequiredDescription
jsonobjectrequiredJSON structure of the screen view. By default, a newly created screen view has the following json value: "collection": "{% screenviewcollection %}" The {% screenviewcollection %} insert is used to pick and display the documents from the documents in documents or groups. If this insert is not used, you must manually insert each document with {% document slug%}.
documentsarray<string>requiredAn array of documents. If groups is used, this array must be empty.
dataarray<any>optionalAn array of documents or Brickworks records
groupsarray<schema-service-DocumentGroupId>requiredAn array of document groups, If documents is used, this array must be empty.
groupsOrderbooleanoptionalBy default, group are ordered for display by their priority. When this field is set to true, they are displayed according to their order in the groups array instead.

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screenViews/content/%7BscreenViewId%7D/%7BscreenViewVersion%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"json":{"property1":null,"property2":null},"documents":["string"],"data":[{"slug":"basket"}],"groups":["43c97b25-4a10-45d0-99b7-d472eea2bb24"],"groupsOrder":false}'

POST /schema-service/screenViews/audience/{screenViewId}/{screenViewVersion} — Add audience (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/createAudience

Self-contained method YAML

Define the audience for a screen view draft.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
screenViewVersionpathstringrequiredVersion of the screen view

Request body

application/json · schema-service-Audience

FieldTypeRequiredDescription
targetTypeenum<"SEGMENT", "QUERY", "ALL">requiredThe method of defining the audience: SEGMENT sets the audience to segmentations whose UUIDs are provided in segments QUERY sets the audience to an analytics query provided in query ALL sets the audience to all profiles in the database
segmentsarray<string>optionalAn array of segmentation IDs. Used with targetType: SEGMENT
querystringoptionalStringified analysis object for the segmentation analytics engine. Used with targetType: QUERY. Refer to the Analytics API Reference.

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screenViews/audience/%7BscreenViewId%7D/%7BscreenViewVersion%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"targetType":"SEGMENT","segments":["string"],"query":"{\"analysis\":{\"title\":\"Unnamed segmentation\",\"description\":\"\",\"unique\":true,\"segments\":[{\"title\":\"Segmentation A\",\"description\":\"\",\"filter\":{\"matching\":true,\"expressions\":[{\"_id\":\"a9b76c8e-34bd-4ac3-be8f-f37041d126bd\",\"name\":\"\",\"type\":\"FUNNEL\",\"matching\":true,\"funnel\":{\"_id\":\"5c759d73-49c6-409f-96a3-b569dff8f8ff\",\"title\":\"Unnamed\",\"completedWithin\":null,\"dateFilter\":{\"type\":\"RELATIVE\",\"offset\":{\"type\":\"DAYS\",\"value\":0},\"duration\":{\"type\":\"DAYS\",\"value\":30}},\"steps\":[{\"_id\":\"78b97ae0-1bc5-45fb-82a4-4f1280cfbdff\",\"title\":\"\",\"action\":{\"id\":944,\"name\":\"page.visit\"},\"eventName\":\"page.visit\",\"expressions\":[]}],\"exact\":false}}]}}]}}"}'

POST /schema-service/screenViews/publish/{screenViewId}/{screenViewVersion} — Publish screen view (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/publishScreenView

Self-contained method YAML

Make the screen view accessible to customers.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
screenViewVersionpathstringrequiredVersion of the screen view

Request body

application/json · schema-service-publishRequest

FieldTypeRequiredDescription
overwritebooleanrequiredCurrently unused

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screenViews/publish/%7BscreenViewId%7D/%7BscreenViewVersion%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"overwrite":true}'

POST /schema-service/screenViews/copyDraftFromExistingScreenView — Copy draft from existing screen view (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/copyDraftFromExistingScreenView

Self-contained method YAML

Copy a duplicate of an active screen view. The duplicate is in draft status.

API consumer: Synerise User

User role permission required: assets_docs: create

Request body

application/json · schema-service-versionedScreenViewKey

FieldTypeRequiredDescription
screenViewIdstringoptionalUUID of the screen view
screenViewVersionstringoptionalVersion of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screenViews/copyDraftFromExistingScreenView \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"screenViewId":"481855c5-f86e-453f-a0fa-d34b5a2be745","screenViewVersion":"string"}'

POST /schema-service/screenViews/createDraftFromExistingScreenView — Create draft from existing screen view (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/createDraftFromExistingScreenView

Self-contained method YAML

Create a duplicate of an active screen view. The duplicate is in draft status.

API consumer: Synerise User

User role permission required: assets_docs: create

Request body

application/json · schema-service-versionedScreenViewKey

FieldTypeRequiredDescription
screenViewIdstringoptionalUUID of the screen view
screenViewVersionstringoptionalVersion of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screenViews/createDraftFromExistingScreenView \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"screenViewId":"481855c5-f86e-453f-a0fa-d34b5a2be745","screenViewVersion":"string"}'

PUT /schema-service/screenViews/single/{screenViewId}/{screenViewVersion}/description — Update screen view description (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/updateDescriptionOfScreenView

Self-contained method YAML

Update the description of a screen view. You can update the descriptions of active screen views.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
screenViewVersionpathstringrequiredVersion of the screen view

Request body

application/json · string

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/schema-service/screenViews/single/%7BscreenViewId%7D/%7BscreenViewVersion%7D/description \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '"string"'

PUT /schema-service/screenViews/single/{screenViewId}/{screenViewVersion}/priority — Update screen view priority (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/updatePriorityOfScreenView

Self-contained method YAML

Update the priority of a screen view. You can update the priorities of active screen views.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
screenViewVersionpathstringrequiredVersion of the screen view

Request body (required)

application/json · integer

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request PUT \
  --url https://api.synerise.com/schema-service/screenViews/single/%7BscreenViewId%7D/%7BscreenViewVersion%7D/priority \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data 0

POST /schema-service/screenViews/discardChanges/{screenViewId}/{screenViewVersion} — Discard changes (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/discardChanges

Self-contained method YAML

Discard the changes made in a version of a screen view.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
screenViewVersionpathstringrequiredVersion of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request POST \
  --url https://api.synerise.com/schema-service/screenViews/discardChanges/%7BscreenViewId%7D/%7BscreenViewVersion%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

DELETE /schema-service/screenViews/delete/{screenViewId} — Delete screen view (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/deleteScreenView

Self-contained method YAML

Delete a screen view and all its versions. This operation is irreversible.

API consumer: Synerise User

User role permission required: assets_docs: delete

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/schema-service/screenViews/delete/%7BscreenViewId%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

DELETE /schema-service/screenViews/single/delete/{screenViewId}/{screenViewVersion} — Delete screen view version (deprecated)

/api-reference/loyalty-and-engagement#tag/Screen-views-(legacy)/operation/deleteSingleScreenView

Self-contained method YAML

Delete a version of a screen view.

API consumer: Synerise User

User role permission required: assets_docs: delete

Parameters

NameInTypeRequiredDescription
screenViewIdpathstringrequiredUUID of the screen view
screenViewVersionpathstringrequiredVersion of the screen view

Responses

StatusDescription
200 application/jsonSuccess
400 application/jsonSee error message for details
401 application/jsonUnauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
403 application/jsonForbidden; insufficient permissions
404 application/jsonResource not found
500 application/jsonSee error message for details

Example request (cURL)

curl --request DELETE \
  --url https://api.synerise.com/schema-service/screenViews/single/delete/%7BscreenViewId%7D/%7BscreenViewVersion%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Back to all API categories