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.


{success} Variants Not Expanded

GET /products/1 HTTP/1.1

{
    "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,
    ]
}

{success} Variants Expanded

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

{
    "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"
        }
    ]
}