Create custom properties for orders

This section describes how to add custom properties to orders.

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=[e-mail]&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
         },
         ...
     }
     ...
}