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.