Custom Order Item Data

Custom data is key/value information that may vary in use depending on implementation needs. For instance, if items need to be marked as “final sale” to indicate that they are not returnable, then custom data with the key of “finalSale” and a value of “true” (as a string) can be provided. Then, the system could be configured to suppress printing return labels for order items with this flag.

To edit custom order item data after the creation of an order and associated items, an additional API is available to manage that data directly and more efficiently. POST, PUT, DELETE, and GET requests are all supported by this Custom Order Item Data API to manage that information.

Although this is related to the Custom Order Data API, this particular API pertains only to the custom data applied to a line item or product. Custom data made at the whole order level should be managed through the Custom Order Data API.

Note that the request body and parameter schemas outlined in this guide are the exact same as in the previous version of OMS, as the Unified Commerce platform supports backwards compatibility for this API. The only change to this request is the format of the base endpoint, as shown in the below table. Remember to provide the x-vol-tenant key for authentication in the headers.

Required Parameters

These parameters are necessary for the Custom Order Item Data API to return a successful response for POST and PUT requests, which require a body.

Optional Parameters

Other possible parameters can be provided to specify other details about the order and item.

Add Custom Order Item Data

The POST request will add a new custom data record to an existing order item. The header specifies the IDs of the item being edited and the order that it belongs to.

The header:

https://{tenantId}-translation.mozu.com/api/v2/orderItem/000000/customData/?orderID=012345

Note that only the name and value of the custom data are required. The item and order IDs are assumed from the header and the custom data ID will be generated by OMS and returned in the response.

The body:

 {
  "name": "Example Data",
  "value": "This is sample custom data."
 }

Update Custom Order Item Data

The PUT request will update an existing custom data record. The header must specify the order and item IDs, but also includes the specific custom data ID before the order ID is appended. This custom ID can be found in the response of any call that returns order information.

The header:

https://{tenantId}-translation.mozu.com/api/v2/orderItem/00000/customData/999999?orderID=012345

Although the name of the custom data record is included in the body as shown below, it must be the name of an existing record and cannot be changed. Only the value may be different from the existing record.

The body:

 {
  "name": "Example Data",
  "value": "This is new text for the sample custom data."
 }

Delete Custom Order Item Data

The DELETE request will remove an existing custom data record. There is no required body of the request, as the header specifies which data element is being deleted based on the IDs that are provided. The custom data ID can be found in the response of any call that returns order information.

The header:

https://{tenantId}-translation.mozu.com/api/v2/orderItem/000000/customData/999999?orderID=012345

This data will be removed and a “204 No Content” response message will be returned to indicate such.

Get Custom Order Item Data

The GET request will simply return the custom data of an item. This request can be made in two ways, as shown below. The first header only specifies item and order IDs, so the response will return all custom order item data blocks that belong to that item in the particular order. The second option specifies a particular orderItemCustomDataID, so only the block with that ID will be returned.

The headers:

https://{tenantId}-translation.mozu.com/api/v2/orderItem/000000/customData/?orderID=012345

https://{tenantId}-translation.mozu.com/api/v2/orderItem/000000/customData/999999?orderID=012345

The information in the body of the response is also often returned as the response of other requests that do make edits, such as the PUT call. A 404 Error will be returned if the user tries to access the data of an order that does not exist.

The body:

{ 
  "orderItemCustomDataID": 999999, 
  "orderID": 012345, 
  "itemID": 000000, 
  "manufacturerID": 10101, 
  "catalogID": 0, 
  "name": "Custom Data", 
  "value": "This is sample custom data." 
}