Create Custom Properties for Promotions

This section describes how to use the Retail Digital Commerce REST web services APIs to add custom properties to promotions.

This section applies to Open Storefront Framework (OSF).

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 Retail Digital 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 Retail Digital 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"
    }
]
}