# Including

Source: https://developers.swell.is/backend-api/querying/including

Use the `include` parameter to include results in a query that may or may not be related to the records being retrieved. For example, when you know there's a need to retrieve two similar records at a time in order to reduce the number of API calls a page would need.

Use `include.params` to specify relative values to the records returned by the main query. The actual field values will be substituted by the API. Use `include.data` to specify literal values for filtering the included result.

An include can also define a `conditions` object evaluated against each parent record—the included query only runs for records that match.

Each key in the `include` object names the field the result is attached to, and each entry needs a `url`. On a list query the included query runs once per record, and its result is attached to that record. A record receives `null` when its `conditions` don't match, or when a placeholder in the `url` can't be resolved from the record.

**Include examples**

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

// Include a second, unrelated query alongside the main result
await swell.get('/products', {
  limit: 25,
  include: {
    on_sale: {
      url: '/products',
      data: {
        limit: 5,
        where: { sale: true }
      }
    }
  }
});

// Use params to pass a value from each record into the included query.
// Here each account's id is used to fetch that account's orders.
await swell.get('/accounts', {
  limit: 25,
  include: {
    orders: {
      url: '/orders',
      params: { account_id: 'id' },
      data: {
        limit: 5,
        fields: 'number, grand_total'
      }
    }
  }
});

// Substitute a record value directly into the url
await swell.get('/orders', {
  limit: 25,
  include: {
    customer: {
      url: '/accounts/{account_id}',
      data: {
        fields: 'name, email'
      }
    }
  }
});

// Run the include only for records that match conditions.
// Accounts with no orders receive `orders: null`.
await swell.get('/accounts', {
  limit: 25,
  include: {
    orders: {
      url: '/orders',
      params: { account_id: 'id' },
      conditions: {
        order_count: { $gt: 0 }
      },
      data: { limit: 5 }
    }
  }
});

// Include more than one query in the same request
await swell.get('/accounts', {
  limit: 25,
  include: {
    orders: {
      url: '/orders',
      params: { account_id: 'id' },
      data: { limit: 5 }
    },
    subscriptions: {
      url: '/subscriptions',
      params: { account_id: 'id' },
      data: { limit: 5 }
    }
  }
});
```

Each include adds 1 point to the request's weight, and an include nested inside another include's `data` adds its own. See [Rate limits](https://developers.swell.is/backend-api/rate-limits) for how weight is counted.

→ See the [Advanced queries guide](https://developers.swell.is/guides/advanced-queries) for a worked example using `include` with `params` and `data`.

## Example request

**Example query using `include`**

**cURL**

```bash
$ curl https://api.swell.store/orders/5407e0929fe97f9d4c712a5f?include[fulfilled_giftcards][url]=/giftcards&include[fulfilled_giftcards][params][order_id]=id&include[fulfilled_giftcards][data][balance][$gt]=0
  -u store-id:secret-key
```

**Node**

```javascript
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/orders/{id}', {
  id: '5407e0929fe97f9d4c712a5f',
  include: {
    fulfilled_giftcards: {
      url: '/giftcards',
      params: {
        order_id: 'id',
      },
      data: {
        balance: { $gt: 0 },
      },
    },
  },
});
```

**PHP**

```php
<?php $swell = new \\Swell\\Client('store-id', 'secret-key');

$swell->get('/orders/{id}', [
  'id' => '5407e0929fe97f9d4c712a5f',
  'include' => [
    'fulfilled_giftcards' => [
      'url' => '/giftcards',
      'params' => [
        'order_id' => 'id'
      ],
      'data' => [
        'balance' => [ '$gt' => 0 ]
      ]
    ]
  ]
]);
```

## Example response

```json
{
  "id": "5407e0929fe97f9d4c712a5f",
  "fulfilled_giftcards": [
    {
      "id": "5407e0929fe97f9d4c712a5g",
      "balance": 25
    },
    {...}
  ],
  ...
}
```