Support
API Reference

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 resource, you see that Customer and Products are included in the results by default. If you wanted to get the Transactions associated with each Order , you may be tempted to enumerate all the orders and issue a subsequent Transaction query for each order.

However, the number of queries can be reduced by requesting that Transactions be included with each order query using the with query parameter.

📘

Requesting related objects

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.

//api.cratejoy.com/v1/?with=rel1,rel2,..,relN

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.

When combined with Filtering and Searching, 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.

🚧

Object Resources

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.

Examples

Default behavior without using 'with'

$.get('/v1/subscriptions/2157093');

{
  "autorenew": true,
  "billing": { // Billing resource
    "id": 17995727,
    "rebill_day": 15,
    "rebill_months": 1,
    "rebill_weeks": null,
    "rebill_window": 11,
    "store_id": 17994176,
    "type": "product_billing"
  },
  "credit": null,
  "customer": { // Customer resource
    "country": "US",
    "email": "[email protected]",
    "first_name": "James",
    "id": 20157082,
    "last_name": "Smith",
    "location": "TX, US",
    "name": "James Smith",
    "type": "customer"
  },
  "end_date": "2015-03-15T00:00:00Z",
  "id": 20157093,
  "is_test": false,
  "note": "Cancellation due to: None given ",
  "product_billing_id": 17995727,
  "revenue": 2250,
  "skipped_date": null,
  "start_date": "2015-02-10T01:41:42Z",
  "status": "cancelled",
  "store_id": 17994176,
  "term": { // Term resource
    "description": "Charged every month",
    "enabled": true,
    "id": 17995729,
    "name": "Month to Month",
    "num_cycles": 1,
    "type": "subscription_type_term"
  },
  "type": "subscription",
  "url": "/v1/subscriptions/2157093/"
}

Getting objects with no relations

$.get('/v1/subscriptions/2157093?with');

{
  "autorenew": true,
  "credit": null,
  "end_date": "2015-03-15T00:00:00Z",
  "id": 20157093,
  "is_test": false,
  "note": "Cancellation due to: None given ",
  "product_billing_id": 17995727,
  "revenue": 2250,
  "skipped_date": null,
  "start_date": "2015-02-10T01:41:42Z",
  "status": "cancelled",
  "store_id": 17994176,
  "type": "subscription",
  "url": "/v1/subscriptions/20157093/"
}

Specifying logs and customer

$.get('/v1/subscriptions/2157093',{
  with: 'logs,customer'
});

{
  "autorenew": true,
  "credit": null,
  "customer": {
    "country": "US",
    "email": "[email protected]",
    "first_name": "James",
    "id": 20157082,
    "last_name": "Smith",
    "location": "TX, US",
    "name": "Joel Smith",
    "type": "customer"
  },
  "end_date": "2015-03-15T00:00:00Z",
  "id": 20157093,
  "is_test": false,
  "logs": [
    {
      "admin": null,
      "admin_id": null,
      "cancel_reason": null,
      "created_at": "2015-02-10T01:41:42Z",
      "customer": {
        "country": "US",
        "email": "[email protected]",
        "first_name": "James",
        "id": 20157082,
        "last_name": "Smith",
        "location": "TX, US",
        "name": "Joel Smith",
        "type": "customer"
      },
      "id": 20157094,
      "log_type": "created",
      "note": null,
      "owner_type": "customer",
      "type": "subscription_log"
    },
    {
      "admin": null,
      "admin_id": null,
      "cancel_reason": null,
      "created_at": "2015-02-10T01:41:44Z",
      "customer": {
        "country": "US",
        "email": "[email protected]",
        "first_name": "James",
        "id": 20157082,
        "last_name": "Smith",
        "location": "TX, US",
        "name": "Joel Smith",
        "type": "customer"
      },
      "id": 20157100,
      "log_type": "paid",
      "note": null,
      "owner_type": "customer",
      "type": "subscription_log"
    },
    {
      "admin": null,
      "admin_id": null,
      "cancel_reason": null,
      "created_at": "2015-03-05T12:45:23Z",
      "customer": {
        "country": "US",
        "email": "[email protected]",
        "first_name": "James",
        "id": 20157082,
        "last_name": "Smith",
        "location": "TX, US",
        "name": "Joel Smith",
        "type": "customer"
      },
      "id": 23120350,
      "log_type": "cancelled",
      "note": null,
      "owner_type": "customer",
      "type": "subscription_log"
    }
  ],
  "note": "Cancellation due to: None given ",
  "product_billing_id": 17995727,
  "revenue": 2250,
  "skipped_date": null,
  "start_date": "2015-02-10T01:41:42Z",
  "status": "cancelled",
  "store_id": 17994176,
  "type": "subscription",
  "url": "/v1/subscriptions/20157093/"
}