updatePromotion
put
/ccadmin/v1/promotions/{id}
Update an existing promotion. **Requires the x-ccasset-language header so translated content can be set for a specific language.**
Request
Supported Media Types
- application/json
Path Parameters
-
id(required): string
ID corresponding to the promotion to udpate.
Header Parameters
-
X-CC-Workset: string
The ID of the workset that this change will appear in. If this header is missing, the change will be made in the default workset.
-
X-CCAsset-Language(required): string
The asset language of the request
Properties to update on the promotion.
Root Schema : updatePromotion_request
Type:
Show Source
object
-
allowMultiple:
boolean
Determines whether the promotion can be given to a customer only once. If set to false, the system grants the promotion only once. If set to true, the system adds a copy of the promotion to the customer's profile every time the customer is granted the promotion.
-
audiences:
array audiences
List of audiences to which the promotion is limited. An empty list implies no restrictions.
-
cardIINRanges:
array cardIINRanges
List of issuer identification numbers including wildcards and ranges for which the promotion should be applied.
-
closenessQualifiers:
array closenessQualifiers
Array of message sets that apply to a specific criteria for displaying a partially-qualified upsell message to a shopper. Partial qualification is based on the threshold value specified in templateValues.See online documentation for more details.
-
description:
string
The description of the promotion.
-
displayName:
string
The display name of the promotion.
-
enableConversion:
boolean
Enables promotion data conversion for promotions based on upgraded templates. Default value is 'false'.
-
enabled:
boolean
Whether or not the promotion is currently enabled.
-
endDate:
string
When this promotion ceases to be active
-
excludedPromotions:
array excludedPromotions
List of promotions to be excluded from the current promotion. Item promotions can exclude promotions of type: item, order, shipping. Order promotions can exclude promotion of type order and shipping. Shipping promotions can only exclude another shipping promotions.
-
filterForQualifierActedAsQualifier:
boolean
Determines whether qualifiers can be reused in a promotion. If true, qualifiers can be used only once per promotion evaluation. Applicable to all promotion types. If unset, will be treated as true.
-
filterForQualifierDiscountedByAny:
boolean
Determines whether items discounted by any promotion can act as qualifiers for other promotions. Applicable to all promotion types. If unset, will be treated as true.
-
filterForQualifierDiscountedByCurrent:
boolean
Determines whether items discounted by the current promotion can act as qualifiers for other promotions. Applicable to item promotions. If unset, will be treated as true.
-
filterForQualifierNegativePrices:
boolean
Determines whether items with negative prices can act as qualifiers for other promotions. Applicable to all promotion types. If unset, will be treated as true.
-
filterForQualifierOnSale:
boolean
Determines whether items that were priced with a sale price should be allowed to act as qualifiers. Applicable to all promotion types. If unset, will be treated as false.
-
filterForQualifierZeroPrices:
boolean
Determines whether items with zero prices can act as qualifiers. Applicable to all promotion types. If unset, will be treated as true.
-
filterForTargetActedAsQualifier:
boolean
Determines whether items that have acted as a qualifier for any discount can receive the current discount. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetDiscountedByAny:
boolean
Determines whether items that have been discounted by any promotion can receive another discount. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetDiscountedByCurrent:
boolean
Determines whether items that have been discounted by the current promotion can receive the discount again. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetNegativePrices:
boolean
Determines whether items with negative prices can receive the discount. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetOnSale:
boolean
Determines whether items that were priced with a sale price should be allowed to receive the current discount. If unset, will be treated as true.
-
filterForTargetPriceLTOETPromoPrice:
boolean
Determines whether to exclude items with price lower than promotion price. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetZeroPrices:
boolean
Determines whether items with zero prices can receive the discount. Applicable to item promotions. If unset, will be treated as true.
-
giveToAnonymousProfiles:
boolean
If both this property and the global property are false, then only registered visitors can receive the promotion. If this property is true, and the global property is false, then anonymous visitors and registered visitors can receive the promotion. In both cases, the visitors must meet any other conditions specified by the promotion in order to receive it.
-
maxUsesPerOrder:
integer
Number of times a promotion can be applied to an order, -1 indicates that the same promotion can be applied unlimited number of times
-
parentFolder:
object parentFolder
Map of promotion folder's repository ID key and value. In order to remove the folder assignment, set parentFolder to null e.g. "parentFolder": null
-
priceListGroups:
array priceListGroups
The price List Groups
-
priority:
string
The priority of this promotion over other promotions
-
qualifiedMessages:
array qualifiedMessages
Promotion upsell messages to display when the shopper has qualified for the promotion.
-
shippingMethods:
array shippingMethods
Shipping Methods for which the promotion should be applied
-
sites:
array sites
This will limit the promotion to being applicable only to the 1+ specified sites. An empty array means the promotion applies to all sites.
-
startDate:
string
When this promotion becomes active
-
templateValues:
object templateValues
Specifies the template values that are used as part of the promotion to control its behavior
-
unqualifiedMessages:
array unqualifiedMessages
Promotion upsell messages to display when the shopper has not yet qualified for the promotion.
-
uses:
integer
The number of orders for a given customer to which the promotion can be applied.
Example:
{
"endDate":"2014-04-29T19:30:00.000-04:00",
"filterForQualifierZeroPrices":null,
"maxUSesPerOrder":"-1",
"displayName":"10% Off Orders Over $100 ",
"templateValues":{
"spend_value":"100",
"discount_value":"10",
"discount_type_value":"percentOff",
"spend_close_value":"5.00"
},
"description":"Spend $100 today and get 10% off your order!",
"sites":[
{
"repositoryId":"funSite"
},
{
"repositoryId":"anotherFunSite"
}
],
"enabled":true,
"cardIINRanges":[
"456789",
"9878",
"987634-987648"
],
"filterForQualifierNegativePrices":null,
"parentFolder":{
"repositoryId":"promoFolder100001"
},
"filterForQualifierOnSale":null,
"audiences":[
{
"repositoryId":"audienceId1"
},
{
"repositoryId":"audienceId2"
}
],
"filterForQualifierActedAsQualifier":null,
"giveToAnonymousProfiles":false,
"shippingMethods":[
"priorityShippingMethod",
"groundShippingMethod"
],
"closenessQualifiers":[
{
"closenessMessages":[
{
"message":"You're getting close! Buy {{QuantityStillNeeded}} more!",
"tags":[
{
"name":"Daily Deals"
},
{
"name":"Banner"
}
]
}
]
}
],
"priority":"1",
"filterForQualifierDiscountedByAny":null,
"excludedPromotions":[
{
"repositoryId":"explicitItemFixedDiscount"
},
{
"repositoryId":"bogoPromotion"
}
],
"unqualifiedMessages":[
{
"message":"Buy something to qualify for this promotion.",
"tags":[
{
"name":"Banner"
}
]
}
],
"enableConversion":true,
"allowMultiple":false,
"qualifiedMessages":[
{
"message":"You have qualified for the promotion!",
"tags":[
{
"name":"Banner"
}
]
}
],
"uses":"2",
"startDate":"2014-04-25T17:30:00.000-04:00"
}
Nested Schema : audiences
Type:
array
List of audiences to which the promotion is limited. An empty list implies no restrictions.
Show Source
Nested Schema : cardIINRanges
Type:
array
List of issuer identification numbers including wildcards and ranges for which the promotion should be applied.
Show Source
Nested Schema : closenessQualifiers
Type:
array
Array of message sets that apply to a specific criteria for displaying a partially-qualified upsell message to a shopper. Partial qualification is based on the threshold value specified in templateValues.See online documentation for more details.
Show Source
Nested Schema : excludedPromotions
Type:
array
List of promotions to be excluded from the current promotion. Item promotions can exclude promotions of type: item, order, shipping. Order promotions can exclude promotion of type order and shipping. Shipping promotions can only exclude another shipping promotions.
Show Source
Nested Schema : parentFolder
Type:
object
Map of promotion folder's repository ID key and value. In order to remove the folder assignment, set parentFolder to null e.g. "parentFolder": null
Show Source
-
repositoryId:
string
Existing promotion folder's repository ID
Nested Schema : qualifiedMessages
Type:
array
Promotion upsell messages to display when the shopper has qualified for the promotion.
Show Source
Nested Schema : shippingMethods
Type:
array
Shipping Methods for which the promotion should be applied
Show Source
Nested Schema : sites
Type:
array
This will limit the promotion to being applicable only to the 1+ specified sites. An empty array means the promotion applies to all sites.
Show Source
Nested Schema : templateValues
Type:
object
Specifies the template values that are used as part of the promotion to control its behavior
Show Source
-
condition_psc_value:
object condition_psc_value
The condition product set criteria value
-
discount_type_value:
string
The discount type
-
discount_value:
string
The discount value
-
discountStructure:
object discountStructure
The discount structure
-
gwpItem:
object gwpItem
The gift with promotion configuration details
-
no_of_items_to_buy:
string
The number of items to buy
-
no_of_items_to_discount:
string
The number of items to discount
-
offer_psc_value:
object offer_psc_value
The offer product set criteria values
-
optional_offer_psc_value:
object optional_offer_psc_value
The offer product set criteria values
-
PSC_value:
object PSC_value
The product set criteria values
-
sort_by:
string
The sort by condition
-
sort_order:
string
The sort order
-
spend_value:
string
The spend value
Nested Schema : unqualifiedMessages
Type:
array
Promotion upsell messages to display when the shopper has not yet qualified for the promotion.
Show Source
Nested Schema : items
Type:
Show Source
object
-
repositoryId(required):
string
The ID of an audience associated with the promotion.
Nested Schema : items
Type:
Show Source
object
-
closenessMessages:
array closenessMessages
Promotion upsell messages to display when the shopper has partially-qualified for the promotion.
-
repositoryId:
string
The closeness qualifier's ID. If provided, this will update an existing closeness qualifier; otherwise a new closeness qualifier will be created. If a closeness qualifier already exists, it will be deleted and replaced.
Nested Schema : closenessMessages
Type:
array
Promotion upsell messages to display when the shopper has partially-qualified for the promotion.
Show Source
Nested Schema : items
Type:
Show Source
object
-
message:
string
Localizable text for the upsell message.
-
repositoryId:
string
The message's ID. If provided, this will update an existing message; otherwise a new message will be created. If a message already exists, it will be deleted and replaced.
-
tags:
array tags
Array of message tags to use in associating where to display the message on the storefront.
Nested Schema : items
Type:
Show Source
object
-
repositoryId(required):
string
The promotion's repository ID
Nested Schema : items
Type:
Show Source
object
-
message:
string
Localizable text for the upsell message.
-
repositoryId:
string
The message's ID. If provided, this will update an existing message; otherwise a new message will be created. If a message already exists, it will be deleted and replaced.
-
tags:
array tags
Array of message tags to use in associating where to display the message on the storefront.
Nested Schema : items
Type:
Show Source
object
-
repositoryId(required):
string
The ID of a site associated with the promotion.
Nested Schema : condition_psc_value
Type:
object
The condition product set criteria value
Show Source
-
excludedCategories:
array excludedCategories
The excluded categories
-
excludedProducts:
array excludedProducts
The excluded products
-
excludedSkus:
array excludedSkus
The excluded SKU IDs
-
includedCategories:
array includedCategories
The included categories
-
includedProducts:
array includedProducts
The included products
-
includedSkus:
array includedSkus
The included SKU IDs
Nested Schema : discountStructure
Type:
object
The discount structure
Show Source
-
discount_details:
array discount_details
The discount details
-
discount_type_value:
string
The discount type value
Nested Schema : gwpItem
Type:
object
The gift with promotion configuration details
Show Source
-
autoRemove:
boolean
Whether to remove item from cart when cart no longer meets buy condition
-
giftId:
string
The product id of the gift item
-
giftType:
string
The gift item type
Nested Schema : offer_psc_value
Type:
object
The offer product set criteria values
Show Source
-
excludedCategories:
array excludedCategories
The excluded categories
-
excludedProducts:
array excludedProducts
The excluded products
-
excludedSkus:
array excludedSkus
The excluded SKU IDs
-
includedCategories:
array includedCategories
The included categories
-
includedProducts:
array includedProducts
The included products
-
includedSkus:
array includedSkus
The included SKU IDs
Nested Schema : optional_offer_psc_value
Type:
object
The offer product set criteria values
Show Source
-
excludedCategories:
array excludedCategories
The excluded categories
-
excludedProducts:
array excludedProducts
The excluded products
-
excludedSkus:
array excludedSkus
The excluded SKU IDs
-
includedCategories:
array includedCategories
The included categories
-
includedProducts:
array includedProducts
The included products
-
includedSkus:
array includedSkus
The included SKU IDs
-
sameAsCondition:
boolean
Items to include and exclude for offer are the same as items in buy condition
Nested Schema : PSC_value
Type:
object
The product set criteria values
Show Source
-
excludedCategories:
array excludedCategories
The excluded categories
-
excludedProducts:
array excludedProducts
The excluded products
-
excludedSkus:
array excludedSkus
The excluded SKU Ids
-
includedCategories:
array includedCategories
The included categories
-
includedProducts:
array includedProducts
The included products
-
includedSkus:
array includedSkus
The included SKU IDs
Nested Schema : items
Type:
Show Source
object
-
discount_value:
string
The discount value
-
spend_value:
string
The spend value
Nested Schema : items
Type:
Show Source
object
-
message:
string
Localizable text for the upsell message.
-
repositoryId:
string
The message's ID. If provided, this will update an existing message; otherwise a new message will be created. If a message already exists, it will be deleted and replaced.
-
tags:
array tags
Array of message tags to use in associating where to display the message on the storefront.
Response
Supported Media Types
- application/json
200 Response
Following model is returned when operation succeeds.
Root Schema : updatePromotion_response
Type:
Show Source
object
-
allowMultiple:
boolean
Determines whether the promotion can be given to a customer only once. If set to false, the system grants the promotion only once. If set to true, the system adds a copy of the promotion to the customer's profile every time the customer is granted the promotion.
-
cardIINRanges:
array cardIINRanges
List of issuer identification numbers including wildcards and ranges for which the promotion should be applied.
-
displayName:
string
The display name of the promotion.
-
enabled:
boolean
Whether or not the promotion is currently enabled.
-
endDate:
string
When this promotion ceases to be active
-
filterForQualifierActedAsQualifier:
boolean
Determines whether qualifiers can be reused in a promotion. If true, qualifiers can be used only once per promotion evaluation. Applicable to all promotion types. If unset, will be treated as true.
-
filterForQualifierDiscountedByAny:
boolean
Determines whether items discounted by any promotion can act as qualifiers for other promotions. Applicable to all promotion types. If unset, will be treated as true.
-
filterForQualifierDiscountedByCurrent:
boolean
Determines whether items discounted by the current promotion can act as qualifiers for other promotions. Applicable to item promotions. If unset, will be treated as true.
-
filterForQualifierNegativePrices:
boolean
Determines whether items with negative prices can act as qualifiers for other promotions. Applicable to all promotion types. If unset, will be treated as true.
-
filterForQualifierOnSale:
boolean
Determines whether items that were priced with a sale price should be allowed to act as qualifiers. Applicable to all promotion types. If unset, will be treated as false.
-
filterForQualifierZeroPrices:
boolean
Determines whether items with zero prices can act as qualifiers. Applicable to all promotion types. If unset, will be treated as true.
-
filterForTargetActedAsQualifier:
boolean
Determines whether items that have acted as a qualifier for any discount can receive the current discount. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetDiscountedByAny:
boolean
Determines whether items that have been discounted by any promotion can receive another discount. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetDiscountedByCurrent:
boolean
Determines whether items that have been discounted by the current promotion can receive the discount again. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetNegativePrices:
boolean
Determines whether items with negative prices can receive the discount. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetOnSale:
boolean
Determines whether items that were priced with a sale price should be allowed to receive the current discount. If unset, will be treated as true.
-
filterForTargetPriceLTOETPromoPrice:
boolean
Determines whether to exclude items with price lower than promotion price. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetZeroPrices:
boolean
Determines whether items with zero prices can receive the discount. Applicable to item promotions. If unset, will be treated as true.
-
giveToAnonymousProfiles:
boolean
If both this property and the global property are false, then only registered visitors can receive the promotion. If this property is true, and the global property is false, then anonymous visitors and registered visitors can receive the promotion. In both cases, the visitors must meet any other conditions specified by the promotion in order to receive it.
-
global:
boolean
Whether the promotion is global.
-
id:
string
The Promotion id.
-
lastModified:
string
When promotion was last modified
-
maxUsesPerOrder:
integer
Number of times a promotion can be applied to an order, -1 indicates that the same promotion can be applied unlimited number of times
-
parentFolder:
object parentFolder
Parent Folder object of the current promotion.
-
repositoryId:
string
The Promotion id.
-
sites:
array sites
This will limit the promotion to being applicable only to the 1+ specified sites. An empty array means the promotion applies to all sites.
-
stackingRule:
object stackingRule
Represents a rule to determine a group of promotions that can be used together.
-
startDate:
string
When this promotion becomes active
-
type:
integer
Integer representation of the promotion type (shipping, item, order).
-
uses:
integer
The number of orders for a given customer to which the promotion can be applied.
Nested Schema : cardIINRanges
Type:
array
List of issuer identification numbers including wildcards and ranges for which the promotion should be applied.
Show Source
Nested Schema : parentFolder
Type:
object
Parent Folder object of the current promotion.
Show Source
-
repositoryId:
string
Existing promotion folder's repository ID
Nested Schema : sites
Type:
array
This will limit the promotion to being applicable only to the 1+ specified sites. An empty array means the promotion applies to all sites.
Show Source
Nested Schema : stackingRule
Type:
object
Represents a rule to determine a group of promotions that can be used together.
Show Source
-
displayName:
string
The name of the rule.
-
id:
string
The stacking rule id.
-
maxPromotions:
string
The maximum number of promotions that can be applied to an order based on this rule.
-
repositoryId:
string
The stacking rule id
Nested Schema : items
Type:
Show Source
object
-
repositoryId:
string
The ID of a site associated with the promotion.
Example Response (application/json)
{
"filterForQualifierZeroPrices":null,
"displayName":"Hubbard Chair Tiered Price Break",
"global":false,
"type":"0",
"filterForQualifierDiscountedByCurrent":null,
"enabled":false,
"cardIINRanges":[
"456789",
"9878",
"987634-987648"
],
"filterForQualifierNegativePrices":null,
"parentFolder":{
"repositoryId":"promoFolder100001"
},
"filterForQualifierOnSale":null,
"filterForTargetNegativePrices":null,
"audiences":[
{
"repositoryId":"audienceId1"
},
{
"repositoryId":"audienceId2"
}
],
"id":"promo20009",
"giveToAnonymousProfiles":false,
"filterForQualifierActedAsQualifier":null,
"filterForTargetDiscountedByCurrent":null,
"filterForTargetActedAsQualifier":null,
"filterForTargetDiscountedByAny":null,
"filterForQualifierDiscountedByAny":null,
"filterForTargetOnSale":null,
"filterForTargetZeroPrices":null,
"allowMultiple":false,
"repositoryId":"promo20009",
"filterForTargetPriceLTOETPromoPrice":null,
"uses":"2"
}
412 Response
ETag mismatch. Asset has been updated by another user.
Default Response
The error response.
The following are the internal error codes thrown by this API when the request processing fails in Oracle Commerce Cloud:
|Error Code|Description|
|------------------|------------------|
|21038|Invalid data error. The exact error message will vary based on the property.|
|21247|Invalid format for parentFolder property|
|21244|No item found for the following type and ID: promotionFolder, invalidId|
|21176|incompatiblePromotionId : Promotion can not be linked to itself with included/excluded Promotions property : itemPromotion.|
|21174|incompatiblePromotionId : Promotion type item can not be included/excluded with the given promotion type : {item/order or discount}.|
|21171|No item found for the following type and ID: promotion, invalidPromotion.|
Root Schema : errorModel
Type:
Show Source
object
-
devMessage:
string
An optional non-localized message containing technical information for developers
-
errorCode:
string
The numerical code identifying the error
-
errors:
array errors
An optional list of errors if multiple errors were encountered
-
message:
string
The localized message describing the error
-
moreInfo:
string
An optional non-localized message with more information
-
o:errorPath:
string
An optional machine readable description of where the error occurred
-
status:
string
The HTTP status code
-
type:
string
The URI to the HTTP state code definition
Nested Schema : errors
Type:
array
An optional list of errors if multiple errors were encountered
Show Source
Nested Schema : items
Type:
Show Source
object
-
devMessage:
string
An optional non-localized message containing technical information for developers
-
errorCode:
string
The numerical code identifying the error
-
message:
string
The localized message describing the error
-
moreInfo:
string
An optional non-localized message with more information
-
o:errorPath:
string
An optional machine readable description of where the error occurred
-
status:
string
The HTTP status code