Hierarchical Object Design

Work with nested objects and relationships in API responses

Objects are often associated to other objects in the Payload API. When requesting an object like an invoice, any related objects, like line items, will be included as nested objects within the parent invoice object's response. This works recursively to create a hierarchical representation of an object's relationships.

Example Hierarchical Response

import payload
pl = payload.Session('secret_key_3bW9...', api_version='v2')
 
invoice = pl.Invoice.get('inv_3bW9JNCxdMPBUV510Gf9E')
print(invoice.json())

Response:

{
  "id": "inv_3bW9JNCxdMPBUV510Gf9E",
  "object": "invoice",
  "amount": 1000,
  "description": "INV - 401",
  "due_date": "2020-02-01",
  "type": "membership",
  "items": [
    {
      "id": "item_3bW9JND5cyoQVPVcCwOkC",
      "object": "line_item",
      "amount": 100,
      "date_incurred": "2020-01-10 20:41:40",
      "description": "Item 1",
      "invoice_id": "inv_3bW9JNCxdMPBUV510Gf9E",
      "type": "item",
      "entry_type": "charge"
    },
    {
      "id": "item_3bW9JND5l6QlItvoXYUXA",
      "object": "line_item",
      "amount": -100,
      "description": "Payment",
      "invoice_id": "inv_3bW9JNCxdMPBUV510Gf9E",
      "entry_type": "payment",
      "payment": {
        "id": "txn_3bW9JMonPXbEWWcNYrIm0",
        "object": "transaction",
        "account_id": "acct_3bW9JMoMCmrCjZByd1Wt6",
        "amount": 100,
        "processing_id": "acct_3bW9JMoN07ApUDouuPdB2",
        "description": "INV - 401 Payment",
        "fee": 1.95,
        "created_at": "2020-02-20 17:21:15",
        "payment_method": {},
        "payment_method_id": "pm_3bW9JMoQUQiZaEV8TgPUO",
        "status": "processed",
        "type": "payment"
      }
    }
  ]
}

Access Nested Objects Directly

Nested objects can be accessed and manipulated directly either through an embedded object resource path, or, if the object id is known, you can access and modify it directly through the object's full resource path.

Embedded Object Resource Path

https://api.payload.com/invoices/inv_3bW9JNCxdMPBUV510Gf9E/items

Full Object Resource Path

https://api.payload.com/line_items/item_3bW9JND5cyoQVPVcCwOkC

Changes to a Nested Object Tree

You can make changes to nested objects by editing the nested object tree in an update operation.

Creating a New Nested Object

New objects added into a nested object tree without an id attribute will get created on either a create or update request.

Example: Adding a new line item to an invoice

{
  "id": "inv_3bW9JNCxdMPBUV510Gf9E",
  "items": [
    {
      "description": "New Item",
      "amount": 50,
      "type": "item"
    }
  ]
}

Updating an Existing Nested Object

To update attributes of a nested object, pass the updated fields along with the object's id in the correct nested position within the parent object in an update operation.

Example: Updating an existing line item

{
  "id": "inv_3bW9JNCxdMPBUV510Gf9E",
  "items": [
    {
      "id": "item_3bW9JND5cyoQVPVcCwOkC",
      "description": "Updated Item Description",
      "amount": 150
    }
  ]
}

Deleting an Existing Nested Object

Remove the nested object from the parent's object tree in an update operation and the object will be deleted.

Example: Removing a line item by excluding it from the items array

{
  "id": "inv_3bW9JNCxdMPBUV510Gf9E",
  "items": [
    // Only include the items you want to keep
    // Excluded items will be deleted
  ]
}