# Including associations

When you fetch a resource or a collection, you can include its associations in the same request, using the `include` query parameter.

{% hint style="warning" %}
The value of the `include` parameter must be a comma-separated list of relationship paths ([see example](#fetching-an-sku-and-some-of-its-associations)) — make sure to avoid whitespaces before or after each comma. A relationship path is a dot-separated list of relationship names ([see example](#using-relationship-paths)). For each included resource you'll find in the `relationships` object of the response an additional `data` array containing their type and ID.
{% endhint %}

{% hint style="info" %}
Included resources **cannot be sorted** or **filtered**. Sort rules and filters apply to the parent resource (e.g. `skus` in the examples below) or to related resources ([see examples](https://docs.commercelayer.io/core/filtering-data#filtering-related-resources)).
{% endhint %}

### Examples

#### Fetching an SKU and some of its associations

{% tabs %}
{% tab title="Request" %}
The following request fetches the SKU identified by the ID "xYZkjABcde" and the related prices and stock items:

```sh
curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde?include=prices,stock_items' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the resource object and the included associations:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": { ... },
    "attributes": { ... },
    "relationships": {
      "shipping_category": { ... },
<strong>      "prices": {
</strong>        "links": { .. },
<strong>        "data": [
</strong><strong>          {
</strong><strong>            "type": "prices",
</strong><strong>            "id": "pxEWUBWXLA"
</strong><strong>          }
</strong><strong>        ]
</strong>      },
<strong>      "stock_items": {
</strong>        "links": { ... },
<strong>        "data": [
</strong><strong>          {
</strong><strong>            "type": "stock_items",
</strong><strong>            "id": "jAdEfdlvBK"
</strong><strong>          },
</strong><strong>          {
</strong><strong>            "type": "stock_items",
</strong><strong>            "id": "jpQRfJlrwN"
</strong><strong>          }
</strong><strong>        ]
</strong>      },
      "stock_reservations": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
      "tags": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  },
  "included": [
    {
<strong>      "id": "pxEWUBWXLA",
</strong><strong>      "type": "prices",
</strong>      "links": { ... },
      "attributes": {
        "currency_code": "USD",
        "sku_code": "TSHIRTMM000000FFFFFFMXXX",
        "amount_cents": 3480,
        "amount_float": 34.8,
        "formatted_amount": "$34.80",
        "compare_at_amount_cents": 4524,
        "compare_at_amount_float": 45.24,
        "formatted_compare_at_amount": "$45.24",
        "created_at": "2019-05-14T10:36:53.987Z",
        "updated_at": "2019-05-14T10:36:53.987Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "price_list": { ... },
        "sku": { ... },
        "price_tiers": { ... },
        "price_volume_tiers": { ... },
        "price_frequency_tiers": { ... },
        "attachments": { ... }
      },
      "meta": {
        "mode": "test",
        "organization_id": "EnAvaFOrRe"
      }
    },
    {
<strong>      "id": "jAdEfdlvBK",
</strong><strong>      "type": "stock_items",
</strong>      "links": { ... },
      "attributes": {
        "sku_code": "TSHIRTMM000000FFFFFFMXXX",
        "quantity": 76,
        "created_at": "2019-05-14T10:36:53.980Z",
        "updated_at": "2019-05-14T10:36:53.980Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_location": { ... },
        "sku": { ... },
        "reserved_stock": { ... },
        "stock_reservations": { ... },
        "attachments": { ... }
      },
      "meta": {
        "mode": "test",
        "organization_id": "EnAvaFOrRe"
      }
    },
    {
<strong>      "id": "jpQRfJlrwN",
</strong><strong>      "type": "stock_items",
</strong>      "links": { ... },
      "attributes": {
        "sku_code": "TSHIRTMM000000FFFFFFMXXX",
        "quantity": 28,
        "created_at": "2019-05-14T10:36:53.993Z",
        "updated_at": "2019-05-14T10:36:53.993Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_location": { ... },
        "sku": { ... },
        "reserved_stock": { ... },
        "stock_reservations": { ... },
        "attachments": { ... }
      },
      "meta": {
        "mode": "test",
        "organization_id": "EnAvaFOrRe"
      }
    }
  ]
}
</code></pre>

{% endtab %}
{% endtabs %}

#### Using relationship paths

{% tabs %}
{% tab title="Request" %}
The following request features the relationship path `stock_items.reserved_stock` as the value of the include parameter, where `stock_items` is a relationship listed under the SKU resource object, and `reserved_stock` is a relationship listed under the stock item resource object:

```bash
curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus/xYZkjABcde?include=stock_items.reserved_stock' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the resource object and the included associations:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": { ... },
    "attributes": { ... },
    "relationships": {
      "shipping_category": { ... },
      "prices": { ... },
<strong>      "stock_items": {
</strong>        "links": { ... },
<strong>        "data": [
</strong><strong>          {
</strong><strong>            "type": "stock_items",
</strong><strong>            "id": "jAdEfdlvBK"
</strong><strong>          },
</strong><strong>          {
</strong><strong>            "type": "stock_items",
</strong><strong>            "id": "jpQRfJlrwN"
</strong><strong>          }
</strong><strong>        ]
</strong>      },
      "stock_reservations": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
      "tags": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  },
  "included": [
    {
<strong>      "id": "jAdEfdlvBK",
</strong><strong>      "type": "stock_items",
</strong>      "links": { ... },
      "attributes": {
        "sku_code": "TSHIRTMM000000FFFFFFMXXX",
        "quantity": 76,
        "created_at": "2019-05-14T10:36:53.980Z",
        "updated_at": "2019-05-14T10:36:53.980Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_location": { ... },
        "sku": { ... },
<strong>        "reserved_stock": {
</strong>          "links": { ... },
<strong>          "data": null
</strong>        },
        "stock_reservations": { ... },
        "attachments": { ... }
      },
      "meta": {
        "mode": "test",
        "organization_id": "EnAvaFOrRe"
      }
    },
    {
<strong>      "id": "jpQRfJlrwN",
</strong><strong>      "type": "stock_items",
</strong>      "links": { ... },
      "attributes": {
        "sku_code": "TSHIRTMM000000FFFFFFMXXX",
        "quantity": 28,
        "created_at": "2019-05-14T10:36:53.993Z",
        "updated_at": "2019-05-14T10:36:53.993Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_location": { ... },
        "sku": { ... },
<strong>        "reserved_stock": {
</strong>          "links": { ... },
<strong>          "data": {
</strong><strong>            "type": "reserved_stocks",
</strong><strong>            "id": "noJnMSBLXo"
</strong><strong>          }
</strong>        },
        "stock_reservations": { ... },
        "attachments": { ... }
      },
      "meta": {
        "mode": "test",
        "organization_id": "EnAvaFOrRe"
      }
    },
    {
<strong>      "id": "noJnMSBLXo",
</strong><strong>      "type": "reserved_stocks",
</strong>      "links": { ... },
      "attributes": {
<strong>        "quantity": 5,
</strong>        "created_at": "2023-07-17T10:29:13.433Z",
        "updated_at": "2023-07-17T10:29:13.441Z",
        "reference": null,
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "stock_item": { ... },
        "sku": { ... },
        "stock_reservations": { ... },
      "meta": {
        "mode": "test",
        "organization_id": "EnAvaFOrRe"
      }
    }
  ]
}
</code></pre>

{% endtab %}
{% endtabs %}

{% hint style="info" %}
You can request to include associations also when [creating](https://docs.commercelayer.io/core/creating-resources) or [updating](https://docs.commercelayer.io/core/updating-resources) resources.
{% endhint %}