Use Klass relationships to create nested Order objects
Last Update: Sep 2024 • Est. Read Time: 5 MINIf you're integrating an order system in Kustomer, you're likely to come across an example of Kustomer's flexible object model through the use of nested objects. Nested objects (or sub-objects) can be rendered in a Klass View, and might include objects like Shipments, or line items that would belong to an Order.
The easiest way to start taking advantage of Order objects would be to browse the Kustomer App Directory and install an ecommerce app integration, which would set these objects up automatically.
If you're interested in setting this up manually, this article will walk through multiple methods of setting up klasses with nested objects using the scenario of an orders <-> items being a one-to-many relationship.
Who can access this feature? | |
User types | Admins can access Klass settings. |
In this article
- Automatic: App integrations
- Manual Option A: Using the default data field on custom objects (recommended)
- Manual Option B: Creating and relating multiple klasses
- FAQ
Automatic: App integrations
Kustomer offers a variety of app integrations in the Kustomer App Directory. This is the easiest way to get integrated with services like Shopify, BigCommerce, Magento, and more. Learn more about our ecommerce apps in the Kustomer Help Center.
Manual Option A: Using the default data field on custom objects (recommended)
Note: If you choose to set up orders manually, we highly recommend using Option A because it's simpler and requires less configuration. Option B should only be considered if your use case requires it.
1. Go to Settings > Platform > Klasses and create an Order
klass in Kustomer, if one doesn't exist already. (These are created automatically if you've installed an ecommerce app integration.) This will expose endpoints like /v1/customers/:id/orders
, etc.
A POST
of an order with many items to /v1/customers/:id/klasses/order
would look like the example shown below. Note that we are populating the data
field. This field can store the raw JSON data as it is represented in the proprietary system.
{ "title": "Order #1", "externalId": "1" "data": { "line_items": [ { "name": "T-Shirt", "price": 20 }, { "name": "Socks", "price": 5 } ] } }
Objects implemented with this method would look like this on the customer's timeline in Kustomer:
2. In order to create the klass view, go to Settings> Platform > Klasses, then select your Order klass and and press the Edit icon.
3. Select the Timeline Layout tab, and then Edit the timeline card.
4. Paste in this starter code snippet.
<Segment> <Grid> <Column size="ten"> <Grid style={{ padding: '5px 20px', background: '#F7F8F8', border: '1px solid #EAEAEA' }}> <Column> <Grid style={{ fontWeight:'bold', opacity:'.5' }}> <Column size="five" >Item Name</Column> <Column size="five">Price</Column> </Grid> <hr /> {_.map(_.get(kobject, "data.line_items", []), (item) => ( <Grid> <Column size="five">{item.name}</Column> <Column size="five">{item.price}</Column> </Grid>))} </Column> </Grid> </Column> </Grid> </Segment>
5. Press Save Changes to finish editing the timeline card.
Pros of this method:
- No need to define klass relationships beforehand
- No need for additional API calls to create additional item objects - we can include everything in our
POST
call to/v1/customers/:id/klasses/orders
- Display data about an item within an order object instead of making users navigate to a separate object
- Cleaner customer timeline in Kustomer
Cons of this method:
- Data in the
data
object are currently not indexed and therefore cannot be searched or reported on.
Manual Option B: Creating and relating multiple klasses
1. Create an Order
klass in Kustomer. This will expose endpoints like /v1/klasses/orders
, /v1/customers/:id/orders
, etc.
2. Create an item
klass in Kustomer. This will expose endpoints like /v1/klasses/items
, /v1/customers/:id/items
, etc.
We now need to define the relationship between the klasses.
3. To define the relationships of an Order
object having many Items
, make the following PUT
request to https://api.kustomerapp.com/v1/metadata/kobject.order
(the Rel suffix is required here):
{ "relationships": { "itemsRel": { "displayName": "Order Items", "target": "kobject.items", "multi": true } } }
4. To define the relationships of an Item
object belonging to one Order
object, make the following PUT
request to https://api.kustomerapp.com/v1/metadata/kobject.items
(the Rel suffix is required here):
{ "relationships": { "orderRel": { "displayName": "Order", "target": "kobject.order", "multi": false } } }
5. We can now create/update instances of an object that are related to other items:
A minimalist POST
of an order with many items to /v1/customers/:id/klasses/order
would look like this:
{ "title": "Order #1", "externalId": "1" "data": {}, "custom": { "itemsRel":["5af9ac1bd672767b2f0a9869","5af9ac21deb0106530702456","5af9ac26deb010553b7024aa"] } }
Likewise, an item that belongs to an order would have a POST
to /v1/customers/:id/klasses/items
and look like this:
{ "title": "Item #1", "externalId": "1", "data": {}, "custom": { "orderRel": "5af9ad0cd67276ffe30aa6c0" } }
Alternatively, you can also try making a POST
to /v1/klasses/orders/:id/itemsRel
without the custom
object to create the nested object.
The ID in orderRel
and itemsRel
represent the IDs of custom objects that exist in Kustomer. If you do not have the custom objects you want to relate when creating another object (ex: you are creating your order
custom object before its respective item
objects) yet then you can always make a PUT
request to /v1/klasses/:klassName/:id
to add the related objects later.
Please note that setting an array of multiple objects (like itemsRel
) will overwrite the existing itemsRel
array on that object instead of appending to it.
Objects would look like this on the customer's timeline:
Pros of this method:
- Splitting objects out into multiple Klasses means Kustomer admins can build Saved Search queries on the custom fields in the object. This is currently not supported by nested
Obj
custom fields described below. - In the above example, the Order Items get to be their own entity with their own set of Klass endpoints. Ex: if you wanted to just find an Order Item object by its external ID, then you could make a request to
/v1/klasses/items/externalId={externalId}
- No nesting limitations like the
Obj
custom field
Cons of this method:
- Requires defining the relationships beforehand
- You have to manage creating/updating each object with its relationships, which ultimately means more API calls as opposed to a create/update for a single Order object that has an
Obj
custom field foritems
. - More objects on the timeline can potentially add a lot of clutter for agents viewing the timeline.
FAQ
Q: What is the purpose of the data
field?
The data
field can be any JSON object with any amount of nesting. We do not index on the items in this field so it will not be searchable. However, this data object will be available for rendering in a Klass View.