Create custom properties for orders
This section describes how to add custom properties to orders.
This section applies to Open Storefront Framework (OSF) and Storefront Classic.
This section describes how to use the Oracle Commerce REST web services APIs to add custom properties to orders. See Use the REST APIs for information you need to know before using the services.
Understand order types
Like shopper profiles, orders include a predefined set of properties. For example, orders have properties for storing data about when the order was submitted, the cost of the items, shipping information, and so on.
Just as the properties of a shopper profile are determined by its associated shopper
type, the properties of an order are determined by its associated order type. The
order type serves as a template for the order. Currently only one order type, whose
ID is order
, is available. This order type is associated with all
Oracle Commerce orders.
You cannot create additional order types, but you can add custom properties to the
order
order type. For example, you could add a
gift_message
property that a customer can use to provide a note
to include in the package when the order items ship.
You can use the Oracle Commerce Admin API to add custom properties to the order
order type. The
Order Types resource in the Admin API includes endpoints for creating and working
with custom properties of the order
order type, and the Orders
resource in the Admin API includes endpoints that you can use to set the values of
properties of individual orders, including custom properties that have been added to
the order
order type.
When you add a custom property to the order
order type, the
property is added to all orders, including any new orders customers create and any
orders that already exist.
Note: Many of the properties of orders store either arrays or pointers to
other resources. The Order Types endpoints do not expose these properties. You can
add custom properties to the order
order type and modify them using
the Order Types endpoints, but you can only create and modify top-level scalar
properties.
View an order
To view an existing order, first log into the Admin API on the administration server using an account that has the Administrator role. For example:
POST /ccadmin/v1/mfalogin HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=admin1@example.com&password=A3ddj3w2&totp_code=365214
Then issue a GET request to the /ccadmin/v1/orders/{id}
endpoint, providing the ID of the order you want to view, and including the access token that was returned by /ccadmin/v1/mfalogin
. For example:
GET /ccadmin/v1/orders/o10008 HTTP/1.1
Authorization: Bearer <access_token>
The response shows the predefined order properties that are exposed by Oracle Commerce, and the values of the properties in the order. You can modify the values of
these properties for an order using the PUT /ccadmin/v1/orders/{id}
endpoint on the administration server.
View an order type
To view an order type, issue a GET
request to the
/ccadmin/v1/orderTypes/{id}
endpoint on the administration
server. The following example illustrates calling this endpoint with
order
(the only order type currently available) specified as
the value for id
:
GET /ccadmin/v1/orderTypes/order HTTP/1.1
Authorization: Bearer <access_token>
Add custom properties to an order type
To add custom properties to an order type, issue a PUT
request to the /ccadmin/v1/orderTypes/{id}
endpoint on the administration server. Use the following format:
- The request header must specify the
x-ccasset-language
value. - The request body is a map where each key is the name of a new property, and each value is an object that specifies the values of the attributes of the property.
- Each object is also a map, with each key being the name of an attribute and each value being the corresponding attribute value.
The attributes of order type properties that you can set through Order Types endpoints are the same as the attributes of shopper type properties you can set through Shopper Types endpoints. See Settable attributes of shopper type properties for descriptions of these properties.
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 orders 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 shows a sample request for adding a custom property to the
order
order type:
{
"properties": {
"gift_message": {
"label": "Enter an optional gift message here:",
"type": "richText",
"uiEditorType": "richText",
"internalOnly": false,
"required": false
}
} }
The following is a portion of the response that shows the new property:
{
...
"properties": {
...
"gift_message": {
"writable": true,
"localizable": false,
"label": "Enter an optional gift message here:",
"type": "richText",
"uiEditorType": "richText",
"textSearchable": false,
"multiSelect": null,
"dimension": false,
"internalOnly": false,
"default": null,
"editableAttributes": [
"textSearchable",
"multiSelect",
"dimension",
"internalOnly",
"default",
"label",
"required",
"searchable"
],
"length": 4000000,
"required": false,
"searchable": false
},
...
}
...
}