Including associations

When you fetch a resource or a collection, you can include its associations in the same request. This reduces the number of roundtrips, optimizing the performances. For example, the following request fetches a single SKU and the related prices and stock items:

GET /api/skus/1234?include=prices,stock_items HTTP/1.1
Accept: application/vnd.api+json
Note: you can request to include associations also when creating or updating resources.

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

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "id": "1234",
    "type": "skus",
    "links": {...},
    "attributes": {...},
    "relationships": {
      "shipping_category": {
        "links": {...}
      },
      "prices": {
        "links": {...},
        "data": [
          {
            "type": "prices",
            "id": 1234
          }
        ]
      },
      "stock_items": {
        "links": {...},
        "data": [
          {
            "type": "stock_items",
            "id": 1234
          }
        ]
      },
      "delivery_lead_times": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  },
  "included": [
    {
      "data": {
        "id": "1234",
        "type": "prices",
        "links": {
          "self": "https://your-brand.commercelayer.io/api/prices/1234"
        },
        "attributes": {
          "currency_code": "EUR",
          "sku_code": "TSHIRTMM000000FFFFFFXLXX",
          "amount_cents": "10000",
          "amount_float": "100.0",
          "formatted_amount": "€100,00",
          "compare_at_amount_cents": "13000",
          "compare_at_amount_float": "130.00",
          "formatted_compare_at_amount": "€130,00",
          "id": "1234",
          "created_at": "2018-01-01T12:00:00.000Z",
          "updated_at": "2018-01-01T12:00:00.000Z",
          "reference": "ANYREFEFERNCE",
          "metadata": {
            "foo": "bar"
          }
        },
        "relationships": {
          "price_list": {
            "links": {
              "self": "https://your-brand.commercelayer.io/api/prices/1234/relationships/price_list",
              "related": "https://your-brand.commercelayer.io/api/prices/1234/price_list"
            }
          },
          "sku": {
            "links": {
              "self": "https://your-brand.commercelayer.io/api/prices/1234/relationships/sku",
              "related": "https://your-brand.commercelayer.io/api/prices/1234/sku"
            }
          }
        },
        "meta": {
          "mode": "test"
        }
      }
    },
    {
      "data": {
        "id": "1234",
        "type": "stock_items",
        "links": {
          "self": "https://your-brand.commercelayer.io/api/stock_items/1234"
        },
        "attributes": {
          "sku_code": "TSHIRTMM000000FFFFFFXLXX",
          "quantity": "100",
          "id": "1234",
          "created_at": "2018-01-01T12:00:00.000Z",
          "updated_at": "2018-01-01T12:00:00.000Z",
          "reference": "ANYREFEFERNCE",
          "metadata": {
            "foo": "bar"
          }
        },
        "relationships": {
          "stock_location": {
            "links": {
              "self": "https://your-brand.commercelayer.io/api/stock_items/1234/relationships/stock_location",
              "related": "https://your-brand.commercelayer.io/api/stock_items/1234/stock_location"
            }
          },
          "sku": {
            "links": {
              "self": "https://your-brand.commercelayer.io/api/stock_items/1234/relationships/sku",
              "related": "https://your-brand.commercelayer.io/api/stock_items/1234/sku"
            }
          }
        },
        "meta": {
          "mode": "test"
        }
      }
    }
  ]
}

The value of the include parameter MUST be a comma-separated list of relationship paths. A relationship path is a dot-separated list of relationship names. For example, a relationship path could be prices.price_list where prices is a relationship listed under an sku resource object, and price_list is a relationship listed under a price resource object.

Get our machine-readable JSON schema that follows the OpenAPI Specification (formerly Swagger).

Get our Postman collection in one click and start making real calls to Commerce Layer API in minutes.

Get in touch with our support team if you have any questions or want to learn more about Commerce Layer.