{"_id":"58112e73ded0340f0085d05e","project":"551e85be610f400d00837db7","__v":0,"category":{"_id":"58112e72ded0340f0085d02e","__v":0,"project":"551e85be610f400d00837db7","version":"58112e71ded0340f0085d02a","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-09-18T20:49:57.839Z","from_sync":false,"order":0,"slug":"cratejoy-api","title":"Cratejoy APIs"},"parentDoc":null,"user":"55f2fd49b5b25021002b7dfd","version":{"_id":"58112e71ded0340f0085d02a","project":"551e85be610f400d00837db7","__v":4,"createdAt":"2016-10-26T22:30:09.862Z","releaseDate":"2016-10-26T22:30:09.862Z","categories":["58112e72ded0340f0085d02b","58112e72ded0340f0085d02c","58112e72ded0340f0085d02d","58112e72ded0340f0085d02e","58112e72ded0340f0085d02f","58112e72ded0340f0085d030","58112e72ded0340f0085d031","58112e72ded0340f0085d032","58112e72ded0340f0085d033","58112e72ded0340f0085d034","581137cc604d3c230048b7e4","58dc367221742d0f00a73f98","590768e54669da0f00db5c0b"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"new designer","version_clean":"2.0.0","version":"2.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-16T15:27:34.463Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"When requesting resources, some of its related objects are loaded by default.  In some cases, for performance reasons, you can specify which relations you require with each resource.  This is useful for reducing the overall number of request necessary or the amount of data returned.\n\n#### An Example\nFor example, looking at the [Order](doc:order) resource, you see that [Customer](doc:customer-1) and [Products](doc:product) are included in the results by default. If you wanted to get the [Transactions](doc:transaction) associated with each [Order](doc:order) , you may be tempted to enumerate all the orders and issue a subsequent [Transaction](doc:transaction) query for each order.\n\nHowever, the number of queries can be reduced by requesting that [Transactions](doc:transaction) be included with each order query using the `with` query parameter.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Requesting related objects\",\n  \"body\": \"Use `with` to specify the set of related data to include in the result set.  The value should be a comma separated list of related property names.\\n\\n_//api.cratejoy.com/v1/<resource>_?**with**=**rel1**,**rel2**,..,**relN** \\n\\n`with` can be set to _all_ to request all related properties be returned with the object.  You may also set `with` to no value to indicate that no related properties be returned as some properties are always returned in the default query.\"\n}\n[/block]\nWhen combined with [Filtering and Searching](doc:filtering-and-searching2), the API provides the a way for you to specify _**what**_ you want and _**how**_ you want it.  Taking advantages of these features can help optimize your workflow by reducing both the number of queries and bandwidth.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Object Resources\",\n  \"body\": \"When reading through the documentation for each resource, there will be a section that describes which related properties are included by default and which can be loaded using the `with` property.\"\n}\n[/block]\n### Examples\n\n#### Default behavior without using 'with'\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.get('/v1/subscriptions/2157093');\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"autorenew\\\": true,\\n  \\\"billing\\\": { // Billing resource\\n    \\\"id\\\": 17995727,\\n    \\\"rebill_day\\\": 15,\\n    \\\"rebill_months\\\": 1,\\n    \\\"rebill_weeks\\\": null,\\n    \\\"rebill_window\\\": 11,\\n    \\\"store_id\\\": 17994176,\\n    \\\"type\\\": \\\"product_billing\\\"\\n  },\\n  \\\"credit\\\": null,\\n  \\\"customer\\\": { // Customer resource\\n    \\\"country\\\": \\\"US\\\",\\n    \\\"email\\\": \\\"20157082:::at:::cjtest.com\\\",\\n    \\\"first_name\\\": \\\"James\\\",\\n    \\\"id\\\": 20157082,\\n    \\\"last_name\\\": \\\"Smith\\\",\\n    \\\"location\\\": \\\"TX, US\\\",\\n    \\\"name\\\": \\\"James Smith\\\",\\n    \\\"num_orders\\\": 1,\\n    \\\"num_subscriptions\\\": 1,\\n    \\\"store_settings\\\": null,\\n    \\\"subscription_status\\\": \\\"cancelled\\\",\\n    \\\"total_revenue\\\": 2888,\\n    \\\"type\\\": \\\"customer\\\"\\n  },\\n  \\\"end_date\\\": \\\"2015-03-15T00:00:00Z\\\",\\n  \\\"id\\\": 20157093,\\n  \\\"is_test\\\": false,\\n  \\\"note\\\": \\\"Cancellation due to: None given \\\",\\n  \\\"product_billing_id\\\": 17995727,\\n  \\\"revenue\\\": 2250,\\n  \\\"skipped_date\\\": null,\\n  \\\"start_date\\\": \\\"2015-02-10T01:41:42Z\\\",\\n  \\\"status\\\": \\\"cancelled\\\",\\n  \\\"store_id\\\": 17994176,\\n  \\\"term\\\": { // Term resource\\n    \\\"description\\\": \\\"Charged every month\\\",\\n    \\\"enabled\\\": true,\\n    \\\"id\\\": 17995729,\\n    \\\"name\\\": \\\"Month to Month\\\",\\n    \\\"num_cycles\\\": 1,\\n    \\\"type\\\": \\\"subscription_type_term\\\"\\n  },\\n  \\\"type\\\": \\\"subscription\\\",\\n  \\\"url\\\": \\\"/v1/subscriptions/2157093/\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Getting objects with no relations\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.get('/v1/subscriptions/2157093?with');\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"autorenew\\\": true,\\n  \\\"credit\\\": null,\\n  \\\"end_date\\\": \\\"2015-03-15T00:00:00Z\\\",\\n  \\\"id\\\": 20157093,\\n  \\\"is_test\\\": false,\\n  \\\"note\\\": \\\"Cancellation due to: None given \\\",\\n  \\\"product_billing_id\\\": 17995727,\\n  \\\"revenue\\\": 2250,\\n  \\\"skipped_date\\\": null,\\n  \\\"start_date\\\": \\\"2015-02-10T01:41:42Z\\\",\\n  \\\"status\\\": \\\"cancelled\\\",\\n  \\\"store_id\\\": 17994176,\\n  \\\"type\\\": \\\"subscription\\\",\\n  \\\"url\\\": \\\"/v1/subscriptions/20157093/\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n#### Specifying logs and customer\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"$.get('/v1/subscriptions/2157093',{\\n  with: 'logs,customer'\\n});\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"autorenew\\\": true,\\n  \\\"credit\\\": null,\\n  \\\"customer\\\": {\\n    \\\"country\\\": \\\"US\\\",\\n    \\\"email\\\": \\\"20157082@cjtest.com\\\",\\n    \\\"first_name\\\": \\\"James\\\",\\n    \\\"id\\\": 20157082,\\n    \\\"last_name\\\": \\\"Smith\\\",\\n    \\\"location\\\": \\\"TX, US\\\",\\n    \\\"name\\\": \\\"Joel Smith\\\",\\n    \\\"num_orders\\\": 1,\\n    \\\"num_subscriptions\\\": 1,\\n    \\\"store_settings\\\": null,\\n    \\\"subscription_status\\\": \\\"cancelled\\\",\\n    \\\"total_revenue\\\": 2888,\\n    \\\"type\\\": \\\"customer\\\"\\n  },\\n  \\\"end_date\\\": \\\"2015-03-15T00:00:00Z\\\",\\n  \\\"id\\\": 20157093,\\n  \\\"is_test\\\": false,\\n  \\\"logs\\\": [\\n    {\\n      \\\"admin\\\": null,\\n      \\\"admin_id\\\": null,\\n      \\\"cancel_reason\\\": null,\\n      \\\"created_at\\\": \\\"2015-02-10T01:41:42Z\\\",\\n      \\\"customer\\\": {\\n        \\\"country\\\": \\\"US\\\",\\n        \\\"email\\\": \\\"20157082@cjtest.com\\\",\\n        \\\"first_name\\\": \\\"James\\\",\\n        \\\"id\\\": 20157082,\\n        \\\"last_name\\\": \\\"Smith\\\",\\n        \\\"location\\\": \\\"TX, US\\\",\\n        \\\"name\\\": \\\"Joel Smith\\\",\\n        \\\"num_orders\\\": 1,\\n        \\\"num_subscriptions\\\": 1,\\n        \\\"subscription_status\\\": \\\"cancelled\\\",\\n        \\\"total_revenue\\\": 2888,\\n        \\\"type\\\": \\\"customer\\\"\\n      },\\n      \\\"id\\\": 20157094,\\n      \\\"log_type\\\": \\\"created\\\",\\n      \\\"note\\\": null,\\n      \\\"owner_type\\\": \\\"customer\\\",\\n      \\\"type\\\": \\\"subscription_log\\\"\\n    },\\n    {\\n      \\\"admin\\\": null,\\n      \\\"admin_id\\\": null,\\n      \\\"cancel_reason\\\": null,\\n      \\\"created_at\\\": \\\"2015-02-10T01:41:44Z\\\",\\n      \\\"customer\\\": {\\n        \\\"country\\\": \\\"US\\\",\\n        \\\"email\\\": \\\"20157082@cjtest.com\\\",\\n        \\\"first_name\\\": \\\"James\\\",\\n        \\\"id\\\": 20157082,\\n        \\\"last_name\\\": \\\"Smith\\\",\\n        \\\"location\\\": \\\"TX, US\\\",\\n        \\\"name\\\": \\\"Joel Smith\\\",\\n        \\\"num_orders\\\": 1,\\n        \\\"num_subscriptions\\\": 1,\\n        \\\"subscription_status\\\": \\\"cancelled\\\",\\n        \\\"total_revenue\\\": 2888,\\n        \\\"type\\\": \\\"customer\\\"\\n      },\\n      \\\"id\\\": 20157100,\\n      \\\"log_type\\\": \\\"paid\\\",\\n      \\\"note\\\": null,\\n      \\\"owner_type\\\": \\\"customer\\\",\\n      \\\"type\\\": \\\"subscription_log\\\"\\n    },\\n    {\\n      \\\"admin\\\": null,\\n      \\\"admin_id\\\": null,\\n      \\\"cancel_reason\\\": null,\\n      \\\"created_at\\\": \\\"2015-03-05T12:45:23Z\\\",\\n      \\\"customer\\\": {\\n        \\\"country\\\": \\\"US\\\",\\n        \\\"email\\\": \\\"20157082@cjtest.com\\\",\\n        \\\"first_name\\\": \\\"James\\\",\\n        \\\"id\\\": 20157082,\\n        \\\"last_name\\\": \\\"Smith\\\",\\n        \\\"location\\\": \\\"TX, US\\\",\\n        \\\"name\\\": \\\"Joel Smith\\\",\\n        \\\"num_orders\\\": 1,\\n        \\\"num_subscriptions\\\": 1,\\n        \\\"subscription_status\\\": \\\"cancelled\\\",\\n        \\\"total_revenue\\\": 2888,\\n        \\\"type\\\": \\\"customer\\\"\\n      },\\n      \\\"id\\\": 23120350,\\n      \\\"log_type\\\": \\\"cancelled\\\",\\n      \\\"note\\\": null,\\n      \\\"owner_type\\\": \\\"customer\\\",\\n      \\\"type\\\": \\\"subscription_log\\\"\\n    }\\n  ],\\n  \\\"note\\\": \\\"Cancellation due to: None given \\\",\\n  \\\"product_billing_id\\\": 17995727,\\n  \\\"revenue\\\": 2250,\\n  \\\"skipped_date\\\": null,\\n  \\\"start_date\\\": \\\"2015-02-10T01:41:42Z\\\",\\n  \\\"status\\\": \\\"cancelled\\\",\\n  \\\"store_id\\\": 17994176,\\n  \\\"type\\\": \\\"subscription\\\",\\n  \\\"url\\\": \\\"/v1/subscriptions/20157093/\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"working-with-object-relationships","type":"basic","title":"Working with Object Relationships"}

Working with Object Relationships


When requesting resources, some of its related objects are loaded by default. In some cases, for performance reasons, you can specify which relations you require with each resource. This is useful for reducing the overall number of request necessary or the amount of data returned. #### An Example For example, looking at the [Order](doc:order) resource, you see that [Customer](doc:customer-1) and [Products](doc:product) are included in the results by default. If you wanted to get the [Transactions](doc:transaction) associated with each [Order](doc:order) , you may be tempted to enumerate all the orders and issue a subsequent [Transaction](doc:transaction) query for each order. However, the number of queries can be reduced by requesting that [Transactions](doc:transaction) be included with each order query using the `with` query parameter. [block:callout] { "type": "info", "title": "Requesting related objects", "body": "Use `with` to specify the set of related data to include in the result set. The value should be a comma separated list of related property names.\n\n_//api.cratejoy.com/v1/<resource>_?**with**=**rel1**,**rel2**,..,**relN** \n\n`with` can be set to _all_ to request all related properties be returned with the object. You may also set `with` to no value to indicate that no related properties be returned as some properties are always returned in the default query." } [/block] When combined with [Filtering and Searching](doc:filtering-and-searching2), the API provides the a way for you to specify _**what**_ you want and _**how**_ you want it. Taking advantages of these features can help optimize your workflow by reducing both the number of queries and bandwidth. [block:callout] { "type": "warning", "title": "Object Resources", "body": "When reading through the documentation for each resource, there will be a section that describes which related properties are included by default and which can be loaded using the `with` property." } [/block] ### Examples #### Default behavior without using 'with' [block:code] { "codes": [ { "code": "$.get('/v1/subscriptions/2157093');", "language": "javascript" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"autorenew\": true,\n \"billing\": { // Billing resource\n \"id\": 17995727,\n \"rebill_day\": 15,\n \"rebill_months\": 1,\n \"rebill_weeks\": null,\n \"rebill_window\": 11,\n \"store_id\": 17994176,\n \"type\": \"product_billing\"\n },\n \"credit\": null,\n \"customer\": { // Customer resource\n \"country\": \"US\",\n \"email\": \"20157082@cjtest.com\",\n \"first_name\": \"James\",\n \"id\": 20157082,\n \"last_name\": \"Smith\",\n \"location\": \"TX, US\",\n \"name\": \"James Smith\",\n \"num_orders\": 1,\n \"num_subscriptions\": 1,\n \"store_settings\": null,\n \"subscription_status\": \"cancelled\",\n \"total_revenue\": 2888,\n \"type\": \"customer\"\n },\n \"end_date\": \"2015-03-15T00:00:00Z\",\n \"id\": 20157093,\n \"is_test\": false,\n \"note\": \"Cancellation due to: None given \",\n \"product_billing_id\": 17995727,\n \"revenue\": 2250,\n \"skipped_date\": null,\n \"start_date\": \"2015-02-10T01:41:42Z\",\n \"status\": \"cancelled\",\n \"store_id\": 17994176,\n \"term\": { // Term resource\n \"description\": \"Charged every month\",\n \"enabled\": true,\n \"id\": 17995729,\n \"name\": \"Month to Month\",\n \"num_cycles\": 1,\n \"type\": \"subscription_type_term\"\n },\n \"type\": \"subscription\",\n \"url\": \"/v1/subscriptions/2157093/\"\n}", "language": "json" } ] } [/block] #### Getting objects with no relations [block:code] { "codes": [ { "code": "$.get('/v1/subscriptions/2157093?with');", "language": "javascript" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"autorenew\": true,\n \"credit\": null,\n \"end_date\": \"2015-03-15T00:00:00Z\",\n \"id\": 20157093,\n \"is_test\": false,\n \"note\": \"Cancellation due to: None given \",\n \"product_billing_id\": 17995727,\n \"revenue\": 2250,\n \"skipped_date\": null,\n \"start_date\": \"2015-02-10T01:41:42Z\",\n \"status\": \"cancelled\",\n \"store_id\": 17994176,\n \"type\": \"subscription\",\n \"url\": \"/v1/subscriptions/20157093/\"\n}", "language": "json" } ] } [/block] #### Specifying logs and customer [block:code] { "codes": [ { "code": "$.get('/v1/subscriptions/2157093',{\n with: 'logs,customer'\n});", "language": "json" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"autorenew\": true,\n \"credit\": null,\n \"customer\": {\n \"country\": \"US\",\n \"email\": \"20157082@cjtest.com\",\n \"first_name\": \"James\",\n \"id\": 20157082,\n \"last_name\": \"Smith\",\n \"location\": \"TX, US\",\n \"name\": \"Joel Smith\",\n \"num_orders\": 1,\n \"num_subscriptions\": 1,\n \"store_settings\": null,\n \"subscription_status\": \"cancelled\",\n \"total_revenue\": 2888,\n \"type\": \"customer\"\n },\n \"end_date\": \"2015-03-15T00:00:00Z\",\n \"id\": 20157093,\n \"is_test\": false,\n \"logs\": [\n {\n \"admin\": null,\n \"admin_id\": null,\n \"cancel_reason\": null,\n \"created_at\": \"2015-02-10T01:41:42Z\",\n \"customer\": {\n \"country\": \"US\",\n \"email\": \"20157082@cjtest.com\",\n \"first_name\": \"James\",\n \"id\": 20157082,\n \"last_name\": \"Smith\",\n \"location\": \"TX, US\",\n \"name\": \"Joel Smith\",\n \"num_orders\": 1,\n \"num_subscriptions\": 1,\n \"subscription_status\": \"cancelled\",\n \"total_revenue\": 2888,\n \"type\": \"customer\"\n },\n \"id\": 20157094,\n \"log_type\": \"created\",\n \"note\": null,\n \"owner_type\": \"customer\",\n \"type\": \"subscription_log\"\n },\n {\n \"admin\": null,\n \"admin_id\": null,\n \"cancel_reason\": null,\n \"created_at\": \"2015-02-10T01:41:44Z\",\n \"customer\": {\n \"country\": \"US\",\n \"email\": \"20157082@cjtest.com\",\n \"first_name\": \"James\",\n \"id\": 20157082,\n \"last_name\": \"Smith\",\n \"location\": \"TX, US\",\n \"name\": \"Joel Smith\",\n \"num_orders\": 1,\n \"num_subscriptions\": 1,\n \"subscription_status\": \"cancelled\",\n \"total_revenue\": 2888,\n \"type\": \"customer\"\n },\n \"id\": 20157100,\n \"log_type\": \"paid\",\n \"note\": null,\n \"owner_type\": \"customer\",\n \"type\": \"subscription_log\"\n },\n {\n \"admin\": null,\n \"admin_id\": null,\n \"cancel_reason\": null,\n \"created_at\": \"2015-03-05T12:45:23Z\",\n \"customer\": {\n \"country\": \"US\",\n \"email\": \"20157082@cjtest.com\",\n \"first_name\": \"James\",\n \"id\": 20157082,\n \"last_name\": \"Smith\",\n \"location\": \"TX, US\",\n \"name\": \"Joel Smith\",\n \"num_orders\": 1,\n \"num_subscriptions\": 1,\n \"subscription_status\": \"cancelled\",\n \"total_revenue\": 2888,\n \"type\": \"customer\"\n },\n \"id\": 23120350,\n \"log_type\": \"cancelled\",\n \"note\": null,\n \"owner_type\": \"customer\",\n \"type\": \"subscription_log\"\n }\n ],\n \"note\": \"Cancellation due to: None given \",\n \"product_billing_id\": 17995727,\n \"revenue\": 2250,\n \"skipped_date\": null,\n \"start_date\": \"2015-02-10T01:41:42Z\",\n \"status\": \"cancelled\",\n \"store_id\": 17994176,\n \"type\": \"subscription\",\n \"url\": \"/v1/subscriptions/20157093/\"\n}", "language": "json" } ] } [/block]