Setup Bonus Items

1. Create a bundle item in your store configuration

2. Add the main item as a component of the bundle

3. Add bonus items as separate components within the same bundle

4. Set the price of bonus items to null to distinguish them from primary items

5. Configure the bundle with appropriate SKUs for each component item

Usage

When a customer purchases a bundle containing bonus items, all items (both primary and bonus) will be included in the item.add webhook payload within the nested_items array. The webhook structure will look like this:

"event_data": {
  "item_id": "itm_XXXXXXXXXX",
  "items": [
    {
      "currency": "USD",
      "description": "Example bundle description",
      "id": "itm_XXXXXXXXXX",
      "name": "Example Bundle",
      "nested_items": [
        {
          "description": "Main item",
          "id": "itm_XXXXXXXXXX",
          "name": "Primary Item",
          "quantity": 1,
          "sku": "primary_item_sku",
          "price": 999
        },
        {
          "description": "Bonus item",
          "id": "itm_XXXXXXXXXX",
          "name": "Bonus Item",
          "quantity": 100,
          "sku": "bonus_item_sku",
          "price": null
        }
      ],
      "price": 999,
      "quantity": 1,
      "sku": "bundle_sku",
      "type": "bundle"
    }
  ]
}

To distinguish bonus items from primary items, filter items where price: null. You can also use the trigger order.paid to ensure you're only processing paid purchases and not free items from other sources like daily rewards or loyalty programs.

Note: The nested_items functionality is being added to the Get Order and Get Payments APIs and will be available in production soon.