Loyalty and Engagement — API Reference

Win the loyalty of your customers with promotions and personalized offers

124 endpoints across 8 tags.

Promotions

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

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

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

Name	In	Type	Required	Description
`sort`	query	string	optional	The 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 Additionally, you can add the following attributes: `ai` : enables ai sorting, should be only combined with `status` sorting (direction of sorting is not needed) 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`
`status`	query	array<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>	optional	Filter by promotion status
`presentOnly`	query	boolean	optional	When 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.
`displayableOnly`	query	boolean	optional	When set to `true`, promotions which are not currently active are included in response, according to date range defined in promotion fields `displayFrom` and `displayTo`.
`tagNames`	query	array<string>	optional	Filter the response to promotions with a certain tag or tags
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`includeMeta`	query	boolean	optional	When `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
`checkGlobalActivationLimits`	query	boolean	optional	Flag to indicate if global limits should be checked
`includeVouchers`	query	boolean	optional	When `true`, promotion with defined vouchers will also have list of assigned vouchers. When `false`, vouchers will not be fetched.
`storeIds`	query	string	optional	Limits the response to data from particular stores, identified by IDs.

Responses

Status	Description
`200` `application/json`	An array of promotions
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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.

Field	Type	Required	Description
`uuid`	string	optional	Promotion UUID
`code`	string	optional	Promotion code

Responses

Status	Description
`200` `application/json`	Promotion duplicated
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Promotion not found
`500`	Internal 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

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

Field	Type	Required	Description
`key`	enum<"uuid", "code">	required	Type of promotion identifier
`value`	string	required	Value of the selected identifier
`pointsToUse`	integer	optional	How many points should be converted to digital money and stored as ready to redeem in transactions in digital cashback promotions.

Responses

Status	Description
`200` `application/json`	Promotion activated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Profile, promotion, or related resource not found
`409` `application/json`	Waiting for profile lock release
`412` `application/json`	Already activated/Already redeemed/Activation limit reached/Promotion not started/Promotion expired
`422` `application/json`	Global Activation limit reached
`423` `application/json`	Profile promotions blocked
`500`	General 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

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

API consumers: Profile (Client), Anonymous Profile

Request body (required)

application/json · array<promotions-promotionActivation>

Responses

Status	Description
`200` `application/json`	Promotions activated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Profile, promotion, or related resource not found
`409` `application/json`	Waiting for profile lock release
`412` `application/json`	Already activated/Already redeemed/Activation limit reached/Promotion not started/Promotion expired
`423` `application/json`	Profile promotions blocked
`500`	General 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

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

Field	Type	Required	Description
`key`	enum<"uuid", "code">	required	Type of promotion identifier
`value`	string	required	Value of the selected identifier
`pointsToUse`	integer	optional	How many points should be converted to digital money and stored as ready to redeem in transactions in digital cashback promotions.

Responses

Status	Description
`200` `application/json`	Promotion deactivated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Promotion deactivation is forbidden due to promotion setup.
`404` `application/json`	Not Found
`429` `application/json`	Waiting 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

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

Status	Description
`200` `application/json`	Promotions deactivated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not Found
`429` `application/json`	Waiting 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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier
`returnCodes`	query	boolean	optional	Return deactivated codes
`lockPoints`	query	boolean	optional	Lock profile points during the deactivation process
`excludeTags`	query	array<string>	optional	Promotions with the tags included in this list will not be deactivated

Responses

Status	Description
`200` `application/json`	All promotions deactivated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Profile 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

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

Field	Type	Required	Description
`code`	string	required	Promotion code
`clientKey`	enum<"externalId", "clientId", "email", "phone", …>	required	Type of profile identifier
`clientKeyValue`	string	required	Value of the selected identifier
`quantity`	integer	optional	Quantity of redeemed items
`sourceId`	string	optional	The 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.
`orderId`	string	optional	Receipt 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.
`lockIdentifier`	string	optional	Identifier 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

Status	Description
`201` `application/json`	Promotion redeemed successfully
`209` `application/json`	Promotion is already redeemed
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not found error
`409` `application/json`	Waiting for profile lock release
`412` `application/json`	Unprocessable redemption
`423` `application/json`	Profile 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

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

Status	Description
`201` `application/json`	Promotion redeemed successfully
`209` `application/json`	Promotion is already redeemed
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not found error
`409` `application/json`	Waiting for profile lock release
`412` `application/json`	Unprocessable redemption
`423` `application/json`	Profile 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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier
`sort`	query	string	optional	The 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 Additionally, you can add the following attributes: `ai` : enables ai sorting, should be only combined with `status` sorting (direction of sorting is not needed) 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`
`status`	query	array<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>	optional	Filter by promotion status
`presentOnly`	query	boolean	optional	When 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.
`displayableOnly`	query	boolean	optional	When set to `true`, promotions which are not currently active are included in response, according to date range defined in promotion fields `displayFrom` and `displayTo`.
`tagNames`	query	array<string>	optional	Filter the response to promotions with a certain tag or tags
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`includeMeta`	query	boolean	optional	When `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
`fields`	query	array<enum<"uuid", "code", "status", "type", …>>	optional	Return only specified promotion fields. If `fields` is not specified, all fields are returned.
`promotionUuids`	query	string	optional	Filters the response data by a list of promotion UUIDs.
`checkGlobalActivationLimits`	query	boolean	optional	Flag to indicate if global limits should be checked
`includeVouchers`	query	boolean	optional	When `true`, promotion with defined vouchers will also have list of assigned vouchers. When `false`, vouchers will not be fetched.
`storeIds`	query	string	optional	Limits the response to data from particular stores, identified by IDs.

Responses

Status	Description
`200` `application/json`	An array of promotions
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Profile 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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"uuid", "code">	required	The promotion identifier to use for the request
`identifierValue`	path	string	required	The value of the selected identifier
`lastingOnly`	query	boolean	optional	When 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

Status	Description
`200` `application/json`	Details of a promotion
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not 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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"uuid", "code">	required	The promotion identifier to use for the request
`identifierValue`	path	string	required	The value of the selected identifier

Responses

Status	Description
`200` `application/json`	Details of a promotion
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not 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

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

Name	In	Type	Required	Description
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`storeCatalog`	query	string	optional	Limits the response to data from stores included in a catalog.
`storeIds`	query	string	optional	Limits the response to data from particular stores, identified by IDs.
`includeMeta`	query	boolean	optional	When `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
`orderFieldName`	query	enum<"createdAt", "headerName", "code", "startAt", …>	optional	Name of the parameter used for sorting
`order`	query	enum<"asc", "desc">	optional	Sorting order
`query`	query	string	optional	A string to search for in the `headerName` parameter or fragment of UUID.
`promotionUuids`	query	string	optional	Filters the response data by a list of promotion UUIDs.
`targetByType`	query	string	optional	A combination of target and type, for example `[SEGMENT]=ACTIVE`

Responses

Status	Description
`200` `application/json`	An array of promotions
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

Name	In	Type	Required	Description
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`storeCatalog`	query	string	optional	Limits the response to data from stores included in a catalog.
`storeIds`	query	string	optional	Limits the response to data from particular stores, identified by IDs.
`target`	query	array<enum<"ALL", "SEGMENT">>	optional	The target of the promotion
`includeMeta`	query	boolean	optional	When `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
`presentOnly`	query	boolean	optional	When 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.
`visibilityStatus`	query	array<enum<"DRAFT", "PUBLISH", "HIDDEN">>	optional	Visibility status
`upsertTimestamp`	query	string	optional	Defines the date since which the differences are shown. If not defined, defaults to infinity.
`orderFieldName`	query	enum<"createdAt", "headerName", "code", "startAt", …>	optional	Name of the parameter used for sorting
`order`	query	enum<"asc", "desc">	optional	Sorting order
`query`	query	string	optional	A string to search for in the `headerName` parameter or fragment of UUID.

Responses

Status	Description
`200` `application/json`	An array of promotions. If a promotion was deleted, the `deletedAt` field is included
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier
`sort`	query	string	optional	The 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 Additionally, you can add the following attributes: `ai` : enables ai sorting, should be only combined with `status` sorting (direction of sorting is not needed) 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`
`status`	query	array<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>	optional	Filter 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.
`tagNames`	query	array<string>	optional	Filter the response to promotions with a certain tag or tags
`target`	query	array<enum<"ALL", "SEGMENT">>	optional	The target of the promotion
`type`	query	array<enum<"GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL">>	optional	Promotion type
`presentOnly`	query	boolean	optional	When 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.
`lastingOnly`	query	boolean	optional	When set to `true`, shows promotions/vouchers that are currently active and those that are still inactivated. (lastingAt set to null or lastingAt in future)
`displayableOnly`	query	boolean	optional	When set to `true`, promotions which are not currently active are included in response, according to date range defined in promotion fields `displayFrom` and `displayTo`.
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`includeMeta`	query	boolean	optional	When `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
`includeVouchers`	query	boolean	optional	When `true`, promotion with defined vouchers will also have list of assigned vouchers. When `false`, vouchers will not be fetched.
`storeIds`	query	string	optional	Limits the response to data from particular stores, identified by IDs.

Responses

Status	Description
`200` `application/json`	An array of promotions
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier
`sort`	query	string	optional	The 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 Additionally, you can add the following attributes: `ai` : enables ai sorting, should be only combined with `status` sorting (direction of sorting is not needed) 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`
`presentOnly`	query	boolean	optional	When 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.
`lastingOnly`	query	boolean	optional	When set to `true`, shows promotions/vouchers that are currently active and those that are still inactivated. (lastingAt set to null or lastingAt in future)
`displayableOnly`	query	boolean	optional	When set to `true`, promotions which are not currently active are included in response, according to date range defined in promotion fields `displayFrom` and `displayTo`.
`status`	query	array<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>	optional	Filter by promotion status
`type`	query	array<enum<"GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL">>	optional	Promotion type
`statusByType`	query	string	optional	A combination of status and type, for example `[CUSTOM]=ACTIVE`
`targetByType`	query	string	optional	A combination of target and type, for example `[SEGMENT]=ACTIVE`
`includeMeta`	query	boolean	optional	When `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
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`limit`	query	integer	optional	The number of items to return per page
`target`	query	array<enum<"ALL", "SEGMENT">>	optional	The target of the promotion
`storeIds`	query	string	optional	Limits the response to data from particular stores, identified by IDs.

Responses

Status	Description
`200` `application/json`	An array of promotions
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"uuid", "code">	required	The promotion identifier to use for the request
`identifierValue`	path	string	required	The value of the selected identifier

Responses

Status	Description
`200` `application/json`	Details of a promotion
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not 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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"uuid", "code">	required	The promotion identifier to use for the request
`identifierValue`	path	string	required	The value of the selected identifier

Request body (required)

application/json · promotions-promotionDataCreate

Field	Type	Required	Description
`visibilityStatus`	enum<"DRAFT", "PUBLISH", "HIDDEN">	optional	Profile-oriented status of the promotion.
`type`	enum<"MEMBERS_ONLY", "HANDBILL", "CUSTOM", "GENERAL">	optional	Promotion type
`redeemLimitPerClient`	integer	optional	Limit how many times a Profile can redeem this promotion.
`redeemQuantityPerActivation`	integer	optional	How many times per activation a multibuy promotion can be redeemed
`redeemLimitGlobal`	integer	optional	Limit the total of redemptions by all Profiles
`redeemType`	enum<"FULL", "PARTIAL">	optional	Promotion redemption type
`details`	object	optional	Promotion details
`discountType`	enum<"PERCENT", "POINTS", "AMOUNT", "NONE", …>	optional	The type of discount
`discountValue`	number	optional	How much discount to apply
`discountMode`	enum<"STATIC", "STEP">	optional	Promotion discount mode
`discountModeDetails`	object	optional	Applies only when `"discountMode": "STATIC"`.
`preDiscountValue`	number	optional	In 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.
`requireRedeemedPoints`	number	optional	How many loyalty points are needed to activate the promotion
`headerName`	string	optional	Name displayed in Synerise Web UI
`headerDescription`	string	optional	Description displayed in Synerise Web UI
`name`	string	optional	Promotion name displayed to viewers
`headline`	string	optional	Promotion headline displayed to viewers
`description`	string	optional	Details of the promotion displayed to viewers
`images`	array<object>	optional	Images and thumbnails for the promotion
`tags`	array<object>	optional	An 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.
`startAt`	string	optional	Time when the promotion becomes available. Defaults to current time.
`expireAt`	string	optional	Time when the promotion ends for all profiles. Defaults to current time. Has to be greater than startAt
`displayFrom`	string	optional	Time when the promotion becomes displayable. Defaults to null.
`displayTo`	string	optional	Time when the promotion stops being displayed for users. Defaults to null. Has to be greater than displayFrom.
`lastingTime`	integer	optional	Duration of the promotion in seconds. This countdown starts when the profile activates a promotion and is individual for each profile.
`params`	object	optional	A JSON object with any custom parameters of type string, object, array.
`itemScope`	enum<"LINE_ITEM", "BASKET">	optional	The 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
`minBasketValue`	number	optional	Minimal 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`.
`maxBasketValue`	number	optional	The 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.
`catalog`	string	optional	ID of the item catalog that the promotion applies to
`catalogItemType`	enum<"ALL", "SELECTED", "FILTERED">	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`.
`catalogIndexItems`	array<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.'
`catalogFilterIds`	array<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.'
`excludeCatalog`	string	optional	ID of the item catalog that the promotion should exclude
`excludeCatalogItemType`	enum<"ALL", "SELECTED", "FILTERED">	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`.
`excludeCatalogIndexItems`	array<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.'
`excludeCatalogFilterIds`	array<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.'
`activationLimitGlobalType`	enum<"RELATIVE", "LIFETIME">	optional	Promotion 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).
`activationLimitGlobalLimit`	integer	optional	Limit the total of activations by all Profiles within given time unit.
`activationLimitGlobalRelativeMinutes`	integer	optional	Used only when `type` is `RELATIVE`. Defines how many minutes back from the current time the limit applies.
`storeCatalog`	string	optional	ID of the store catalog that the promotion applies to
`storeItemType`	enum<"ALL", "SELECTED">	optional	Defines if the promotion is available for the entire store catalog or only certain stores (listed in `storeIds`).
`storeIds`	array<string>	optional	An array of stores from the store catalog where the promotion is available if `storeItemType` is set to `SELECTED`
`targetType`	enum<"ALL", "SEGMENT">	optional	If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
`targetSegment`	array<string>	optional	This field applies only when `targetType` is set to "SEGMENT".
`price`	integer	optional	In 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.
`priority`	integer	optional	Defines the priority of the promotion for display. `1` is the highest priority.
`voucherPool`	object	optional	Settings 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.
`importHash`	string	optional	Hash of the import

Responses

Status	Description
`200` `application/json`	Promotion updated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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"]},"discountedItemsCount":1},"cashbackSettings":{"exchangeRate":0.01,"limits":{"minPoints":10,"maxPoints":1000,"maxTransactionAmount":20,"maxTransactionPercentage":50}}},"discountType":"PERCENT","discountValue":0,"discountMode":"STATIC","discountModeDetails":{"discountSteps":[{"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"],"excludeCatalog":["311"],"excludeCatalogItemType":"SELECTED","excludeCatalogIndexItems":["29727276"],"excludeCatalogFilterIds":[],"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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`limit`	query	integer	optional	The number of items to return per page
`lockIdentifier`	query	string	optional	Identifier 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

Status	Description
`200` `application/json`	An array of promotions
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`409` `application/json`	Waiting 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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier

Request body (required)

application/json · promotions-promotionActivation

Field	Type	Required	Description
`key`	enum<"uuid", "code">	required	Type of promotion identifier
`value`	string	required	Value of the selected identifier
`pointsToUse`	integer	optional	How many points should be converted to digital money and stored as ready to redeem in transactions in digital cashback promotions.

Responses

Status	Description
`200` `application/json`	Promotion activated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not Found
`409` `application/json`	Waiting for profile lock release
`412` `application/json`	Already activated/Already redeemed/Activation limit reached/Promotion not started/Promotion expired
`422` `application/json`	Global Activation limit reached
`423` `application/json`	Profile promotions blocked
`500`	General 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

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.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_BATCH_ACTIVATE_PROMOTIONS_UPDATE

User role permission required: campaigns_promotions: update

Parameters

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier

Request body (required)

application/json · array<promotions-promotionActivation>

Responses

Status	Description
`200` `application/json`	Promotions activated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not Found
`409` `application/json`	Waiting for profile lock release
`412` `application/json`	Already activated/Already redeemed/Activation limit reached/Promotion not started/Promotion expired
`500`	General 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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier

Request body (required)

application/json · promotions-promotionActivation

Field	Type	Required	Description
`key`	enum<"uuid", "code">	required	Type of promotion identifier
`value`	string	required	Value of the selected identifier
`pointsToUse`	integer	optional	How many points should be converted to digital money and stored as ready to redeem in transactions in digital cashback promotions.

Responses

Status	Description
`200` `application/json`	Promotion deactivated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not Found
`429` `application/json`	Waiting 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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier

Request body (required)

application/json · array<promotions-promotionActivation>

Responses

Status	Description
`200` `application/json`	Promotions deactivated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not Found
`429` `application/json`	Waiting 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

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

Field	Type	Required	Description
`visibilityStatus`	enum<"DRAFT", "PUBLISH", "HIDDEN">	optional	Profile-oriented status of the promotion.
`type`	enum<"MEMBERS_ONLY", "HANDBILL", "CUSTOM", "GENERAL">	optional	Promotion type
`redeemLimitPerClient`	integer	optional	Limit how many times a Profile can redeem this promotion.
`redeemQuantityPerActivation`	integer	optional	How many times per activation a multibuy promotion can be redeemed
`redeemLimitGlobal`	integer	optional	Limit the total of redemptions by all Profiles
`redeemType`	enum<"FULL", "PARTIAL">	optional	Promotion redemption type
`details`	object	optional	Promotion details
`discountType`	enum<"PERCENT", "POINTS", "AMOUNT", "NONE", …>	optional	The type of discount
`discountValue`	number	optional	How much discount to apply
`discountMode`	enum<"STATIC", "STEP">	optional	Promotion discount mode
`discountModeDetails`	object	optional	Applies only when `"discountMode": "STATIC"`.
`preDiscountValue`	number	optional	In 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.
`requireRedeemedPoints`	number	optional	How many loyalty points are needed to activate the promotion
`headerName`	string	optional	Name displayed in Synerise Web UI
`headerDescription`	string	optional	Description displayed in Synerise Web UI
`name`	string	optional	Promotion name displayed to viewers
`headline`	string	optional	Promotion headline displayed to viewers
`description`	string	optional	Details of the promotion displayed to viewers
`images`	array<object>	optional	Images and thumbnails for the promotion
`tags`	array<object>	optional	An 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.
`startAt`	string	optional	Time when the promotion becomes available. Defaults to current time.
`expireAt`	string	optional	Time when the promotion ends for all profiles. Defaults to current time. Has to be greater than startAt
`displayFrom`	string	optional	Time when the promotion becomes displayable. Defaults to null.
`displayTo`	string	optional	Time when the promotion stops being displayed for users. Defaults to null. Has to be greater than displayFrom.
`lastingTime`	integer	optional	Duration of the promotion in seconds. This countdown starts when the profile activates a promotion and is individual for each profile.
`params`	object	optional	A JSON object with any custom parameters of type string, object, array.
`itemScope`	enum<"LINE_ITEM", "BASKET">	optional	The 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
`minBasketValue`	number	optional	Minimal 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`.
`maxBasketValue`	number	optional	The 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.
`catalog`	string	optional	ID of the item catalog that the promotion applies to
`catalogItemType`	enum<"ALL", "SELECTED", "FILTERED">	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`.
`catalogIndexItems`	array<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.'
`catalogFilterIds`	array<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.'
`excludeCatalog`	string	optional	ID of the item catalog that the promotion should exclude
`excludeCatalogItemType`	enum<"ALL", "SELECTED", "FILTERED">	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`.
`excludeCatalogIndexItems`	array<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.'
`excludeCatalogFilterIds`	array<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.'
`activationLimitGlobalType`	enum<"RELATIVE", "LIFETIME">	optional	Promotion 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).
`activationLimitGlobalLimit`	integer	optional	Limit the total of activations by all Profiles within given time unit.
`activationLimitGlobalRelativeMinutes`	integer	optional	Used only when `type` is `RELATIVE`. Defines how many minutes back from the current time the limit applies.
`storeCatalog`	string	optional	ID of the store catalog that the promotion applies to
`storeItemType`	enum<"ALL", "SELECTED">	optional	Defines if the promotion is available for the entire store catalog or only certain stores (listed in `storeIds`).
`storeIds`	array<string>	optional	An array of stores from the store catalog where the promotion is available if `storeItemType` is set to `SELECTED`
`targetType`	enum<"ALL", "SEGMENT">	optional	If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
`targetSegment`	array<string>	optional	This field applies only when `targetType` is set to "SEGMENT".
`price`	integer	optional	In 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.
`priority`	integer	optional	Defines the priority of the promotion for display. `1` is the highest priority.
`voucherPool`	object	optional	Settings 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.
`importHash`	string	optional	Hash of the import

Responses

Status	Description
`201` `application/json`	Promotion created
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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"]},"discountedItemsCount":1},"cashbackSettings":{"exchangeRate":0.01,"limits":{"minPoints":10,"maxPoints":1000,"maxTransactionAmount":20,"maxTransactionPercentage":50}}},"discountType":"PERCENT","discountValue":0,"discountMode":"STATIC","discountModeDetails":{"discountSteps":[{"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"],"excludeCatalog":["311"],"excludeCatalogItemType":"SELECTED","excludeCatalogIndexItems":["29727276"],"excludeCatalogFilterIds":[],"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

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

Field	Type	Required	Description
`value`	string	required	Code of the promotion to delete

Responses

Status	Description
`200` `application/json`	Promotion deleted
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Profile, promotion, or related resource not found
`409` `application/json`	Waiting 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

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

Field	Type	Required	Description
`uuid`	string	optional	Unique UUIDv4.
`code`	string	optional	Unique code
`visibilityStatus`	enum<"DRAFT", "PUBLISH", "HIDDEN">	optional	Profile-oriented status of the promotion.
`type`	enum<"MEMBERS_ONLY", "HANDBILL", "CUSTOM", "GENERAL">	optional	Promotion type
`redeemLimitPerClient`	integer	optional	Limit how many times a Profile can redeem this promotion.
`redeemQuantityPerActivation`	integer	optional	How many times per activation a multibuy promotion can be redeemed
`redeemLimitGlobal`	integer	optional	Limit the total of redemptions by all Profiles
`redeemType`	enum<"FULL", "PARTIAL">	optional	Promotion redemption type
`discountType`	enum<"PERCENT", "POINTS", "AMOUNT", "NONE", …>	optional	The type of discount
`details`	object	optional	Promotion details
`discountValue`	number	optional	How much discount to apply
`discountMode`	enum<"STATIC", "STEP">	optional	Promotion discount mode
`discountModeDetails`	object	optional	Applies only when `"discountMode": "STATIC"`.
`preDiscountValue`	number	optional	In 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.
`requireRedeemedPoints`	number	optional	How many loyalty points are needed to activate the promotion
`headerName`	string	optional	Name displayed in Synerise Web UI
`headerDescription`	string	optional	Description displayed in Synerise Web UI
`name`	string	optional	Promotion name displayed to viewers
`headline`	string	optional	Promotion headline displayed to viewers
`description`	string	optional	Details of the promotion displayed to viewers
`images`	array<object>	optional	Images and thumbnails for the promotion
`tags`	array<object>	optional	An 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.
`startAt`	string	optional	Time when the promotion becomes available. Defaults to current time.
`expireAt`	string	optional	Time when the promotion ends for all profiles. Defaults to current time. Has to be greater than startAt
`displayFrom`	string	optional	Time when the promotion becomes displayable. Defaults to null.
`displayTo`	string	optional	Time when the promotion stops being displayed for users. Defaults to null. Has to be greater than displayFrom.
`lastingTime`	integer	optional	Duration of the promotion in seconds. This countdown starts when the profile activates a promotion and is individual for each profile.
`params`	object	optional	A JSON object with any custom parameters of type string, object, array.
`itemScope`	enum<"LINE_ITEM", "BASKET">	optional	The 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
`minBasketValue`	number	optional	Minimal 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`.
`maxBasketValue`	number	optional	The 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.
`catalog`	string	optional	ID of the item catalog that the promotion applies to
`catalogItemType`	enum<"ALL", "SELECTED", "FILTERED">	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`.
`catalogIndexItems`	array<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.'
`catalogFilterIds`	array<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.'
`excludeCatalog`	string	optional	ID of the item catalog that the promotion should exclude
`excludeCatalogItemType`	enum<"ALL", "SELECTED", "FILTERED">	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`.
`excludeCatalogIndexItems`	array<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.'
`excludeCatalogFilterIds`	array<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.'
`storeCatalog`	string	optional	ID of the store catalog that the promotion applies to
`storeItemType`	enum<"ALL", "SELECTED">	optional	Defines if the promotion is available for the entire store catalog or only certain stores (listed in `storeIds`).
`storeIds`	array<string>	optional	An array of stores from the store catalog where the promotion is available if `storeItemType` is set to `SELECTED`
`targetType`	enum<"ALL", "SEGMENT">	optional	If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
`targetSegment`	array<string>	optional	This field applies only when `targetType` is set to "SEGMENT".
`price`	integer	optional	In 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.
`priority`	integer	optional	Defines the priority of the promotion for display. `1` is the highest priority.
`voucherPool`	object	optional	Settings 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.
`importHash`	string	optional	Hash of the import

Responses

Status	Description
`200` `application/json`	Promotion updated
`201` `application/json`	Promotion created
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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"]},"discountedItemsCount":1},"cashbackSettings":{"exchangeRate":0.01,"limits":{"minPoints":10,"maxPoints":1000,"maxTransactionAmount":20,"maxTransactionPercentage":50}}},"discountValue":0,"discountMode":"STATIC","discountModeDetails":{"discountSteps":[{"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"],"excludeCatalog":["311"],"excludeCatalogItemType":"SELECTED","excludeCatalogIndexItems":["29727276"],"excludeCatalogFilterIds":[],"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

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

Status	Description
`200` `application/json`	Vouchers redeemed
`207` `application/json`	Some 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

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

Status	Description
`200` `application/json`	Vouchers redeemed
`207` `application/json`	Some 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

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

Field	Type	Required	Description
`data`	array<promotions-promotionImportData>	required	Array of promotion objects to import (upsert)
`extra`	object	optional	Import metadata

Responses

Status	Description
`202` `application/json`	All items accepted for processing
`207` `application/json`	Some items failed validation
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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"]},"discountedItemsCount":1},"cashbackSettings":{"exchangeRate":0.01,"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"],"excludeCatalog":"string","excludeCatalogItemType":"SELECTED","excludeCatalogIndexItems":["string"],"excludeCatalogFilterIds":["string"],"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

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

Field	Type	Required	Description
`data`	array<promotions-PromotionDeleteItem>	required	Array of objects with promotion code to delete
`extra`	object	optional	Additional metadata

Responses

Status	Description
`202` `application/json`	All items accepted for processing
`207` `application/json`	Some items failed validation
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier

Request body

application/json · promotions-processSaleReq

Field	Type	Required	Description
`operationId`	integer	required	Operation ID
`clientDateTime`	string	required	Operation's start time
`terminal`	object	required	Data about the terminal that is the transaction's source
`transactionMetric`	object	required	Metadata of the transaction
`finalValue`	string	required	The total cost of all items in the basket, after discounts, including tax
`transactionItems`	array<promotions-transactionItemWithoutGrants>	required	Array of transaction items
`transactionAdditionalItems`	array<promotions-transactionAdditionalItem>	required	Array of additional items in the transaction
`paymentsReport`	object	required	Payment information
`promotionsToActivate`	array<promotions-promotionActivationProcessSale>	optional	Array of promotions to activate during the sale process

Responses

Status	Description
`200` `application/json`	Basket processed
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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"}],"paymentsReport":{"paymentItems":[{"seqNo":0,"type":0,"name":"string","amount":"string","hashCode":"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

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.

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_SALE_PROMOTIONS_READ

User role permission required: campaigns_promotions: read

Parameters

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier

Request body

application/json · promotions-processCheckoutReq

Field	Type	Required	Description
`operationId`	integer	required	Operation ID
`clientDateTime`	string	required	Operation's start time
`terminal`	object	required	Data about the terminal that is the transaction's source
`transactionMetric`	object	required	Metadata of the transaction
`finalValue`	string	required	The total cost of all items in the basket, after discounts, including tax
`transactionItems`	array<promotions-transactionItemWithoutGrants>	required	Array of transaction items
`transactionAdditionalItems`	array<promotions-transactionAdditionalItem>	required	Array of additional items in the transaction
`paymentsReport`	object	required	Payment information

Responses

Status	Description
`200` `application/json`	POS checkout processed
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

Field	Type	Required	Description
`operationId`	integer	required	Operation ID
`clientDateTime`	string	required	Operation's start time
`terminal`	object	required	Data about the terminal that is the transaction's source
`transactionMetric`	object	required	Metadata of the transaction
`finalValue`	string	required	The total cost of all items in the basket, after discounts, including tax
`transactionItems`	array<promotions-transactionItemWithoutGrants>	required	Array of transaction items
`transactionAdditionalItems`	array<promotions-transactionAdditionalItem>	required	Array of additional items in the transaction
`paymentsReport`	object	required	Payment information
`promotionsToActivate`	array<promotions-promotionActivationProcessSale>	optional	Array of promotions to activate during the sale process

Responses

Status	Description
`200` `application/json`	Basket processed
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`428` `application/json`	Property 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"}],"paymentsReport":{"paymentItems":[{"seqNo":0,"type":0,"name":"string","amount":"string","hashCode":"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

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

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

Field	Type	Required	Description
`operationId`	integer	required	Operation ID
`clientDateTime`	string	required	Operation's start time
`terminal`	object	required	Data about the terminal that is the transaction's source
`transactionMetric`	object	required	Metadata of the transaction
`finalValue`	string	required	The total cost of all items in the basket, after discounts, including tax
`transactionItems`	array<promotions-transactionItemWithoutGrants>	required	Array of transaction items
`transactionAdditionalItems`	array<promotions-transactionAdditionalItem>	required	Array of additional items in the transaction
`paymentsReport`	object	required	Payment information

Responses

Status	Description
`200` `application/json`	POS checkout processed
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

Name	In	Type	Required
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body (required)

application/json · vouchers-voucherActionRequestAsClientReq

Field	Type	Required	Description
`poolUuid`	string	required	UUID of the voucher pool
`clientUuid`	string	optional	UUID of the Profile. This field is ignored.

Responses

Status	Description
`201` `application/json`	Code assigned
`416` `application/json`	Range 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

Retrieve all vouchers assigned to a Profile.

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

User role permission required: assets_code_pool: read

Parameters

Name	In	Type	Required
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Responses

Status	Description
`200` `application/json`	An 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

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

Name	In	Type	Required
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body (required)

application/json · vouchers-voucherActionRequestAsClientReq

Field	Type	Required	Description
`poolUuid`	string	required	UUID of the voucher pool
`clientUuid`	string	optional	UUID of the Profile. This field is ignored.

Responses

Status	Description
`200` `application/json`	Details of the code
`416` `application/json`	Range 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

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

Name	In	Type	Required
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body (required)

application/json · vouchers-voucherData

Field	Type	Required	Description
`poolUuid`	string	required	UUID of the voucher pool
`clientUuid`	string	optional	UUID of the Profile
`clientId`	integer	optional	ID of the Profile
`code`	string	optional	Voucher code Must match the pattern: `^.{0,36}$`
`expireIn`	string	optional	Date when the voucher expires.
`redeemAt`	string	optional	Time when the voucher was redeemed. Defaults to current time when redeeming.
`assignedAt`	string	optional	Time when the voucher was assigned. Defaults to current time when assigning.
`status`	enum<"ASSIGNED", "UNASSIGNED", "REDEEMED", "CANCELED">	optional	Voucher status
`createdAt`	string	optional	Time when the voucher was created.
`updatedAt`	string	optional	Time when the voucher was last updated.

Responses

Status	Description
`201` `application/json`	Voucher 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

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

Name	In	Type	Required
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body

application/json · vouchers-bulkCreateVouchersReq

Field	Type	Required	Description
`poolUuid`	string	required	UUID of the voucher pool
`codeList`	string	required	A list of unique voucher codes, separated by semicolons

Responses

Status	Description
`201` `application/json`	Vouchers created
`400` `application/json`	Bad 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

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

Name	In	Type	Required	Description
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`includeMeta`	query	boolean	optional	When `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

Status	Description
`200` `application/json`	An 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

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

Name	In	Type	Required	Description
`voucherUuid`	path	string	required	UUID of the voucher
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Responses

Status	Description
`200` `application/json`	Details 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

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

Name	In	Type	Required	Description
`voucherUuid`	path	string	required	UUID of the voucher
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body (required)

application/json · vouchers-voucherData

Field	Type	Required	Description
`poolUuid`	string	required	UUID of the voucher pool
`clientUuid`	string	optional	UUID of the Profile
`clientId`	integer	optional	ID of the Profile
`code`	string	optional	Voucher code Must match the pattern: `^.{0,36}$`
`expireIn`	string	optional	Date when the voucher expires.
`redeemAt`	string	optional	Time when the voucher was redeemed. Defaults to current time when redeeming.
`assignedAt`	string	optional	Time when the voucher was assigned. Defaults to current time when assigning.
`status`	enum<"ASSIGNED", "UNASSIGNED", "REDEEMED", "CANCELED">	optional	Voucher status
`createdAt`	string	optional	Time when the voucher was created.
`updatedAt`	string	optional	Time when the voucher was last updated.

Responses

Status	Description
`200` `application/json`
`400` `application/json`	Bad 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

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

Name	In	Type	Required	Description
`voucherUuid`	path	string	required	UUID of the voucher
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Responses

Status	Description
`200` `application/json`	Voucher 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

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

Name	In	Type	Required	Description
`searchKey`	path	enum<"code", "uuid">	required	The key type to search by
`searchValue`	path	string	required	The value to search for
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Responses

Status	Description
`200` `application/json`	Details 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

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

Name	In	Type	Required
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body (required)

application/json · vouchers-voucherActionRequestAsProfileReq

Field	Type	Required	Description
`poolUuid`	string	required	UUID of the voucher pool
`clientUuid`	string	required	UUID of the Profile

Responses

Status	Description
`201` `application/json`	Voucher assigned
`416` `application/json`	Pool 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

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

Name	In	Type	Required	Description
`clientUuid`	path	string	required	UUID of the Profile
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Responses

Status	Description
`200` `application/json`	An 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

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

Name	In	Type	Required
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body (required)

application/json · vouchers-voucherActionRequestAsProfileReq

Field	Type	Required	Description
`poolUuid`	string	required	UUID of the voucher pool
`clientUuid`	string	required	UUID of the Profile

Responses

Status	Description
`200` `application/json`	Details of a voucher
`416` `application/json`	Pool 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

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

Name	In	Type	Required	Description
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required
`clientIdentifierName`	query	enum<"id", "uuid", "email", "custom_identify">	required	The Profile identifier to use for the request.
`clientIdentifierValue`	query	string	required	The value of the selected profile identifier

Responses

Status	Description
`200` `application/json`	An array of vouchers
`400` `application/json`	Bad Request
`416` `application/json`	Invalid 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

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

Name	In	Type	Required	Description
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required
`clientIdentifierName`	query	enum<"id", "uuid", "email", "custom_identify">	required	The Profile identifier to use for the request.

Request body (required)

application/json · vouchers-voucherActionRequestByClientIdentifierAsProfileReq

Field	Type	Required	Description
`poolUuid`	string	required	UUID of the voucher pool
`clientIdentifierValue`		required	Value of the profile identifier. For example `clientIdentifierValue=custom_identify_1234`

Responses

Status	Description
`200` `application/json`	Details of a voucher
`416` `application/json`	Pool 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

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

Name	In	Type	Required	Description
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required
`clientIdentifierName`	query	enum<"id", "uuid", "email", "custom_identify">	required	The Profile identifier to use for the request.

Request body (required)

application/json · vouchers-voucherActionRequestByClientIdentifierAsProfileReq

Field	Type	Required	Description
`poolUuid`	string	required	UUID of the voucher pool
`clientIdentifierValue`		required	Value of the profile identifier. For example `clientIdentifierValue=custom_identify_1234`

Responses

Status	Description
`201` `application/json`	Voucher assigned
`416` `application/json`	Pool 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

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

Name	In	Type	Required
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body (required)

application/json · vouchers-voucherRedeemReq

Field	Type	Required	Description
`code`	string	required	Voucher code Must match the pattern: `^.{0,36}$`

Responses

Status	Description
`200` `application/json`	Voucher redeemed
`400` `application/json`	Data 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

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

Name	In	Type	Required	Description
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required
`includeMeta`	query	boolean	optional	When `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
`orderFieldName`	query	enum<"name", "poolLimit", "startAt", "expireIn", …>	optional	Name of the parameter used for sorting. If you include this parameter, you must also send the `order` parameter.
`order`	query	enum<"asc", "desc">	optional	Sorting order. If you include this parameter, you must also send the `orderFieldName` parameter.
`query`	query	string	optional	Filter by phrase in pool name.
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.

Responses

Status	Description
`200` `application/json`	An 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

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

Name	In	Type	Required
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body (required)

application/json · vouchers-createAVoucherPoolReq

Field	Type	Required	Description
`name`	string	required	Name of the voucher pool
`barcodeType`	enum<"NONE", "UPC", "EAN-13", "CODE-39", …>	optional	The type of codes in the pool
`description`	string	optional	A description of the pool
`voucherPrefix`	string	optional	A prefix added to each voucher in the pool
`poolLimit`	integer	optional	Maximum number of vouchers to store in the pool
`redeemedLimitPerClient`	integer	optional	Maximum number of times that one Profile can retrieve a voucher from this pool
`startAt`	string	optional	Time when the pool starts functioning. Defaults to current time.

Responses

Status	Description
`201` `application/json`	Pool 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","barcodeType":"NONE","description":"string","voucherPrefix":"0","poolLimit":0,"redeemedLimitPerClient":0,"startAt":"2019-08-24T14:15:22Z"}'

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

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

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

Name	In	Type	Required	Description
`poolUuid`	path	string	required	UUID of the voucher pool
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Responses

Status	Description
`200` `application/json`	Details 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

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

Name	In	Type	Required	Description
`poolUuid`	path	string	required	UUID of the voucher pool
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Request body (required)

application/json · vouchers-createAVoucherPoolReq

Field	Type	Required	Description
`name`	string	required	Name of the voucher pool
`barcodeType`	enum<"NONE", "UPC", "EAN-13", "CODE-39", …>	optional	The type of codes in the pool
`description`	string	optional	A description of the pool
`voucherPrefix`	string	optional	A prefix added to each voucher in the pool
`poolLimit`	integer	optional	Maximum number of vouchers to store in the pool
`redeemedLimitPerClient`	integer	optional	Maximum number of times that one Profile can retrieve a voucher from this pool
`startAt`	string	optional	Time when the pool starts functioning. Defaults to current time.

Responses

Status	Description
`200` `application/json`	Voucher 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","barcodeType":"NONE","description":"string","voucherPrefix":"0","poolLimit":0,"redeemedLimitPerClient":0,"startAt":"2019-08-24T14:15:22Z"}'

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

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

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

Name	In	Type	Required	Description
`poolUuid`	path	string	required	UUID of the voucher pool
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Responses

Status	Description
`200` `application/json`	Voucher 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

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

Name	In	Type	Required	Description
`poolUuid`	path	string	required	UUID of the voucher pool
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`includeMeta`	query	boolean	optional	When `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

Status	Description
`200` `application/json`	An 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

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

Name	In	Type	Required	Description
`poolUuid`	path	string	required	UUID of the voucher pool
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Responses

Status	Description
`200` `application/json`	Vouchers 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

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

Name	In	Type	Required	Description
`poolUuid`	path	string	required	UUID of the voucher pool
`Accept`	header	enum<"application/json">	required
`Content-Type`	header	enum<"application/json">	required
`Api-Version`	header	enum<"4.4", "4.2">	required

Responses

Status	Description
`200` `application/json`	Set 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

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

Name	In	Type	Required	Description
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`sort`	query	string	optional	The 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."
`includeMeta`	query	boolean	optional	When `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

Status	Description
`200` `application/json`	List of handbill configurations
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

Field	Type	Required	Description
`channel`	enum<"MOBILE", "CHECK_OUT", "CHECK_IN">	required	Channel 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.
`status`	enum<"DRAFT", "ACTIVE", "INACTIVE">	required	Status of the handbill
`name`	string	required	Name of the handbill configuration
`description`	string	required	Description of the handbill configuration
`controlGroup`	object	required	Details 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.
`variants`	array<object>	required	Variants of the handbill configuration. If you do not want to use variants, send an empty array.

Responses

Status	Description
`200` `application/json`	Configuration created
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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":0},"variants":[{"name":"string","uuid":"095be615-a8ad-4c33-8e9c-c7612fbf6c9f","percentage":0,"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"}},"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":";"},"filterIds":["497f6eca-6276-4993-bfeb-53cbbbba6f08"],"types":["MEMBERS_ONLY","HANDBILL"],"excludeByAvailableProducts":true,"slotFilters":{"order":"GIVEN","slots":[{"filterId":"aff0ee0f-f371-4b82-82c6-dc3b96f05c91","limit":5}]}}]}'

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

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

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

Name	In	Type	Required	Description
`handbillUuid`	path	string	required	UUID of the handbill configuration

Responses

Status	Description
`200` `application/json`	Handbill configuration
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

Name	In	Type	Required	Description
`handbillUuid`	path	string	required	UUID of the handbill configuration

Request body

application/json · promotions-handbillConfigUpdateRequest

Field	Type	Required	Description
`channel`	enum<"MOBILE", "CHECK_OUT", "CHECK_IN">	optional	Channel 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.
`status`	enum<"DRAFT", "ACTIVE", "INACTIVE">	optional	Status of the handbill
`name`	string	optional	Name of the handbill configuration
`description`	string	optional	Description of the handbill configuration
`controlGroup`	object	optional	Details 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.
`variants`	array<object>	optional	Variants of the handbill configuration. If you do not want to use variants, send an empty array.

Responses

Status	Description
`200` `application/json`	Configuration updated
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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":0},"variants":[{"name":"string","uuid":"095be615-a8ad-4c33-8e9c-c7612fbf6c9f","percentage":0,"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"}},"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":";"},"filterIds":["497f6eca-6276-4993-bfeb-53cbbbba6f08"],"types":["MEMBERS_ONLY","HANDBILL"],"excludeByAvailableProducts":true,"slotFilters":{"order":"GIVEN","slots":[{"filterId":"aff0ee0f-f371-4b82-82c6-dc3b96f05c91","limit":5}]}}]}'

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

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

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 or HIDDEN 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.
- When using AI engine, the promotion candidate list is sorted by priority and truncated to 2500 items before applying the recommendation engine.

API consumers: Profile (Client), Anonymous Profile

Parameters

Name	In	Type	Required	Description
`handbillUuid`	path	string	required	UUID of the handbill configuration
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`fields`	query	array<enum<"uuid", "code", "status", "type", …>>	optional	Return only specified promotion fields. If `fields` is not specified, all fields are returned.

Responses

Status	Description
`200` `application/json`	A list of handbill-type promotions assigned to this profile
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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 or HIDDEN 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.
- When using AI engine, the promotion candidate list is sorted by priority and truncated to 2500 items before applying the recommendation engine.

API consumers: Profile (Client), Anonymous Profile

Parameters

Name	In	Type	Required	Description
`handbillUuid`	query	array<string>	required
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`limit`	query	integer	optional	The number of items to return per page
`includeMeta`	query	boolean	optional	When `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
`fields`	query	array<enum<"uuid", "code", "status", "type", …>>	optional	Return only specified promotion fields. If `fields` is not specified, all fields are returned.

Responses

Status	Description
`200` `application/json`	A list of handbill-type promotions assigned to this profile
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

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 or HIDDEN 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.
- When using AI engine, the promotion candidate list is sorted by priority and truncated to 2500 items before applying the recommendation engine.

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier
`handbillUuid`	path	string	required	UUID of the handbill configuration
`type`	query	array<enum<"GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL">>	optional	Promotion type
`status`	query	array<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>	optional	Filter by promotion status
`visibilityStatus`	query	array<enum<"DRAFT", "PUBLISH", "HIDDEN">>	optional	Visibility status
`tagNames`	query	array<string>	optional	Filter the response to promotions with a certain tag or tags
`target`	query	array<enum<"ALL", "SEGMENT">>	optional	The target of the promotion
`presentOnly`	query	boolean	optional	When 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.
`lastingOnly`	query	boolean	optional	When set to `true`, shows promotions/vouchers that are currently active and those that are still inactivated. (lastingAt set to null or lastingAt in future)
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`limit`	query	integer	optional	The number of items to return per page
`sort`	query	string	optional	The 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."
`includeMeta`	query	boolean	optional	When `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
`fields`	query	array<enum<"uuid", "code", "status", "type", …>>	optional	Return only specified promotion fields. If `fields` is not specified, all fields are returned.

Responses

Status	Description
`200` `application/json`	A list of promotions assigned to this profile
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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 or HIDDEN 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.
- When using AI engine, the promotion candidate list is sorted by priority and truncated to 2500 items before applying the recommendation engine.

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier
`handbillUuid`	path	string	required	UUID of the handbill configuration
`limit`	query	integer	optional	The number of items to return per page
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.

Responses

Status	Description
`200` `application/json`	A list of handbill-type promotions assigned to this profile
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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 or HIDDEN 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.
- When using AI engine, the promotion candidate list is sorted by priority and truncated to 2500 items before applying the recommendation engine.

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

Name	In	Type	Required	Description
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier
`handbillUuid`	query	array<string>	required
`type`	query	array<enum<"GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL">>	optional	Promotion type
`page`	query	integer	optional	Page number to return for pagination. The first page has the index `1`.
`limit`	query	integer	optional	The number of items to return per page
`includeMeta`	query	boolean	optional	When `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
`status`	query	array<enum<"ACTIVE", "ASSIGNED", "REDEEMED">>	optional	Filter by promotion status
`fields`	query	array<enum<"uuid", "code", "status", "type", …>>	optional	Return only specified promotion fields. If `fields` is not specified, all fields are returned.

Responses

Status	Description
`200` `application/json`	A list of promotions assigned to this profile
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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'

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

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

Name	In	Type	Required	Description
`feedSlug`	path	string	required	Slug of the screen view feed

Responses

Status	Description
`200` `application/json`	Processed JSON content
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`feedSlug`	path	string	required	Slug of the screen view feed

Request body

application/json · object

Responses

Status	Description
`200` `application/json`	Processed JSON content
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

Create a screen view.

API consumer: Synerise User

User role permission required: assets_docs: create

Request body

application/json · schema-service-CreateScreenViewRequest

Field	Type	Required	Description
`priority`	integer	required	Priority 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.
`name`	string	optional	Name of the screen view
`directoryId`	string	required	UUID 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.
`content`	object	required	Content of the screen view
`audience`	object	required	The profiles (clients) which have access to this resource
`schedule`	object	optional	Configuration of the schedule
`feedId`	string	required	UUID of the feed where this screen view is assigned.

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Field	Type	Required	Description
`name`	string	optional	If no name is provided, defaults to "Unnamed document" or Screen View Campaign" (depending on what you are initializing).
`directory`	string	optional	If no directory is provided, the default directory is used.

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Request body

application/json · schema-service-ScreenViewContent

Field	Type	Required	Description
`json`	object	required	JSON 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%}`.
`documents`	array<string>	required	An array of documents. If `groups` is used, this array must be empty.
`data`	array<any>	optional	An array of documents or Brickworks records
`groups`	array<schema-service-DocumentGroupId>	required	An array of document groups, If `documents` is used, this array must be empty.
`groupsOrder`	boolean	optional	By 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

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Request body

application/json · schema-service-Audience

Field	Type	Required	Description
`targetType`	enum<"SEGMENT", "QUERY", "ALL">	required	The 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
`segments`	array<string>	optional	An array of segmentation IDs. Used with `targetType: SEGMENT`
`query`	string	optional	Stringified `analysis` object for the segmentation analytics engine. Used with `targetType: QUERY`. Refer to the Analytics API Reference.

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Request body

application/json · schema-service-screenViewPriority

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Request body (required)

application/json · string

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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:

POST /v3/screen-views/{feedSlug}/generate
GET /v3/screen-views/{feedSlug}/generate

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

Name	In	Type	Required	Description
`feedSlug`	path	string	required	Slug of the screen view feed
`identifierType`	path	enum<"id", "uuid", "email", "custom_identify">	required	Type of the profile identifier. The value is sent in `identifierValue` in the request body.

Request body

application/json · object

Field	Type	Required	Description
`identifierValue`	string	required	Value of the profile identifier selected in `identifierType` (profile ID is sent as a string)
`params`	object	optional	Additional parameters

Responses

Status	Description
`200` `application/json`	Processed JSON content
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Status	Description
`200` `application/json`	List of feeds
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Field	Type	Required	Description
`slug`	string	required	Unique slug of the screen view feed
`name`	string	required	Name of the screen view feed

Responses

Status	Description
`200` `application/json`	Feed created
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`page`	query	number	optional
`limit`	query	number	optional	Limit of items per page
`search`	query	string	optional	A string to search for in resource names
`directoryId`	query	string	optional	UUID of the directory for filtering the results
`status`	query	enum<"DRAFT", "ACTIVE", "SCHEDULED", "PAUSED", …>	optional
`feedId`	query	string	optional

Responses

Status	Description
`200` `application/json`	List of screen views
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Details of the screen view
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Screen view deleted
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Data of the created copy
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Entities which refer to the requested screen view
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Documents referenced from the requested screen view
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Status	Description
`200` `application/json`	List of directories
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Field	Type	Required	Description
`name`	string	required	Name of the directory

Responses

Status	Description
`200` `application/json`	Directory created
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`directoryId`	path	string	required	UUID of the directory

Request body

application/json · object

Field	Type	Required	Description
`name`	string	required

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`directoryId`	path	string	required	UUID of the directory

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`directoryId`	path	string	required	UUID of the directory

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Request body

application/json · string

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`feedId`	path	string	required	UUID of a screen view feed

Request body

application/json · object

Field	Type	Required	Description
`name`	string	required	New name of the feed

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`feedId`	path	string	required	UUID of a screen view feed

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Field	Type	Required	Description
`externalId`	string	optional	UUID of the screen view or document that the schedule applies to
`type`	enum<"SCREENVIEW", "DOCUMENT">	optional	Type of the scheduled object
`schedule`	object	optional	Configuration of the schedule

Responses

Status	Description
`200` `application/json`	Schedule added
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`objectId`	path	string	required	Screen view or document ID
`objectType`	path	enum<"SCREENVIEW", "DOCUMENT">	required	Object type

Responses

Status	Description
`200` `application/json`	Schedule details
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	Object 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Field	Type	Required	Description
`pointsAmount`	integer	required	How many points to send
`recipient`	object	required	Identifier of the recipient
`sender`	object	optional	Information about the sender
`message`	string	optional	A message that the recipient will receive with the points

Responses

Status	Description
`202` `application/json`	Point transfer scheduled
`400` `application/json`	Bad request
`404` `application/json`	Profile not found
`422` `application/json`	Unprocessable point transfer
`423` `application/json`	Profile 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

API consumers: Workspace (Business Profile), Synerise User

API key permission required: PROMOTIONS_SETTINGS_PROMOTIONS_READ

User role permission required: campaigns_personalised_promotions: read

Responses

Status	Description
`200` `application/json`	OK
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

Example request (cURL)

curl --request GET \
  --url https://api.synerise.com/v4/promotions/settings

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

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

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

Field	Type	Required	Description
`checkoutSettings`	object	optional	Handbill checkout settings
`enableCodeGeneration`	boolean	optional	Flag which indicates if promotion code should be generated as ordinal number prefixed with prefix defined in `codePrefix`
`codePrefix`	string	optional	Prefix which will be added to promotion code, when `enableCodeGeneration` is set to true
`blockTag`	string	optional	Tag name which marks a profile as blocked. Blocked profiles do not receive promotions in POS methods and are not allowed to activate new promotions.
`expression`	string	optional	Expression UUID which will be used to count the balance of loyalty points in the promotion activation endpoint.
`promotionListSettings`	object	optional	Filter for promotions in `/promotion/get-for-client-by-custom-settings/{identifierType}/{identifierValue}` method
`promotionAssignmentSettings`	object	optional	Filter for promotions in `/promotion/get-for-client/{identifierType}/{identifierValue}/handbill/{handbillUuid}` method
`restorePointsOnProfileDeactivation`	boolean	optional	When 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.
`allowRedeemCompletionWhenBlocked`	boolean	optional	When set to `true`, the profile can complete the redemption of promotions that had been activated before a lock was put on that profile.
`saleSettings`	object	optional	Settings for sales
`lockSettings`	object	optional	Settings for locks
`transferSettings`	array<object>	optional	Settings for point transfers
`cashbackSettings`	object	optional	Settings for cashback mechanism

Responses

Status	Description
`200` `application/json`	OK
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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"}],"forPaginator":"DISCOUNT_VALUE"},"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"}],"forPaginator":"DISCOUNT_VALUE"},"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":null,"processSalePromotionActivationLockWaitTime":null,"lockPromotionRequestByIdentifier":true},"transferSettings":[{"expression":"2395fc33-f2f0-420c-8e7b-0ac63c3454de","recipient":{"segments":["string"]},"sender":{"segments":["string"]}}],"cashbackSettings":{"exchangeRate":0.01,"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

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

Status	Description
`200` `application/json`	Information about Profile lock
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden

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

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

Name	In	Type	Required	Description
`lockTtlSec`	query	number	optional	Lock duration in seconds
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier

Responses

Status	Description
`200` `application/json`	Lock created
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Profile 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

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

Name	In	Type	Required	Description
`lockIdentifier`	path	string	required	Lock identifier
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier

Responses

Status	Description
`200` `application/json`	Lock released
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Profile not found
`409` `application/json`	Lock 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

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

Name	In	Type	Required	Description
`lockIdentifier`	path	string	required	Lock identifier
`identifierType`	path	enum<"email", "phone", "externalId", "uuid", …>	required	The Profile identifier to use for the request. `externalId` is known as `customId` or `custom_identify` in other Synerise services.
`identifierValue`	path	string	required	The value of the selected identifier

Responses

Status	Description
`200` `application/json`	Lock released
`400` `application/json`	Request body invalid/malformed/missing elements
`401` `application/json`	Unauthorized
`403` `application/json`	Forbidden
`404` `application/json`	Not 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

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

Name	In	Type	Required	Description
`limit`	query	string	required	The maximum number of items to retrieve for pagination
`page`	query	integer	required	The number of the page to retrieve
`status`	query	enum<"DRAFT", "ACTIVE", "SCHEDULED", "PAUSED", …>	optional	Filter the results by screen view status

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`screenViewVersion`	path	string	required	Version of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`limit`	query	string	required	The maximum number of items to retrieve for pagination
`page`	query	integer	required	The number of the page to retrieve

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Status	Description
`200` `application/json`	Processed JSON content
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Status	Description
`200` `application/json`	Processed JSON content
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`screenViewVersion`	path	string	required	Version of the screen view

Request body

application/json · schema-service-versionedScreenViewKey

Field	Type	Required	Description
`screenViewId`	string	optional	UUID of the screen view
`screenViewVersion`	string	optional	Version of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

Add content to a screen view draft.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`screenViewVersion`	path	string	required	Version of the screen view

Request body

application/json · schema-service-ScreenViewContent

Field	Type	Required	Description
`json`	object	required	JSON 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%}`.
`documents`	array<string>	required	An array of documents. If `groups` is used, this array must be empty.
`data`	array<any>	optional	An array of documents or Brickworks records
`groups`	array<schema-service-DocumentGroupId>	required	An array of document groups, If `documents` is used, this array must be empty.
`groupsOrder`	boolean	optional	By 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

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

Define the audience for a screen view draft.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`screenViewVersion`	path	string	required	Version of the screen view

Request body

application/json · schema-service-Audience

Field	Type	Required	Description
`targetType`	enum<"SEGMENT", "QUERY", "ALL">	required	The 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
`segments`	array<string>	optional	An array of segmentation IDs. Used with `targetType: SEGMENT`
`query`	string	optional	Stringified `analysis` object for the segmentation analytics engine. Used with `targetType: QUERY`. Refer to the Analytics API Reference.

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

Make the screen view accessible to customers.

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`screenViewVersion`	path	string	required	Version of the screen view

Request body

application/json · schema-service-publishRequest

Field	Type	Required	Description
`overwrite`	boolean	required	Currently unused

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Field	Type	Required	Description
`screenViewId`	string	optional	UUID of the screen view
`screenViewVersion`	string	optional	Version of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Field	Type	Required	Description
`screenViewId`	string	optional	UUID of the screen view
`screenViewVersion`	string	optional	Version of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`screenViewVersion`	path	string	required	Version of the screen view

Request body

application/json · string

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`screenViewVersion`	path	string	required	Version of the screen view

Request body (required)

application/json · integer

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

API consumer: Synerise User

User role permission required: assets_docs: create

Parameters

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`screenViewVersion`	path	string	required	Version of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

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

API consumer: Synerise User

User role permission required: assets_docs: delete

Parameters

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

Delete a version of a screen view.

API consumer: Synerise User

User role permission required: assets_docs: delete

Parameters

Name	In	Type	Required	Description
`screenViewId`	path	string	required	UUID of the screen view
`screenViewVersion`	path	string	required	Version of the screen view

Responses

Status	Description
`200` `application/json`	Success
`400` `application/json`	See error message for details
`401` `application/json`	Unauthorized: wrong consumer scope; token missing/expired/invalid; invalid API key; etc.
`403` `application/json`	Forbidden; insufficient permissions
`404` `application/json`	Resource not found
`500` `application/json`	See 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

Loyalty and Engagement — API Reference

Promotions

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

Parameters

Responses

Example request (cURL)

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

Request body (required)

Responses

Example request (cURL)

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

Request body (required)

Responses

Example request (cURL)

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

Request body (required)

Responses

Example request (cURL)

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

Request body (required)

Responses

Example request (cURL)

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

Request body (required)

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Request body (required)

Responses

Example request (cURL)

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

Request body (required)

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

Parameters

Request body (required)

Responses

Example request (cURL)

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

Parameters

Responses

Example request (cURL)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`POST` `/v4/promotions/promotion` — Create a promotion

`DELETE` `/v4/promotions/promotion` — Delete a promotion

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

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

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

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

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

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

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

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