To add custom properties to a promotion, issue a PUT request to the /ccadmin/v1/itemTypes/promotion/{id} 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 Using Oracle Commerce Cloud.

The following is a sample request to create a custom property named campaign. Note that shortText is the only value supported for the type attribute of a promotion property:

{
  "specifications": [
    {
      "id": "campaign",
      "label": "Campaign",
      "type": "shortText",
      "required": false,
      "uiEditorType": "shortText",
      "localizable": false,
      "includeInDiscountInfoJson": true
    }
  ]
}

The following is an example response with the new 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",
    "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": "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 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"
    }
  },
  "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",
  "campaign": "onlineOnly",
  "stackingRule": null,
  "dynamicPropertyMapDouble": {},
  "startDate": null
}