1. REST API for Oracle Commerce Cloud December 2017
  2. Tasks
  3. Admin
  4. Promotions

listPromotions

get

/ccadmin/v1/promotions

List 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
Type: string
One of three values: enabled, disabled, both. This will return promotions that are enabled, disabled, or both enabled and disabled.
folder
Type: 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
Type: 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
Type: 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
Type: integer
The number of items to return.
name
Type: string
This is a search filter value that will find promotions that match on the ID or display name.
offset
Type: integer
Index of the first element to return.
promotionId
Type: string
A filter string that will return partial matches on ID or displayName. This returns ALL promotions, no paging, no limit.
promotionType
Type: 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
Type: 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
Type: 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
Type: string
Filters the results using a specific template key in the format of type.name. E.g., item.getItemDiscount.
total
Type: integer
The total number of items.

Response

Supported Media Types
  • application/json
200 Response
Following model is returned when operation succeeds.
Body
Root Schema : listPromotions_response
Nested Schema : items
Type: array
The items returned by the listing.
Nested Schema : sort
Type: array
Sorting criteria.
Nested Schema : items
Type: object
Nested Schema : cardIINRanges
Type: array
List of issuer identification numbers including wildcards and ranges for which the promotion should be applied.
Nested Schema : parentFolder
Type: object
Parent Folder object of the current promotion.
Nested Schema : sites
Type: array
The list of sites
Nested Schema : stackingRule
Type: object
It represents a rule to determine a group of promotions that can be used together.
Nested Schema : items
Type: object
Nested Schema : items
Type: object
Example application/json

{
    "total":3,
    "totalResults":3,
    "offset":0,
    "limit":3,
    "sort":[
        {
            "property":"displayName",
            "order":"asc"
        }
    ],
    "type":"promotion",
    "items":[
        {
            "parentFolder":{
                "repositoryId":"200002"
            },
            "displayName":"Hubbard Chair Tiered Price Break",
            "repositoryId":"promo20009",
            "stackingRule":{
                "maxPromotions":-1,
                "displayName":"TEST2",
                "repositoryId":"100002",
                "id":"100002"
            },
            "id":"promo20009",
            "lastModified":"2017-01-09T05:10:01.000Z",
            "type":0,
            "enabled":false,
            "cardIINRanges":[
                "456789",
                "9878",
                "987634-987648"
            ]
        },
        {
            "parentFolder":{
                "repositoryId":"200002"
            },
            "displayName":"TENSHIP Coupon - 10% Off Order ",
            "repositoryId":"promo20011",
            "id":"promo20011",
            "lastModified":"2017-01-09T05:10:01.000Z",
            "type":9,
            "enabled":false,
            "cardIINRanges":[
                "456789",
                "9878",
                "987634-987648"
            ]
        },
        {
            "displayName":"TENSHIP Coupon - Free Shipping",
            "repositoryId":"promo20004",
            "id":"promo20004",
            "lastModified":"2017-01-09T05:10:01.000Z",
            "type":5,
            "enabled":false,
            "cardIINRanges":[
                "456789",
                "9878",
                "987634-987648"
            ]
        }
    ]
}
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.|
Body
Root Schema : errorModel
Type: object
Nested Schema : errors
Type: array
An optional list of errors if multiple errors were encountered
Nested Schema : items
Type: object

Examples

Sample Response Payload returned by endpoint:

{
  "total": 3,
  "totalResults": 3,
  "offset": 0,
  "limit": 3,
  "sort": [{
    "property": "displayName",
    "order": "asc"
  }],
  "type": "promotion",
  "items": [
    {
      "parentFolder": {"repositoryId": "200002"},
      "displayName": "Hubbard Chair Tiered Price Break",
      "repositoryId": "promo20009",
      "stackingRule": {
        "maxPromotions": -1,
        "displayName": "TEST2",
        "repositoryId": "100002",
        "id": "100002"
      },
      "id": "promo20009",
      "lastModified": "2017-01-09T05:10:01.000Z",
      "type": 0,
      "enabled": false,
      "cardIINRanges": [
        "456789",
        "9878",
        "987634-987648"
      ]
    },
    {
      "parentFolder": {"repositoryId": "200002"},
      "displayName": "TENSHIP Coupon - 10% Off Order ",
      "repositoryId": "promo20011",
      "id": "promo20011",
      "lastModified": "2017-01-09T05:10:01.000Z",
      "type": 9,
      "enabled": false,
      "cardIINRanges": [
        "456789",
        "9878",
        "987634-987648"
      ]
    },
    {
      "displayName": "TENSHIP Coupon - Free Shipping",
      "repositoryId": "promo20004",
      "id": "promo20004",
      "lastModified": "2017-01-09T05:10:01.000Z",
      "type": 5,
      "enabled": false,
      "cardIINRanges": [
        "456789",
        "9878",
        "987634-987648"
      ]
    }
  ]
}