Create custom properties for promotions
This section describes how to use the Oracle Commerce REST web services APIs to add custom properties to promotions.
The Use the REST APIs section contains information you should be familiar with before creating custom properties.
Understand item types
Like shopper profiles, commerce items and orders, promotions include a predefined set of properties. Promotion properties are determined by an item type.
Promotions use the /itemTypes/{id}
administration endpoint, where the ID is a repository item type that supports customizable properties. When you use PUT
with the endpoint, the endpoint uses attributes whose names are configured for each item type. In the case of custom properties for promotions, the itemType
is promotion.
You cannot create additional item types, but you can add custom properties to the
promotion
item type. For example, you could add a custom property that an
administrator uses to indicate additional promotion details.
View a promotion
Promotions can be created with the Oracle Commerce REST Admin APIs by using the createPromotion
endpoint, or updated with
the updatePromotion
endpoint. In both cases, custom properties appear in
the request body alongside the other predefined properties.
You can use the Oracle Commerce Admin API to retrieve promotion information. Issue a GET
request to
/ccadmin/v1/promotions
to display all promotions. For example:
GET /ccadmin/v1/promotions HTTP/1.1
Authorization: Bearer <access_token>
To view a specific promotion, issue a GET
request to the /ccadmin/v1/promotions/{id}
endpoint, providing the ID of the promotion you want to view.
The response displays a list of promotions and a subset of properties for each promotion. You can modify the values of these properties using the PUT /ccadmin/v1/promotions/{id}
endpoint on the administration server.
Create a promotion custom property
To add custom properties to a promotion, issue a PUT
request to the /ccadmin/v1/itemTypes/promotion
endpoint on the administration server.
The Item Types resource in the administration API includes endpoints for creating and working with custom properties of the item type. The items resource in the Admin API includes endpoints that you can use to set the values of properties of individual promotions, including custom properties that have been added to the promotion item type.
The promotion
item type uses some of the attributes used by all
non-product item types, which are type
, uiEditorType
,
label
, default
, internalOnly
,
required
, and localizable
. Note that the
localizable
attribute is rejected by other item types. An attribute that
is specific to the promotion
item type is the
includeInDiscountInfoJson
attribute. When you define a custom property
for a promotion, the includeInDiscountInfoJson
attribute, which is set by
default to true
, indicates if the custom property will be added
automatically along with the promotionId
, promotionDesc
,
and promotionLevel
values that are included in
discountInfo
for each promotion. This attribute, which is a boolean
attribute, can be set when creating or updating the custom property.
When you add a custom property to the promotion
item type, the property is added to all promotions, including any new promotions. Note that changes to an individual promotion must be selected for publication and then published. Custom property definitions are automatically included in the publishing process. For additional information on publishing, refer to Publish Changes.
The ID of a custom property must include the underscore character (_). This ensures that the ID will not conflict with any properties that Commerce adds to promotions in the future. The endpoint produces an error if you attempt to create a custom property without an underscore in its ID.
The following is a sample request to create a custom property named
promotion_campaign
. Note that shortText
is the only
value supported for the type
attribute of a promotion property:
{
"specifications": [
{
"id": "promotion_campaign",
"label": "Campaign",
"type": "shortText",
"required": false,
"uiEditorType": "shortText",
"localizable": false,
"includeInDiscountInfoJson": true
}
]
}
The following is an example response with the new promotion_campaign
custom property:
{
"propertiesOrder": [
"upsell",
"global",
"displayName",
"isSiteRestricted",
"filterForQualifierActedAsQualifier",
"filterForQualifierDiscountedByAny",
"template",
"giveToAnonymousProfiles",
"filterForQualifierOnSale",
"beginUsable",
"startDate",
"filterForQualifierZeroPrices",
"endDate",
"priority",
"endUsable",
"relativeExpiration",
"description",
"timeUntilExpire",
"filterForQualifierNegativePrices",
"allowMultiple",
"uses",
"enabled",
"pmdlVersion",
"evaluationLimit",
"pmdlRule",
"promotion_campaign"
],
"displayName": "Promotion",
"links": [
{
"rel": "self",
"href": "http://my.website.com:9080/ccadmin/v1/itemTypes/promotion"
}
],
...
{
"internalOnly": false,
"uiEditorType": "shortText",
"default": null,
"length": 254,
"includeInDiscountInfoJson": true,
"localizable": false,
"label": "Campaign",
"id": "promotion_campaign",
"type": "shortText",
"editableAttributes": [
"internalOnly",
"default",
"includeInDiscountInfoJson",
"label",
"required"
],
"required": false,
"writable": true
},
{
"internalOnly": false,
"uiEditorType": "number",
"default": 1,
"length": 10,
"includeInDiscountInfoJson": false,
"localizable": false,
"label": "Max uses per customer",
"id": "uses",
"type": "number",
"editableAttributes": [
"internalOnly",
"default",
"includeInDiscountInfoJson",
"label",
"required"
],
"required": false,
"writable": true
},
{
"internalOnly": false,
"uiEditorType": "date",
"default": null,
"length": 7,
"includeInDiscountInfoJson": false,
"localizable": false,
"label": "Distribute starting",
"id": "startDate",
"type": "date",
"editableAttributes": [
"internalOnly",
"default",
"includeInDiscountInfoJson",
"label",
"required"
],
"required": false,
"writable": true
}
]
}
The following is an example of a request for creating a promotion with the promotion_campaign
custom property:
{
"priceListGroups" : [ "defaultPriceGroup" ],
"endDate" : null,
"templateName" : "tieredOrderDiscount",
"displayName" : "10% off over $100",
"templateValues" : {
"discountStructure" : {
"discount_details" : [ {
"spend_value" : "100.00",
"discount_value" : "10.00"
} ],
"discount_type_value" : "percentOff"
}
},
"promotion_campaign" : "onlineOnly",
"sites" : [ ],
"priority" : 1,
"promotionId" : null,
"startDate" : null,
"excludedPromotions" : [ ],
"templatePath" : "order"
}
The following is the request response:
{
"template": "/order/tieredOrderDiscount.pmdt",
"dynamicPropertyMapLong": {},
"endDate": null,
"displayName": "10% off over $100",
"templateValues": {
"discountStructure": {
"discount_details": [
{
"spend_value": "100.00",
"discount_value": "10.00"
}
],
"discount_type_value": "percentOff"
}
},
"description": null,
"global": true,
"sites": [],
"type": 9,
"enabled": true,
"parentFolder": null,
"priceListGroups": [
"defaultPriceGroup"
],
"includedPromotions": [],
"dynamicPropertyMapString": {
"promotion_campaign": "onlineOnly"
},
"links": [
{
"rel": "self",
"href": "http://localhost:9080/ccadmin/v1/promotions/promo10001"
}
],
"paymentTypes": [],
"id": "promo10001",
"filterForQualifierActedAsQualifier": null,
"evaluationLimit": -1,
"shippingMethods": [],
"dynamicPropertyMapBigString": {},
"priority": 1,
"excludedPromotions": [],
"repositoryId": "promo10001",
"promotion_campaign": "onlineOnly",
"stackingRule": null,
"dynamicPropertyMapDouble": {},
"startDate": null
}
Update an existing custom property
To update a custom property issue a PUT
request to the /ccadmin/v1/itemTypes/promotion
endpoint on the administration server with the ID of the existing custom property. The following example changes the label displayed for the promotion_campaign
property:
{
"id": "promotion", //this is the ID of the item-type item
"specifications": [
{
"id": "promotion_campaign", //this is the ID of the property
"label": "Discount Source"
}
]
}