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
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 for how weight is counted.

→ See the Advanced queries guide for a worked example using include with params and data.