# Deactivate a promotion
- Operation ID: `DeactivateAPromotion`
- HTTP method: `POST`
- Path: `/v4/promotions/promotion/deactivate`
- [Human-readable API reference](https://hub.synerise.com/api-reference/loyalty-and-engagement#tag/Promotions/operation/DeactivateAPromotion)
## 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/promotion/deactivate:
post:
tags:
- Promotions
summary: Deactivate a promotion
description: |
A Profile can change the status of an activated promotion back to `assigned`.
---
**API consumers:** Profile (Client), Anonymous Profile
operationId: DeactivateAPromotion
requestBody:
description: ""
content:
application/json:
schema:
required:
- key
- value
type: object
properties:
key:
type: string
description: Type of promotion identifier
enum:
- uuid
- code
value:
type: string
description: Value of the selected identifier
pointsToUse:
nullable: true
type: integer
minimum: 0
description: How many points should be converted to digital money and stored as ready to redeem in transactions in digital cashback promotions.
example:
key: code
value: 7893467834GG
pointsToUse: 100
required: true
responses:
"200":
description: Promotion deactivated
content:
application/json:
schema:
type: object
description: Details of a promotion
properties:
uuid:
type: string
description: Unique UUIDv4.
code:
type: string
maxLength: 64
description: Unique code
status:
type: string
description: Profile-oriented status of the promotion.
enum:
- ASSIGNED
- ACTIVE
- REDEEMED
type:
type: string
description: Promotion type
enum:
- MEMBERS_ONLY
- HANDBILL
- CUSTOM
- GENERAL
default: GENERAL
redeemLimitPerClient:
type: integer
description: Limit how many times a Profile can redeem this promotion.
default: 0
minimum: 0
maximum: 32767
nullable: true
redeemQuantityPerActivation:
type: integer
nullable: true
description: How many times per activation a multibuy promotion can be redeemed
minimum: 0
maximum: 8388607
currentRedeemedQuantity:
type: integer
description: Current redeem quantity for the Profile.
currentRedeemedLimit:
type: integer
description: Current redeem limit for the Profile.
activationCounter:
type: integer
description: Number of promotion activation
possibleRedeems:
type: integer
description: Number of available redeems left
details:
type: object
description: Promotion details
required:
- discountType
nullable: true
properties:
discountType:
type: object
description: Details that apply for specific discount type
required:
- name
- outerScope
- requiredItemsCount
- discountedItemsCount
properties:
name:
type: string
enum:
- BOGO
default: BOGO
outerScope:
type: boolean
description: |
This defines whether a defined promotion trigger for discount is based on different item scope.
When set to
* `false` it means items are from the same scope,
* `true` it means items are from outer scope and `requiredItems` should be defined.
default: false
example: true
requiredItemsCount:
description: Number of items that should be purchased to meet the promotion condition.
type: integer
format: int32
example: 2
discountedItemsCount:
description: Number of items to apply the discount to.
type: integer
format: int32
example: 1
discountType:
type: string
description: The type of discount
enum:
- PERCENT
- POINTS
- AMOUNT
- NONE
- MULTIBUY
- 2_FOR_1
- EXACT_PRICE
- DIGITAL_CASHBACK
default: NONE
discountValue:
type: number
description: How much discount to apply
default: 0
minimum: 0
maximum: 100
discountMode:
type: string
description: Promotion discount mode
enum:
- STATIC
- STEP
default: STATIC
discountModeDetails:
type: object
properties:
steps:
type: array
nullable: false
minItems: 1
maxItems: 5
items:
required:
- discountValue
- usageThreshold
type: object
properties:
discountValue:
description: Discount value in given step
type: number
usageThreshold:
description: Threshold after current step would apply
type: number
discountUsageTrigger:
type: string
enum:
- TRANSACTION
- REDEEM
nullable: false
description: Describe after what action new steps would be applied
nullable: true
description: 'Applies only when `"discountMode": "STEP"`.'
requireRedeemedPoints:
type: number
nullable: true
format: int32
description: How many loyalty points are needed to activate the promotion
name:
type: string
maxLength: 255
description: Promotion name displayed to viewers
headline:
type: string
nullable: true
description: Promotion headline displayed to viewers
description:
type: string
maxLength: 2048
nullable: true
description: Details of the promotion displayed to viewers
images:
type: array
nullable: true
items:
required:
- url
- type
type: object
properties:
url:
description: Image or thumbnail source. Must be an absolute HTTP/HTTPS URL.
type: string
format: uri
example: https://www.snrcdn.net/upload/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/1537188683527-el-ipadpro.png
type:
type: string
enum:
- image
- thumbnail
description: Images and thumbnails for the promotion
tags:
description: |
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](https://developers.synerise.com/AssetManagement/AssetManagement.html#operation/createDirectoryType). Then create a directory of that type and assign tags to it.
type: array
items:
type: object
properties:
hash:
type: string
description: Hash ID of the tag
example: 6f54671d-157f-4c4e-a577-11fac3111293
nullable: true
startAt:
type: string
nullable: true
format: date-time
description: Time when the promotion becomes available. Defaults to current time.
expireAt:
type: string
nullable: true
format: date-time
description: Time when the promotion ends for all profiles. Defaults to current time. Has to be greater than startAt
displayFrom:
type: string
nullable: true
description: Time when the promotion becomes displayable. Defaults to null.
displayTo:
type: string
nullable: true
description: Time when the promotion stops being displayed for users. Defaults to null. Has to be greater than displayFrom.
assignedAt:
type: string
nullable: true
format: date-time
description: Time when promotion becomes active for the Profile.
lastingTime:
type: integer
format: int32
nullable: true
description: Duration of the promotion in seconds. This countdown starts when the profile activates a promotion and is individual for each profile.
default: 0
lastingAt:
type: string
nullable: true
format: date-time
description: Time when promotion becomes expire for the Profile.
params:
type: object
description: A JSON object with any custom parameters of type string, object, array.
nullable: true
additionalProperties: true
catalogIndexItems:
type: array
items:
type: string
description: |
'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.'
nullable: true
example: []
price:
description: 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.
type: integer
default: 0
minimum: 0
maximum: 2147483647
priority:
description: Defines the promotion's priority, used both for display order and to order candidate promotions when they are selected during handbill and checkout assignment. Values are ordered ascending, so a lower number means a higher priority and `1` is the highest. When the per-slot read limit or the AI request cap truncates the candidate list, the higher-priority (lower-numbered) promotions are the ones kept. Promotions that share the same priority have no further guaranteed ordering between them, so when a truncation boundary falls inside a group of equal priority it is not defined which of them are kept — assign distinct priorities to the promotions that must always win.
type: integer
minimum: 1
maximum: 500
default: 250
itemScope:
type: string
description: |-
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
enum:
- LINE_ITEM
- BASKET
default: LINE_ITEM
minBasketValue:
type: number
nullable: true
default: null
minimum: 0
description: |
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:
type: number
nullable: true
default: null
minimum: 0
description: |
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.
vouchers:
type: array
description: Vouchers redeemed successfully
items:
type: object
required:
- code
- status
- autoGenerated
- lastingAt
- redeemedAt
- assignedAt
properties:
code:
type: string
description: Voucher code
example: 6f54671d-157f-4c4e-a577-11fac3111293
status:
type: string
description: Status of the voucher
example: ASSIGNED
enum:
- ASSIGNED
- REDEEMED
- CANCELED
autoGenerated:
type: boolean
example: false
description: "`true` if the voucher was generated by an algorithm"
lastingAt:
type: string
nullable: true
example: 2026-01-01
format: date-time
description: Time when the voucher expires.
redeemedAt:
type: string
nullable: true
example: null
format: date-time
description: Time when the voucher was redeemed.
assignedAt:
type: string
nullable: true
example: 2025-01-01
format: date-time
description: Time when the voucher was assigned.
extra:
type: object
nullable: true
description: |
Assignment provenance when the promotion was assigned from a handbill. Absent otherwise. Reflects the handbill config at assignment time. Always returned regardless of the `fields` query param.
properties:
slot:
type: integer
minimum: 0
description: Index in the handbill variant's `slotFilters.slots` the item filled.
assignmentSource:
type: string
enum:
- ai
- ai_relaxed_filter
- random
- fallback_random
- fallback_pool
description: |
How the item was selected. `ai_relaxed_filter` marks items the AI engine added itself to fill the slot (e.g. to complete a distinct-filtered slot). Extensible — clients must tolerate new values.
"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: Promotion deactivation is forbidden due to promotion setup.
content:
application/json:
schema:
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
"404":
description: Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: Short summary of the response
example:
message: Promotion for profile not found
"429":
description: Waiting for profile lock release
content:
application/json:
schema:
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
deprecated: false
security:
- JWT: []
x-snr-doc-urls:
- /api-reference/loyalty-and-engagement#tag/Promotions/operation/DeactivateAPromotion
x-codeSamples:
- lang: cURL
label: cURL
source: |-
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}'
- lang: Python
label: Python
source: |-
import http.client
conn = http.client.HTTPSConnection("api.synerise.com")
payload = "{\"key\":\"code\",\"value\":\"7893467834GG\",\"pointsToUse\":100}"
headers = {
'Authorization': "Bearer REPLACE_BEARER_TOKEN",
'content-type': "application/json"
}
conn.request("POST", "/v4/promotions/promotion/deactivate", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
- lang: JavaScript
label: JavaScript
source: |-
const data = JSON.stringify({
"key": "code",
"value": "7893467834GG",
"pointsToUse": 100
});
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.synerise.com/v4/promotions/promotion/deactivate");
xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
- lang: Node.js
label: Node.js
source: |-
const http = require("https");
const options = {
"method": "POST",
"hostname": "api.synerise.com",
"port": null,
"path": "/v4/promotions/promotion/deactivate",
"headers": {
"Authorization": "Bearer REPLACE_BEARER_TOKEN",
"content-type": "application/json"
}
};
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.write(JSON.stringify({key: 'code', value: '7893467834GG', pointsToUse: 100}));
req.end();
- lang: PHP
label: PHP
source: |-
setUrl('https://api.synerise.com/v4/promotions/promotion/deactivate');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders([
'Authorization' => 'Bearer REPLACE_BEARER_TOKEN',
'content-type' => 'application/json'
]);
$request->setBody('{"key":"code","value":"7893467834GG","pointsToUse":100}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
- lang: Java
label: Java
source: |-
HttpResponse response = Unirest.post("https://api.synerise.com/v4/promotions/promotion/deactivate")
.header("Authorization", "Bearer REPLACE_BEARER_TOKEN")
.header("content-type", "application/json")
.body("{\"key\":\"code\",\"value\":\"7893467834GG\",\"pointsToUse\":100}")
.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: Promotions
components:
securitySchemes:
JWT:
type: http
scheme: bearer
description: |-
JWT Bearer token. The header looks like this: `Bearer {JWT}`
Remember to include the space between 'Bearer' and the token.
Generate a token via the **Authorization** endpoints.
```