Includes

You can easily include resource relationships on most top-level resources. Multiple includes are defined using comma delimited values.

Each supported resource includes its own documentation on the available resources that can be included.

If there you request a resource to be includes, but no related entities of that resource type exist for your store, the response will not have any "included" section present.

Similarly, if you request to include a resource that is not supported as an include by the endpoint you are requesting from, there will be no "included" section in the response.

It is highly recommend to not include a resource if there will be more than 100 entities returned by that included resource.

There is a soft limit of five included resources per request, where one included resource could be "main_image", and another could be "categories" etc.

Below are some common include examples.

Include Category products

GET https://api.moltin.com/v2/categories/:id?include=products

Path Parameters

Name	Type	Description
id	string	The ID of the product

Query Parameters

Name	Type	Description
include	string	products

Headers

Name	Type	Description
Authorization	string	The Bearer token to grant access to the API

200

{
    "data": {
        "id": "521e6029-0e0e-4704-b9a5-9777047ada04",
        "type": "category",
        "status": "live",
        "name": "Bright",
        "slug": "bright",
        "description": "Bright Category",
        "meta": {
            "timestamps": {
                "created_at": "2018-02-05T11:19:08+00:00",
                "updated_at": "2018-03-29T10:34:13+00:00"
            }
        },
        "relationships": {
            "products": {
                "data": [
                    {
                        "type": "product",
                        "id": "41c84c63-4d5e-4135-979f-e4b681b83dcc"
                    }
                ]
            }
        },
        "background_colour": "#ded7cb",
        "background_image": "https://s3-eu-west-1.amazonaws.com/bkt-svc-files-cmty-api-moltin-com/e8c53cb0-120d-4ea5-8941-ce74dec06038/61118f21-14a2-466c-a84b-c30b1f900cf9.png"
    },
    "included": {
        "products": [
            {
                "type": "product",
                "id": "41c84c63-4d5e-4135-979f-e4b681b83dcc",
                "name": "Orb",
                "slug": "orb",
                "sku": "ORLP100WHI",
                "manage_stock": false,
                "description": "Abstract, sculptural, refined and edgy with a modern twist. Its symmetrical, spoked structure generates a clever geometric presence, which works well in a contemporary environment.",
                "price": [
                    {
                        "amount": 45000,
                        "currency": "USD",
                        "includes_tax": true
                    }
                ],
                "status": "live",
                "commodity_type": "physical",
                "meta": {
                    "timestamps": {
                        "created_at": "2017-06-19T13:26:03+00:00",
                        "updated_at": "2018-03-13T13:43:57+00:00"
                    },
                    "display_price": {
                        "with_tax": {
                            "amount": 45000,
                            "currency": "USD",
                            "formatted": "$450.00"
                        },
                        "without_tax": {
                            "amount": 45000,
                            "currency": "USD",
                            "formatted": "$450.00"
                        }
                    },
                    "stock": {
                        "level": 500,
                        "availability": "in-stock"
                    }
                },
                "relationships": {
                    "files": {
                        "data": [
                            {
                                "type": "file",
                                "id": "61118f21-14a2-466c-a84b-c30b1f900cf9"
                            }
                        ]
                    },
                    "categories": {
                        "data": [
                            {
                                "type": "category",
                                "id": "521e6029-0e0e-4704-b9a5-9777047ada04"
                            }
                        ]
                    },
                    "main_image": {
                        "data": {
                            "type": "main_image",
                            "id": "61118f21-14a2-466c-a84b-c30b1f900cf9"
                        }
                    }
                }
            }
        ]
    }
}

cURL

curl -X GET https://api.moltin.com/v2/categories/:id?include=products \
     -H "Authorization: Bearer XXXX"

JavaScript SDK

const MoltinGateway = require('@moltin/sdk').gateway

const Moltin = MoltinGateway({
  client_id: 'X'
})

const id = 'XXXX'

Moltin.Categories.With('products')
  .Get(id)
  .then(category => {
    // Do something
  })

Swift SDK

let moltin = Moltin(withClientID: "<your client ID>")

let id = "XXXX"

moltin.category.include([.products]).get(forID: id) { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Include product main_image

GET https://api.moltin.com/v2/products?include=main_image

Path Parameters

Name	Type	Description
include	string	main_image

Headers

Name	Type	Description
Authorization	string	The Bearer token used to access the API

200

{
    "data": {
            "id": "933f837e-106d-412d-9724-e45a0760f404",
            "type": "product",
            "tax-code": null,
            "name": "Sourdough bread",
            "slug": "sourdough-bread",
            "sku": "SRD-BR-01",
            "manage_stock": false,
            "description": "Sourdough bread",
            "price": [
                {
                    "amount": 299,
                    "currency": "USD",
                    "includes_tax": true
                }
            ],
            "status": "live",
            "commodity_type": "physical",
            "meta": {
                "timestamps": {
                    "created_at": "2018-06-08T09:50:59+00:00",
                    "updated_at": "2019-05-21T02:05:42+00:00"
                },
                "display_price": {
                    "with_tax": {
                        "amount": 299,
                        "currency": "USD",
                        "formatted": "$2.99"
                    },
                    "without_tax": {
                        "amount": 299,
                        "currency": "USD",
                        "formatted": "$2.99"
                    }
                },
                "stock": {
                    "level": 0,
                    "availability": "out-stock"
                }
            },
                "main_image": {
                    "data": {
                        "type": "main_image",
                        "id": "147807c4-28a5-4a73-ac2a-4fe80b5f6791"
                    }
                }
            }
        }
    }

cURL

curl -X GET https://api.moltin.com/v2/products?include=main_image \
     -H "Authorization: Bearer XXXX"

JavaScript SDK

const MoltinGateway = require('@moltin/sdk').gateway

const Moltin = MoltinGateway({
  client_id: 'X'
})

const id = 'XXXX'

Moltin.Products.With('main_image')
  .All()
  .then(products => {
    // Do something
  })

Swift SDK

let moltin = Moltin(withClientID: "<your client ID>")

let id = "XXXX"

moltin.product.include([.main_image]).all { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}

Multiple includes

GET https://api.moltin.com/v2/products?include=main_images,category

Path Parameters

Name	Type	Description
include	string	main_images,category

Headers

Name	Type	Description
Authorization	string	The Bearer token used to access the API

200

{
    "data": {
            "id": "933f837e-106d-412d-9724-e45a0760f404",
            "type": "product",
            "tax-code": null
            "name": "Sourdough bread",
            "slug": "sourdough-bread",
            "sku": "SRD-BR-01",
            "manage_stock": false,
            "description": "Sourdough bread",
            "price": [
                {
                    "amount": 299,
                    "currency": "USD",
                    "includes_tax": true
                }
            ],
            "status": "live",
            "commodity_type": "physical",
            "meta": {
                "timestamps": {
                    "created_at": "2018-06-08T09:50:59+00:00",
                    "updated_at": "2019-05-21T02:05:42+00:00"
                },
                "display_price": {
                    "with_tax": {
                        "amount": 299,
                        "currency": "USD",
                        "formatted": "$2.99"
                    },
                    "without_tax": {
                        "amount": 299,
                        "currency": "USD",
                        "formatted": "$2.99"
                    }
                },
                "stock": {
                    "level": 0,
                    "availability": "out-stock"
                }
            },
            "relationships": {
                "categories": {
                    "data": [
                        {
                            "type": "category",
                            "id": "9ea28fde-cf9b-4316-9ed1-638e3461e0f5"
                        }
                    ]
                },
                "main_image": {
                    "data": {
                        "type": "main_image",
                        "id": "147807c4-28a5-4a73-ac2a-4fe80b5f6791"
                    }
                }
            }
        }
    }

cURL

curl -X GET https://api.moltin.com/v2/products?include=main_image,category \
     -H "Authorization: Bearer XXXX"

JavaScript SDK

const MoltinGateway = require('@moltin/sdk').gateway

const Moltin = MoltinGateway({
  client_id: 'X'
})

const id = 'XXXX'

Moltin.Products.With(['main_image', 'category'])
  .All()
  .then(products => {
    // Do something
  })

Swift SDK

let moltin = Moltin(withClientID: "<your client ID>")

let id = "XXXX"

moltin.product.include([.main_image, .category]).all { result in
    switch result {
        case .success(let response):
            print(response)
        case .failure(let error):
            print(error)
    }
}