Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
Getting started
Getting started
  • Welcome to Commerce Layer
    • Guided setup
    • Manual configuration
  • API specification
  • API credentials
  • Authentication
    • Client credentials
    • Password
    • Authorization code
    • Refresh token
    • JWT bearer
    • Revoking a token
  • Roles and permissions
  • Fetching resources
  • Fetching relationships
  • Including associations
  • Sparse fieldsets
  • Sorting results
  • Pagination
  • Filtering data
  • Creating resources
  • Updating resources
  • Tagging resources
  • Deleting resources
  • Importing resources
  • Exporting resources
  • Cleaning up resources
  • External resources
    • External order validation
    • External prices
    • External shipping costs
    • External payment gateways
    • External promotions
    • External tax calculators
  • Rate limits
  • Handling errors
  • Real-time webhooks
  • Callbacks security
On this page

Including associations

How to include a resource and its associations in the same request

PreviousFetching relationshipsNextSparse fieldsets

Last updated 10 months ago

When you fetch a resource or a collection, you can include its associations in the same request, using the include query parameter. This reduces the number of roundtrips, optimizing the performances.

The value of the include parameter must be a comma-separated list of relationship paths () — make sure to avoid whitespaces before or after each comma. A relationship path is a dot-separated list of relationship names (). For each included resource you'll find in the relationships object of the response an additional data array containing their type and ID.

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 ().

Examples

Fetching an SKU and some of its associations

The following request fetches the SKU identified by the ID "xYZkjABcde" and the related prices and stock items:

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'

On success, the API responds with a 200 OK status code, returning the resource object and the included associations:

{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": { ... },
    "attributes": { ... },
    "relationships": {
      "shipping_category": { ... },
      "prices": {
        "links": { .. },
        "data": [
          {
            "type": "prices",
            "id": "pxEWUBWXLA"
          }
        ]
      },
      "stock_items": {
        "links": { ... },
        "data": [
          {
            "type": "stock_items",
            "id": "jAdEfdlvBK"
          },
          {
            "type": "stock_items",
            "id": "jpQRfJlrwN"
          }
        ]
      },
      "stock_reservations": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
      "tags": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  },
  "included": [
    {
      "id": "pxEWUBWXLA",
      "type": "prices",
      "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"
      }
    },
    {
      "id": "jAdEfdlvBK",
      "type": "stock_items",
      "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"
      }
    },
    {
      "id": "jpQRfJlrwN",
      "type": "stock_items",
      "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"
      }
    }
  ]
}

Using relationship paths

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:

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'

On success, the API responds with a 200 OK status code, returning the resource object and the included associations:

{
  "data": {
    "id": "xYZkjABcde",
    "type": "skus",
    "links": { ... },
    "attributes": { ... },
    "relationships": {
      "shipping_category": { ... },
      "prices": { ... },
      "stock_items": {
        "links": { ... },
        "data": [
          {
            "type": "stock_items",
            "id": "jAdEfdlvBK"
          },
          {
            "type": "stock_items",
            "id": "jpQRfJlrwN"
          }
        ]
      },
      "stock_reservations": { ... },
      "delivery_lead_times": { ... },
      "sku_options": { ... },
      "attachments": { ... },
      "events": { ... },
      "tags": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  },
  "included": [
    {
      "id": "jAdEfdlvBK",
      "type": "stock_items",
      "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": {
          "links": { ... },
          "data": null
        },
        "stock_reservations": { ... },
        "attachments": { ... }
      },
      "meta": {
        "mode": "test",
        "organization_id": "EnAvaFOrRe"
      }
    },
    {
      "id": "jpQRfJlrwN",
      "type": "stock_items",
      "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": {
          "links": { ... },
          "data": {
            "type": "reserved_stocks",
            "id": "noJnMSBLXo"
          }
        },
        "stock_reservations": { ... },
        "attachments": { ... }
      },
      "meta": {
        "mode": "test",
        "organization_id": "EnAvaFOrRe"
      }
    },
    {
      "id": "noJnMSBLXo",
      "type": "reserved_stocks",
      "links": { ... },
      "attributes": {
        "quantity": 5,
        "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"
      }
    }
  ]
}

You can request to include associations also when or resources.

creating
updating
see example
see example
see examples