See related
No related articles

Use Klass relationships to create nested Order objects

Last Update: Sep 2024 • Est. Read Time: 5 MIN
To check plan availability, see the pricing page.

If 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 typesAdmins can access Klass settings.


In this article

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 for items.
  • 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.