OMS DOCUMENTATIONRESOURCE CENTER

These guides provide examples for many tasks that a developer will need to be familiar with during implementation.

KIBO OMS DEVELOPMENT

Documentation

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, OMS 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.

Version2.0
Callhttps://integration.shopatron.com/api/v2/orderItem/{orderItemID}/customData
Supported FormatsJSON
HTTP MethodPOST, PUT, DELETE, GET
Schemahttps://integration.shopatron.com/api/v2/schema/orderItem/orderItemCustomData.json

The .json address above can be used to access the schema within Postman. An example use of the Custom Order Item Data API follows below, or view the schema.

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.

ParameterTypeDescription
namestringThe name of the value in the value store of custom data. The minimum length is 1 and the maximum length is 100.
valuestringThe data for the value portion of the key/value store of custom data. The minimum length is 1 and the maximum length is 1000.

Optional Parameters

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

ParameterTypeDescription
orderItemCustomDataIDintegerA unique identifier for each custom data record.
orderIDintegerA unique identifier for the order that the item belongs to. The minimum value is “1”.
itemIDintegerA unique identifier for the order item that the data applies to. The minimum value is “1”.
manufacturerIDintegerA unique identifier for the manufacturer that the order belongs to. The minimum value is “1”.
catalogIDintegerThe catalog number for the manufacturer. The minimum value is “0”.

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://integration.shopatron.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://integration.shopatron.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://integration.shopatron.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://integration.shopatron.com/api/v2/orderItem/000000/customData/?orderID=012345
https://integration.shopatron.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."
}