Create custom properties for line items

This section describes how to add custom properties to line items.

This section describes how to use the Oracle Commerce REST web services APIs to add custom properties to line items. See Use the REST APIs for information you need to know before using the services.

View the commerceItem item type

Order line items are stored internally as instances of the commerceItem item type. You can view this item type with the following call:

GET /ccadmin/v1/itemTypes/commerceItem HTTP/1.1
Authorization: Bearer <access_token>

The following example shows a portion of the response representing one of the commerceItem properties. Each property has a group of attributes whose values control the behavior associated with the property:

...
"productId": {
  "length": 254,
  "label": "Product id",
  "type": "shortText",
  "required": false,
  "searchable": false,
  "writable": true,
  "internalOnly": false,
  "uiEditorType": "shortText",
  "default": null,
  "audienceVisibility": null,
  "localizable": false,
  "textSearchable": false,
  "dimension": false,
  "multiSelect": null,
  "editableAttributes": [
    "internalOnly",
    "default",
    "audienceVisibility",
    "textSearchable",
    "label",
    "dimension",
    "required",
    "searchable",
    "multiSelect"
  ]
}
...

You can use the updateItemType endpoint to modify the commerceItem item type:

• Modify existing properties by changing the values of their attributes.
• Create custom properties by specifying their attributes.

See Settable attributes of shopper type properties for descriptions of these attributes.

The next section provides an example of creating a custom property.

Add custom properties to the commerceItem item type

You can use the updateItemType endpoint in the Commerce Admin API to add custom properties to the commerceItem item type. When you add a custom property to the commerceItem item type, the property is added to all line items in all orders.

Note that sites that sell configurable products such as telecommunications plans may use certain item types that extend the commerceItem item type. When you add custom properties to the commerceItem item type, they are automatically added to these extensions as well. For example, you could add a fulfillment status property for separately tracking each line item in a service plan.

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 the commerceItem item type in the future. The endpoint produces an error if you attempt to create a custom property without an underscore in its ID.

The following example illustrates using the updateItemType endpoint to add a custom property. Note that the request header must specify the x-ccasset-language value:

PUT /ccadmin/v1/itemTypes/commerceItem  HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en

{
  "id": "commerceItem",
  "specifications": [
    {
       "id": "monogram_initials",
       "label": "Initials for monogramming",
       "type": "shortText",
       "uiEditorType": "shortText",
       "internalOnly": false,
       "required": false,
       "default": null
    }
  ]
}

The response includes the custom property you added:

...
{
      "length": 254,
      "label": "Initials for monogramming",
      "type": "shortText",
      "required": false,
      "searchable": false,
      "writable": true,
      "internalOnly": false,
      "uiEditorType": "shortText",
      "default": null,
      "audienceVisibility": null,
      "localizable": false,
      "textSearchable": false,
      "id": "monogram_initials",
      "dimension": false,
      "multiSelect": null,
      "editableAttributes": [
        "internalOnly",
        "default",
        "audienceVisibility",
        "textSearchable",
        "label",
        "dimension",
        "required",
        "searchable",
        "multiSelect"
      ]
    }
...

Note that for a commerceItem custom property, you will typically want to set default to null and required to false, so that the property is not set unless the shopper explicitly chooses to set it.