This is the documentation for 2021-02-23 but the latest version is 2022-02-01. You can switch versions in the menu.

Expanding Objects

Many objects contain the id of a related object in their response properties. For example, a Product may have associated Variant ids. Those objects can be expanded inline with the expand request parameter. Objects that can be expanded are noted in this documentation.

You can expand recursively by specifying nested fields after a dot (.). For example, requesting items.variant on an order will expand the variant property into a full variant object.

You can expand multiple objects at once by separating them with a comma.

Variants Not Expanded

Request

GET /products/1 HTTP/1.1

Response

{
    "is_test": false,
    "id": 1,
    "title": "qui ut nemo",
    "description": "Autem nesciunt ipsam excepturi non distinctio quas ullam placeat. Quam quidem rerum veniam corrupti velit aperiam non. Repudiandae rem incidunt atque optio vero et voluptatem. Fuga et quos in ipsa.",
    "created_at": "2017-11-15T08:07:48+00:00",
    "updated_at": "2017-11-15T08:07:48+00:00",
    "variants": [
        90,
        92,
        94,
    ]
}

Variants Expanded

Request

GET /products/1?expand=variants HTTP/1.1

Response

{
    "is_test": false,
    "id": 1,
    "title": "qui ut nemo",
    "description": "Autem nesciunt ipsam excepturi non distinctio quas ullam placeat. Quam quidem rerum veniam corrupti velit aperiam non. Repudiandae rem incidunt atque optio vero et voluptatem. Fuga et quos in ipsa.",
    "created_at": "2017-11-15T08:07:48+00:00",
    "updated_at": "2017-11-15T08:07:48+00:00",
    "variants": [
        {
            "id": 90,
            "total": 101.7,
            "price": 85.46,
            "tax": 16.24,
            "tax_rate": 19,
            "attributes": [
                {
                    "name": "color",
                    "value": "RoyalBlue"
                },
                {
                    "name": "size",
                    "value": "S"
                }
            ],
            "origin": {
                "code": "0635579894134"
            },
            "media_id": 607,
            "views": {
                "back": {
                    "composite_media_id": 609,
                    "customizations": []
                },
                "left": {
                    "composite_media_id": 610,
                    "customizations": []
                },
                "front": {
                    "composite_media_id": 608,
                    "customizations": []
                },
                "right": {
                    "composite_media_id": 611,
                    "customizations": []
                }
            },
            "created_at": "2017-11-15T08:07:48+00:00",
            "updated_at": "2017-11-15T08:07:50+00:00"
        },
        {
            "id": 92,
            "total": 185.21,
            "price": 173.09,
            "tax": 12.12,
            "tax_rate": 7,
            "attributes": [
                {
                    "name": "color",
                    "value": "DarkCyan"
                },
                {
                    "name": "size",
                    "value": "L"
                }
            ],
            "origin": {
                "code": "6904687103174"
            },
            "media_id": 617,
            "views": {
                "back": {
                    "composite_media_id": 619,
                    "customizations": []
                },
                "left": {
                    "composite_media_id": 620,
                    "customizations": []
                },
                "front": {
                    "composite_media_id": 618,
                    "customizations": []
                },
                "right": {
                    "composite_media_id": 621,
                    "customizations": []
                }
            },
            "created_at": "2017-11-15T08:07:49+00:00",
            "updated_at": "2017-11-15T08:07:50+00:00"
        },
        {
            "id": 94,
            "total": 24.52,
            "price": 20.61,
            "tax": 3.91,
            "tax_rate": 19,
            "attributes": [
                {
                    "name": "color",
                    "value": "Blue"
                },
                {
                    "name": "size",
                    "value": "L"
                }
            ],
            "origin": {
                "code": "1243574262255"
            },
            "media_id": 627,
            "views": {
                "back": {
                    "composite_media_id": 629,
                    "customizations": []
                },
                "left": {
                    "composite_media_id": 630,
                    "customizations": []
                },
                "front": {
                    "composite_media_id": 628,
                    "customizations": []
                },
                "right": {
                    "composite_media_id": 631,
                    "customizations": []
                }
            },
            "created_at": "2017-11-15T08:07:50+00:00",
            "updated_at": "2017-11-15T08:07:50+00:00"
        }
    ]
}