# Get settings for current Workspace
- Operation ID: `endpointSettingsGetSettingsGET`
- HTTP method: `GET`
- Path: `/v4/promotions/settings`
- [Human-readable API reference](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotion-settings/operation/endpointSettingsGetSettingsGET)
## Self-contained OpenAPI method
The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.
```yaml
openapi: 3.0.0
info:
title: Synerise Public API
version: 1.9.1
paths:
/v4/promotions/settings:
get:
tags:
- Promotion settings
summary: Get settings for current Workspace
operationId: endpointSettingsGetSettingsGET
parameters:
- in: query
name: only
required: false
description: |
Return only the settings property at this dotted path (e.g. `saleSettings.discountOrder.strategy`) instead of the whole settings object. Responds with 404 when the property is not defined.
schema:
type: string
pattern: ^[A-Za-z0-9]+(\.[A-Za-z0-9]+)*$
example: saleSettings.combineBasketDiscounts
- in: query
name: withDefaults
required: false
description: |
When true, missing values are filled from the server-side defaults before the response is built. Combined with `only`, a property that has a configured default resolves even when the Workspace has not stored it; a property without a default still responds with 404.
schema:
type: boolean
default: false
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
checkoutSettings:
type: object
description: Handbill checkout settings
nullable: true
properties:
handbillUuidsForCheckout:
type: array
description: Handbill UUIDs to use for checkout couponing
nullable: true
items:
type: string
format: uuid
codeGeneration:
type: object
description: Checkout code generation options
nullable: true
properties:
prefix:
type: string
description: Prefix added to each code
length:
type: integer
default: 36
description: Length of the random code to generate
crc:
type: boolean
description: When `true`, a CRC string is added to the end of the code
enableCodeGeneration:
type: boolean
description: Flag which indicates if promotion code should be generated as ordinal number prefixed with prefix defined in `codePrefix`
nullable: true
example: true
codePrefix:
type: string
description: Prefix which will be added to promotion code, when `enableCodeGeneration` is set to true
nullable: true
example: SYN
blockTag:
type: string
description: 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.
nullable: true
example: BLOCKED
expression:
type: string
nullable: true
format: uuid
description: Expression UUID which will be used to count the balance of loyalty points in the promotion activation endpoint.
promotionListSettings:
type: object
nullable: true
description: Filter for promotions in [`/promotion/get-for-client-by-custom-settings/{identifierType}/{identifierValue}`](#operation/GetClientPromotionsByACustomFilter) method
allOf:
- type: object
properties:
setFieldsValues:
type: object
deprecated: true
description: Set values on promotions when returning list to profile
where:
type: object
description: Promotion filter
properties:
excludeIds:
type: array
description: IDs of promotions to exclude from the list
nullable: true
items:
type: integer
example: 3
handbillPromotionIds:
type: array
description: Handbill promotion IDs to include
nullable: true
items:
type: integer
example: 3
visibilityStatus:
type: array
description: Filter by visibility status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- DRAFT
- PUBLISH
- HIDDEN
default: DRAFT
status:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
statusByType:
type: object
description: Filter by a combination of promotion type and status
properties:
GENERAL:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
CUSTOM:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
MEMBERS_ONLY:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
HANDBILL:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
target:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
targetByType:
type: object
description: Filter by a combination of promotion type and target
properties:
GENERAL:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
CUSTOM:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
MEMBERS_ONLY:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
HANDBILL:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
type:
type: array
description: Filter by promotion type
nullable: true
items:
type: string
description: Promotion type
enum:
- MEMBERS_ONLY
- HANDBILL
- CUSTOM
- GENERAL
default: GENERAL
presentOnly:
description: When set to `false`, expired promotions are included in the response.
type: boolean
nullable: true
default: true
lastingOnly:
description: When set to `true`, filters to promotions that are currently active and those that were not yet activated.
type: boolean
nullable: true
default: true
displayableOnly:
description: When set to `true`, filters to promotions that are currently configured to be displayed (by `displayFrom` and `displayTo` dates).
type: boolean
nullable: true
default: true
checkExistsInTarget:
nullable: true
type: boolean
default: true
description: When set to `true`, the profile must exist within the target segmentation.
tagNames:
type: array
description: Promotion filter by promotion tags
nullable: true
items:
type: string
fields:
type: array
description: Fields to be returned in the promotion object
nullable: true
items:
type: string
sort:
type: object
nullable: true
description: Promotion sorting settings
properties:
forDBQuery:
type: array
description: Sorting options for database queries (sort all promotions matched by the filter)
items:
type: object
properties:
field:
type: string
description: Field name to sort by
enum:
- headerName
- name
- code
- startAt
- createdAt
- updatedAt
- expireAt
- requireRedeemedPoints
- type
- priority
- status
direction:
type: string
description: Sorting direction
enum:
- asc
- desc
page:
type: number
description: Page number to return for pagination. The first page has the index `1`.
limit:
type: number
description: The number of items to return per page
promotionAssignmentSettings:
type: object
nullable: true
description: |
Filter for promotions in the [`/promotion/get-for-client/{identifierType}/{identifierValue}/handbill/{handbillUuid}`](#operation/getAssignHandbillForClient_GET) and `/promotion/get-for-client/{identifierType}/{identifierValue}/with-handbills` methods.
For `where` fields not defined in the stored settings, the following defaults apply: `target: ["ALL", "SEGMENT"]`, `visibilityStatus: ["PUBLISH"]`, `type: ["GENERAL", "CUSTOM", "MEMBERS_ONLY", "HANDBILL"]`, `presentOnly: true`, `lastingOnly: true`, `displayOnly: false`. Precedence (lowest to highest): defaults, stored settings, request query parameters.
allOf:
- type: object
properties:
setFieldsValues:
type: object
deprecated: true
description: Set values on promotions when returning list to profile
where:
type: object
description: Promotion filter
properties:
excludeIds:
type: array
description: IDs of promotions to exclude from the list
nullable: true
items:
type: integer
example: 3
handbillPromotionIds:
type: array
description: Handbill promotion IDs to include
nullable: true
items:
type: integer
example: 3
visibilityStatus:
type: array
description: Filter by visibility status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- DRAFT
- PUBLISH
- HIDDEN
default: DRAFT
status:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
statusByType:
type: object
description: Filter by a combination of promotion type and status
properties:
GENERAL:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
CUSTOM:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
MEMBERS_ONLY:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
HANDBILL:
type: array
description: Promotion filter by assignment status
nullable: true
items:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
target:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
targetByType:
type: object
description: Filter by a combination of promotion type and target
properties:
GENERAL:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
CUSTOM:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
MEMBERS_ONLY:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
HANDBILL:
type: array
description: Promotion filter by target type
nullable: true
items:
type: string
description: If this field is set to "SEGMENT", you must provide a list of segments in `targetSegment`.
default: ALL
enum:
- ALL
- SEGMENT
type:
type: array
description: Filter by promotion type
nullable: true
items:
type: string
description: Promotion type
enum:
- MEMBERS_ONLY
- HANDBILL
- CUSTOM
- GENERAL
default: GENERAL
presentOnly:
description: When set to `false`, expired promotions are included in the response.
type: boolean
nullable: true
default: true
lastingOnly:
description: When set to `true`, filters to promotions that are currently active and those that were not yet activated.
type: boolean
nullable: true
default: true
displayableOnly:
description: When set to `true`, filters to promotions that are currently configured to be displayed (by `displayFrom` and `displayTo` dates).
type: boolean
nullable: true
default: true
checkExistsInTarget:
nullable: true
type: boolean
default: true
description: When set to `true`, the profile must exist within the target segmentation.
tagNames:
type: array
description: Promotion filter by promotion tags
nullable: true
items:
type: string
fields:
type: array
description: Fields to be returned in the promotion object
nullable: true
items:
type: string
sort:
type: object
nullable: true
description: Promotion sorting settings
properties:
forDBQuery:
type: array
description: Sorting options for database queries (sort all promotions matched by the filter)
items:
type: object
properties:
field:
type: string
description: Field name to sort by
enum:
- headerName
- name
- code
- startAt
- createdAt
- updatedAt
- expireAt
- requireRedeemedPoints
- type
- priority
- status
direction:
type: string
description: Sorting direction
enum:
- asc
- desc
page:
type: number
description: Page number to return for pagination. The first page has the index `1`.
limit:
type: number
description: The number of items to return per page
restorePointsOnProfileDeactivation:
type: boolean
description: When set to `true` and you use the method which [deactivates all promotions for a profile](#operation/deactivateAllPromotions), the points taken for activation of the promotion will be restored.
nullable: true
default: true
allowRedeemCompletionWhenBlocked:
type: boolean
description: When set to `true`, the profile can complete the redemption of promotions that had been activated before a lock was put on that profile.
nullable: true
default: false
saleSettings:
type: object
nullable: true
description: Settings for sales
properties:
discountSourceType:
type: integer
nullable: true
description: The type which is assigned to discounts to differentiate which ones come from Synerise when using the Process Basket/Checkout endpoints.
example: 0
clientIdCardType:
type: integer
nullable: true
description: The type of card which is used for extracting profile identification data
example: 0
handbillCheckout:
type: string
format: uuid
nullable: true
description: UUID of the Handbill which is used to generate promotions in the Process Checkout endpoints
priceValueBaseStrategy:
type: string
default: MUTABLE
description: |
This strategy defines how basket discount values are calculated in the Process Basket endpoints.
- If the CONSTANT strategy is chosen, the discounts are always calculated based on the evidPrice of the item.
- If the MUTABLE strategy is chosen, the price of an item is updated after each promotion assignment and it is treated as a base for calculating the discounts that follow.
**Example:** One basket with two promotions (20%, 30%) and one item with a price of 1.00.
- When the CONSTANT strategy is chosen, the discounts are always subtracted from evidPrice=1.00, so the effective discounts are 0.20 and 0.30. The final price is 0.50.
- When the MUTABLE strategy is chosen, the discounts are calculated using the updated item price, so applying them in order (20%, 30%) is done in the following way:
1. `20% of 1.00 = 0.20, *updated price* = 0.80`
2. `30% of *updated price* = 30% * 0.80 = 0.24`
3. The final price is `1.00 - 0.20 - 0.24 = 0.56`
To define the order of applying promotions, use the `discountOrder` object.
enum:
- CONSTANT
- MUTABLE
combineBasketDiscounts:
type: boolean
description: If `true`, basket discounts are combined.
default: false
discountOrder:
type: object
description: Discount order settings
properties:
strategy:
type: string
description: The strategy defines the order of applying discounts. The direction is set in `direction`.
default: DISCOUNT_VALUE
enum:
- DISCOUNT_VALUE
- PRIORITY
direction:
type: string
description: Direction of the discount order within the strategy selected in `strategy`.
default: desc
enum:
- asc
- desc
returnFields:
type: array
items:
type: string
description: An array of promotion fields which should be returned in the Process Basket endpoints in the `transactionItems.grantedDiscounts` object.
lockSettings:
type: object
nullable: true
description: Settings for locks
required:
- lockPromotionRequestByIdentifier
properties:
promotionRequestedLockTtl:
type: number
description: The time in seconds for which promotion deactivation will be blocked after a POS request.
default: 60
processSalePromotionActivationLockWaitTime:
type: number
description: The time in seconds that the system will wait and retry to acquire a promotion activation lock during the process sale operation.
lockPromotionRequestByIdentifier:
type: boolean
description: Indicates if POS should provide the `lockIdentifier`, which puts a lock on promotion fetching the promotion list. This identifier can be sent when using the [Get Profile promotions by a custom filter](#operation/GetClientPromotionsByACustomFilter) endpoint.
nullable: false
transferSettings:
type: array
minItems: 1
maxItems: 1
description: Settings for point transfers
items:
type: object
properties:
expression:
type: string
format: uuid
description: UUID of expression that defines how the points should be calculated when evaluating sender points balance
example: 2395fc33-f2f0-420c-8e7b-0ac63c3454de
recipient:
type: object
description: Point recipient settings
properties:
segments:
type: array
nullable: true
description: IDs of the Profile segmentations that can participate in point transfers as recipients
items:
type: string
sender:
type: object
description: Point sender settings
properties:
segments:
type: array
nullable: true
description: IDs of the Profile segmentations that can participate in point transfers as senders
items:
type: string
cashbackSettings:
type: object
description: Settings for cashback mechanism
nullable: true
required:
- exchangeRate
properties:
exchangeRate:
type: number
minimum: 0.0001
description: Defines how much currency corresponds to one point. For example, if the currency is PLN and exchangeRate is 2, then 1 point equals 2 PLN.
limits:
type: object
nullable: true
description: Defines the limits on cashback usage
properties:
minPoints:
type: integer
nullable: true
minimum: 1
description: The minimum number of points required to spend for cashback. If null - there is no limit defined.
example: 10
maxPoints:
type: integer
nullable: true
minimum: 1
description: The maximum number of points allowed to spend for cashback. If null - there is no limit defined.
example: 1000
maxTransactionAmount:
type: number
nullable: true
minimum: 0.01
description: Maximum amount in local currency to redeem in a transaction. If null - there is no limit defined.
example: 20
maxTransactionPercentage:
type: number
nullable: true
description: Defines how much (in percent) of the total transaction amount can be treated as cashback. If null - there is no limit defined.
example: 50
minimum: 0.01
maximum: 100
example:
data:
expression: xxxxxxx-d047-40fd-99c8-yyyyxxxxyyy
blockTag: BLOCK_PROMOTIONS
checkoutSettings:
handbilUuids:
- 1eb6c8f0-dc7a-4d9c-9e0e-bb995ee87699
cashbackSettings:
exchangeRate: 10
limits:
minPoints: 10
maxPoints: 100
maxTransactionAmount: 80
maxTransactionPercentage: 60
promotionListSettings:
fields:
- code
- possibleRedeems
- lastingAt
- vouchers
sort: NONE
limit: 200
where:
status:
- ASSIGNED
- ACTIVE
type:
- CUSTOM
- MEMBERS_ONLY
- HANDBILL
target:
- ALL
- SEGMENT
tagNames: null
lastingOnly: true
presentOnly: true
statusByType:
CUSTOM:
- ACTIVE
HANDBILL:
- ASSIGNED
targetByType:
CUSTOM:
- ALL
HANDBILL:
- ALL
MEMBERS_ONLY:
- SEGMENT
visibilityStatus:
- PUBLISH
- HIDDEN
"400":
description: Request body invalid/malformed/missing elements
content:
application/json:
schema:
anyOf:
- type: object
title: JSON content issue
properties:
message:
type: string
description: Summary of the error
error:
description: Details of the error
anyOf:
- type: array
description: An array of objects with error details
items:
type: object
description: Details of an error
properties:
message:
type: string
description: Short description of the error
example: Internal Error
additionalProperties:
description: Additional information, if applicable
- type: string
description: Description of the error
- type: object
title: JSON structure issue
properties:
message:
type: string
description: Summary of the error
code:
type: string
description: String-type code of the error
"401":
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP code of the problem
error:
type: string
description: Summary of the error
message:
type: string
description: Error details
timestamp:
type: string
description: Time when the error occurred
"403":
description: Forbidden
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP code of the problem
error:
type: string
description: Summary of the error
message:
type: string
description: Error details
timestamp:
type: string
description: Time when the error occurred
"404":
description: Not Found
content:
application/json:
schema:
type: object
properties:
status:
type: integer
description: HTTP code of the problem
error:
type: string
description: Summary of the error
message:
type: string
description: Error details
timestamp:
type: string
description: Time when the error occurred
x-snr-doc-urls:
- /api-reference/loyalty-and-engagement#tag/Promotion-settings/operation/endpointSettingsGetSettingsGET
description: |
---
**API consumers:** Workspace (Business Profile), Synerise User
**API key permission required:** `PROMOTIONS_SETTINGS_PROMOTIONS_READ`
**User role permission required:** `campaigns_personalised_promotions: read`
x-codeSamples:
- lang: cURL
label: cURL
source: |-
curl --request GET \
--url 'https://api.synerise.com/v4/promotions/settings?only=saleSettings.combineBasketDiscounts&withDefaults=SOME_BOOLEAN_VALUE'
- lang: Python
label: Python
source: |-
import http.client
conn = http.client.HTTPSConnection("api.synerise.com")
conn.request("GET", "/v4/promotions/settings?only=saleSettings.combineBasketDiscounts&withDefaults=SOME_BOOLEAN_VALUE")
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
- lang: JavaScript
label: JavaScript
source: |-
const data = null;
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://api.synerise.com/v4/promotions/settings?only=saleSettings.combineBasketDiscounts&withDefaults=SOME_BOOLEAN_VALUE");
xhr.send(data);
- lang: Node.js
label: Node.js
source: |-
const http = require("https");
const options = {
"method": "GET",
"hostname": "api.synerise.com",
"port": null,
"path": "/v4/promotions/settings?only=saleSettings.combineBasketDiscounts&withDefaults=SOME_BOOLEAN_VALUE",
"headers": {}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
- lang: PHP
label: PHP
source: |-
setUrl('https://api.synerise.com/v4/promotions/settings');
$request->setMethod(HTTP_METH_GET);
$request->setQueryData([
'only' => 'saleSettings.combineBasketDiscounts',
'withDefaults' => 'SOME_BOOLEAN_VALUE'
]);
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
- lang: Java
label: Java
source: |-
HttpResponse response = Unirest.get("https://api.synerise.com/v4/promotions/settings?only=saleSettings.combineBasketDiscounts&withDefaults=SOME_BOOLEAN_VALUE")
.asString();
servers:
- description: Microsoft Azure EU
url: https://api.synerise.com
- description: Microsoft Azure USA
url: https://api.azu.synerise.com
- description: Google Cloud Platform
url: https://api.geb.synerise.com
tags:
- name: Promotion settings
```