listPromotions
get
/ccapp/v1/promotions
Get a list of promotions including support for pagination and sorting.
The following query params cannot be used together: name and promotionId.
Request
Supported Media Types
- application/json
Query Parameters
-
enabledState(optional): string
One of three values: enabled, disabled, both. This will return promotions that are enabled, disabled, or both enabled and disabled.
-
folder(optional): string
Filters the promotions using a specific promotion folder id. All the promotions whose parentfolder is assigned to the provided id can be retrieved through the folder parameter.
-
id(optional): string
If id used only with propertyName, then it is promotion's repository id to fetch the included/excluded promotions list on that promotion. If id is combined with itemType=stackingRule and propertyName=promotions, it returns the list of promotions with stacking rule matching the id.
-
itemType(optional): string
Type of repository item on which the list of referenced promotions is to be fetched. This parameter must be used with id and propertyName to fetch a list of promotions with stacking rule matching the id. It's value can be 'stackingRule or 'promotion'. If this property is skipped, then by default it is considered as 'promotion' type
-
limit(optional): integer
The number of items to return.
-
name(optional): string
This is a search filter value that will find promotions that match on the ID or display name.
-
offset(optional): integer
Index of the first element to return.
-
promotionId(optional): string
A filter string that will return partial matches on ID or displayName. This returns ALL promotions, no paging, no limit.
-
promotionType(optional): string
Filters the results using a specific promotion type. This can be one of three values: item, order, shipping. These can be a comma-separated list (e.g., promotionType=item,order).
-
propertyName(optional): string
Property name that stores a list of promotions on a given item id - e.g. 'excludedPromotions' on a promotion matching id param, or 'promotions' on a stacking rule. This parameter should be used with id parameter that is either repositoryId of a promotion or a stacking rule. If used with id and itemType then it is the property of a repository Item of type itemType.
-
sort(optional): string
Sorting criteria. Following are the fields supported by this param: |Field|Type|Description| |------------------|------------------|------------------| |property|string|The property the listing is sorted by.| |order|string|Sort order: asc or desc.|
-
templateFilter(optional): string
Filters the results using a specific template key in the format of type.name. E.g., item.getItemDiscount.
-
total(optional): integer
The total number of items.
Response
Supported Media Types
- application/json
200 Response
Following model is returned when operation succeeds.
Root Schema : listPromotions_response
Type:
Show Source
object
-
items(optional):
array items
The items returned by the listing.
-
limit(optional):
integer
The number of items to return.
-
offset(optional):
integer
Index of the first element to return.
-
sort(optional):
array sort
Sorting criteria.
-
total(optional):
integer
The total number of items. Deprecated.
-
totalResults(optional):
integer
The total number of items.
-
type(optional):
string
The promotion type being listed.
Nested Schema : items
Type:
Show Source
object
-
allowMultiple(optional):
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(optional):
array audiences
List of audiences to which the promotion is limited. An empty list implies no restrictions.
-
cardIINRanges(optional):
array cardIINRanges
List of issuer identification numbers including wildcards and ranges for which the promotion should be applied.
-
displayName(optional):
string
The display name of the promotion.
-
enabled(optional):
boolean
Whether or not the promotion is currently enabled.
-
endDate(optional):
string
The end date of the promotion.
-
filterForQualifierActedAsQualifier(optional):
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(optional):
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(optional):
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(optional):
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(optional):
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(optional):
boolean
Determines whether items with zero prices can act as qualifiers. Applicable to all promotion types. If unset, will be treated as true.
-
filterForTargetActedAsQualifier(optional):
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(optional):
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(optional):
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(optional):
boolean
Determines whether items with negative prices can receive the discount. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetOnSale(optional):
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(optional):
boolean
Determines whether to exclude items with price lower than promotion price. Applicable to item promotions. If unset, will be treated as true.
-
filterForTargetZeroPrices(optional):
boolean
Determines whether items with zero prices can receive the discount. Applicable to item promotions. If unset, will be treated as true.
-
giveToAnonymousProfiles(optional):
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(optional):
boolean
Whether the promotion is global.
-
id(optional):
string
The Promotion id.
-
lastModified(optional):
string
When promotion was last modified
-
parentFolder(optional):
object parentFolder
Parent Folder object of the current promotion.
-
promotionTemplateName(optional):
string
The name of the promotion template.
-
repositoryId(optional):
string
The repository ID of the promotion.
-
sites(optional):
array sites
The list of sites
-
stackingRule(optional):
object stackingRule
It represents a rule to determine a group of promotions that can be used together.
-
startDate(optional):
string
The start date of the promotion.
-
type(optional):
integer
Integer representation of the promotion type (shipping, item, order).
-
typeName(optional):
string
The type of the promotion.
-
uses(optional):
integer
The number of orders for a given customer to which the promotion can be applied.
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 : parentFolder
Type:
object
Parent Folder object of the current promotion.
Show Source
-
repositoryId(optional):
string
The promotion folder's repository ID that the promotion is assigned to.
Nested Schema : stackingRule
Type:
object
It represents a rule to determine a group of promotions that can be used together.
Show Source
-
displayName(optional):
string
Stacking rule's display name that the promotion is assigned to.
-
id(optional):
string
Stacking rule's ID that the promotion is assigned to.
-
maxPromotions(optional):
integer
The maximum number of promotions that can be applied to an order based on this rule.
-
repositoryId(optional):
string
Stacking rule's repository ID that the promotion is assigned to.
Nested Schema : items
Type:
Show Source
object
-
repositoryId:
string
The ID of an audience associated with the promotion.
Nested Schema : items
Type:
Show Source
object
-
order(optional):
string
Sort order: asc or desc.
-
property(optional):
string
The property the listing is sorted by.
Example Response (application/json)
{
"total":3,
"totalResults":3,
"offset":0,
"limit":3,
"sort":[
{
"property":"displayName",
"order":"asc"
}
],
"type":"promotion",
"items":[
{
"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":"200002"
},
"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,
"stackingRule":{
"maxPromotions":-1,
"displayName":"TEST2",
"repositoryId":"100002",
"id":"100002"
},
"uses":2,
"lastModified":"2017-01-09T05:10:01.000Z"
},
{
"filterForQualifierZeroPrices":null,
"displayName":"TENSHIP Coupon - 10% Off Order ",
"global":false,
"type":9,
"filterForQualifierDiscountedByAny":null,
"enabled":false,
"cardIINRanges":[
"456789",
"9878",
"987634-987648"
],
"filterForQualifierNegativePrices":null,
"parentFolder":{
"repositoryId":"200002"
},
"filterForQualifierOnSale":null,
"allowMultiple":false,
"repositoryId":"promo20011",
"audiences":[
{
"repositoryId":"audienceId1"
},
{
"repositoryId":"audienceId2"
}
],
"uses":2,
"id":"promo20011",
"lastModified":"2017-01-09T05:10:01.000Z",
"giveToAnonymousProfiles":false,
"filterForQualifierActedAsQualifier":null
},
{
"filterForQualifierZeroPrices":null,
"displayName":"TENSHIP Coupon - Free Shipping",
"global":false,
"type":5,
"filterForQualifierDiscountedByAny":null,
"enabled":false,
"cardIINRanges":[
"456789",
"9878",
"987634-987648"
],
"filterForQualifierNegativePrices":null,
"filterForQualifierOnSale":null,
"allowMultiple":false,
"repositoryId":"promo20004",
"audiences":[
{
"repositoryId":"audienceId1"
},
{
"repositoryId":"audienceId2"
}
],
"uses":2,
"id":"promo20004",
"lastModified":"2017-01-09T05:10:01.000Z",
"giveToAnonymousProfiles":false,
"filterForQualifierActedAsQualifier":null
}
]
}
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|
|------------------|------------------|
|21015|Invalid value for the promotionType parameter: {0}.|
|21014|This is an unsupported enabledState: {0}.|
|21001|Promotion not found for the given id: invalidPromotionId.|
|21012|The template filter is improperly formatted: {0}.|
|21011|There is no promotion item type of type {0}.|
|21010|Cannot list promotions with a blank item type.|
|21241|promotion folder not found for the given ID : nonExistingId|
|21174|propertyName is a required property for this request.|
|21240|Promotion folder ID is blank|
|21173|propertyName can only be excludedPromotions for this request.|
|21170|id is a required property for this request.|
|21019|Internal Error.|
Root Schema : errorModel
Type:
Show Source
object
-
devMessage(optional):
string
An optional non-localized message containing technical information for developers
-
errorCode(optional):
string
The numerical code identifying the error
-
errors(optional):
array errors
An optional list of errors if multiple errors were encountered
-
message(optional):
string
The localized message describing the error
-
moreInfo(optional):
string
An optional non-localized message with more information
-
o:errorPath(optional):
string
An optional machine readable description of where the error occurred
-
status(optional):
string
The HTTP status code
-
type(optional):
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(optional):
string
An optional non-localized message containing technical information for developers
-
errorCode(optional):
string
The numerical code identifying the error
-
message(optional):
string
The localized message describing the error
-
moreInfo(optional):
string
An optional non-localized message with more information
-
o:errorPath(optional):
string
An optional machine readable description of where the error occurred
-
status(optional):
string
The HTTP status code