Commerce Layer will be proud to sponsor the next JAMstack Conf in London — 09-10 July, 2019 🎉 Stay tuned!

API REFERENCE

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.