Fetching relationships

How to directly fetch related resources

You can fetch either single related resources or collections by sending GET requests to the "related" link /api/<parent_resource>/:id/<related_resource> (i.e. the parent resource endpoint, specifying the single parent resource ID and the related resource you want to retrieve).

Make sure to use the relationship name and not the resource name (e.g., if you want to retrieve the billing address associated with an order, use billing_address and not just addresses — )

When fetching a list of related resources results can be sorted () and filtered ().

Examples

The following request fetches the billing address associated with the order identified by the ID "xYZkjABcde":

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/orders/xYZkjABcde/billing_address' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

On success, the API responds with a 200 OK status code, returning the single related resource object:

{
  "data": {
    "id": "yzXKjYzaCx",
    "type": "addresses",
    "links": {...},
    "attributes": {
      "business": false,
      "first_name": "John",
      "last_name": "Doe",
      "company": null,
      "full_name": "John Doe",
      "line_1": "1234 5th Avenue",
      "line_2": null,
      "city": "New York",
      "zip_code": "10018",
      "state_code": "NY",
      "country_code": "US",
      "phone": "646-1234567",
      "full_address": "1234 5th Avenue, 10018 New York NY (US) 646-1234567",
      "name": "John Doe, 1234 5th Avenue, 10018 New York NY (US) 646-1234567",
      "email": null,
      "notes": null,
      "lat": null,
      "lng": null,
      "is_localized": false,
      "is_geocoded": false,
      "provider_name": null,
      "map_url": null,
      "static_map_url": null,
      "billing_info": null,
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "geocoder": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "JxYabZKcAw"
    }
  }
}

The following request fetches the order history of a specific customer, i.e. the list of orders associated with the customer identified by the ID "xYZkjABcde":

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

On success, the API responds with a 200 OK status code, returning a paginated collection of the related resource objects:

{
  "data": [
    {
      "id": "yzXKjYzaCx",
      "type": "orders",
      "links": {...},
      "attributes": {
        "number": 1234,
        "autorefresh": true,
        "status": "pending",
        "payment_status": "unpaid",
        "fulfillment_status": "unfulfilled",
        "guest": false,
        "editable": true,
        "customer_email": "john@example.com",
        "language_code": "en",
        "currency_code": "USD",
        "tax_included": false,
        "tax_rate": null,
        "freight_taxable": null,
        "requires_billing_info": false,
        "country_code": "US",
        "shipping_country_code_lock": null,
        "coupon_code": null,
        "gift_card_code": null,
        "gift_card_or_coupon_code": null,
        "subtotal_amount_cents": 3480,
        "subtotal_amount_float": 34.8,
        "formatted_subtotal_amount": "$34.80",
        "shipping_amount_cents": 700,
        "shipping_amount_float": 7.0,
        "formatted_shipping_amount": "$7.00",
        "payment_method_amount_cents": 0,
        "payment_method_amount_float": 0.0,
        "formatted_payment_method_amount": "$0.00",
        "discount_amount_cents": 0,
        "discount_amount_float": 0.0,
        "formatted_discount_amount": "$0.00",
        "adjustment_amount_cents": 0,
        "adjustment_amount_float": 0.0,
        "formatted_adjustment_amount": "$0.00",
        "gift_card_amount_cents": 0,
        "gift_card_amount_float": 0.0,
        "formatted_gift_card_amount": "$0.00",
        "total_tax_amount_cents": 0,
        "total_tax_amount_float": 0.0,
        "formatted_total_tax_amount": "$0.00",
        "subtotal_tax_amount_cents": 0,
        "subtotal_tax_amount_float": 0.0,
        "formatted_subtotal_tax_amount": "$0.00",
        "shipping_tax_amount_cents": 0,
        "shipping_tax_amount_float": 0.0,
        "formatted_shipping_tax_amount": "$0.00",
        "payment_method_tax_amount_cents": 0,
        "payment_method_tax_amount_float": 0.0,
        "formatted_payment_method_tax_amount": "$0.00",
        "adjustment_tax_amount_cents": 0,
        "adjustment_tax_amount_float": 0.0,
        "formatted_adjustment_tax_amount": "$0.00",
        "total_amount_cents": 4180,
        "total_amount_float": 41.8,
        "formatted_total_amount": "$41.80",
        "total_taxable_amount_cents": 4180,
        "total_taxable_amount_float": 41.8,
        "formatted_total_taxable_amount": "$41.80",
        "subtotal_taxable_amount_cents": 3480,
        "subtotal_taxable_amount_float": 34.8,
        "formatted_subtotal_taxable_amount": "$34.80",
        "shipping_taxable_amount_cents": 700,
        "shipping_taxable_amount_float": 7.0,
        "formatted_shipping_taxable_amount": "$7.00",
        "payment_method_taxable_amount_cents": 0,
        "payment_method_taxable_amount_float": 0.0,
        "formatted_payment_method_taxable_amount": "$0.00",
        "adjustment_taxable_amount_cents": 0,
        "adjustment_taxable_amount_float": 0.0,
        "formatted_adjustment_taxable_amount": "$0.00",
        "total_amount_with_taxes_cents": 4180,
        "total_amount_with_taxes_float": 41.8,
        "formatted_total_amount_with_taxes": "$41.80",
        "fees_amount_cents": 0,
        "fees_amount_float": 0.0,
        "formatted_fees_amount": "$0.00",
        "duty_amount_cents": null,
        "duty_amount_float": null,
        "formatted_duty_amount": null,
        "skus_count": 1,
        "line_item_options_count": 0,
        "shipments_count": 1,
        "payment_source_details": null,
        "token": "y0ur-t0K3n",
        "cart_url": null,
        "return_url": null,
        "terms_url": null,
        "privacy_url": null,
        "checkout_url": "https://your-checkout-url/yzXKjYzaCx",
        "placed_at": null,
        "approved_at": null,
        "cancelled_at": null,
        "payment_updated_at": null,
        "fulfillment_updated_at": null,
        "refreshed_at": null,
        "archived_at": null,
        "expires_at": null,
        "created_at": "2018-01-01T12:00:00.000Z",
        "updated_at": "2018-01-01T12:00:00.000Z",
        "reference": "",
        "reference_origin": null,
        "metadata": {}
      },
      "relationships": {
        "market": {
          "links": {...}
        },
        "customer": {
          "links": {...}
        },
        "shipping_address": {
          "links": {...}
        },
        "billing_address": {
          "links": {...}
        },
        "available_payment_methods": {
          "links": {...}
        },
        "available_customer_payment_sources": {
          "links": {...}
        },
        "payment_method": {
          "links": {...}
        },
        "payment_source": {
          "links": {...}
        },
        "line_items": {
          "links": {...}
        },
        "shipments": {
          "links": {...}
        },
        "transactions": {
          "links": {...}
        },
        "authorizations": {
          "links": {...}
        },
        "captures": {
            "links": {...}
        },
        "voids": {
          "links": {...}
        },
        "refunds": {
          "links": {...}
        },
        "order_subscriptions": {
            "links": {...}
        },
        "order_copies": {
          "links": {...}
        },
        "attachments": {
          "links": {...}
        }
      },
      "meta": {
        "mode": "test",
        "organization_id": "JxYabZKcAw"
      }
    },
    {
      "other": "... 9 orders (first page)"
    }
  ],
  "meta": {
      "record_count": 70,
      "page_count": 7
  },
  "links": {
    "first": "https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders?page[number]=1&page[size]=10",
    "next": "https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders?page[number]=2&page[size]=10",
    "last": "https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders?page[number]=7&page[size]=10"
  }
}

PreviousFetching resources NextIncluding associations

Last updated 6 months ago

{ "data": { "id": "yzXKjYzaCx", "type": "addresses", "links": {...}, "attributes": { "business": false, "first_name": "John", "last_name": "Doe", "company": null, "full_name": "John Doe", "line_1": "1234 5th Avenue", "line_2": null, "city": "New York", "zip_code": "10018", "state_code": "NY", "country_code": "US", "phone": "646-1234567", "full_address": "1234 5th Avenue, 10018 New York NY (US) 646-1234567", "name": "John Doe, 1234 5th Avenue, 10018 New York NY (US) 646-1234567", "email": null, "notes": null, "lat": null, "lng": null, "is_localized": false, "is_geocoded": false, "provider_name": null, "map_url": null, "static_map_url": null, "billing_info": null, "created_at": "2018-01-01T12:00:00.000Z", "updated_at": "2018-01-01T12:00:00.000Z", "reference": null, "reference_origin": null, "metadata": {} }, "relationships": { "geocoder": { "links": {...} } }, "meta": { "mode": "test", "organization_id": "JxYabZKcAw" } } }

{ "data": [ { "id": "yzXKjYzaCx", "type": "orders", "links": {...}, "attributes": { "number": 1234, "autorefresh": true, "status": "pending", "payment_status": "unpaid", "fulfillment_status": "unfulfilled", "guest": false, "editable": true, "customer_email": "john@example.com", "language_code": "en", "currency_code": "USD", "tax_included": false, "tax_rate": null, "freight_taxable": null, "requires_billing_info": false, "country_code": "US", "shipping_country_code_lock": null, "coupon_code": null, "gift_card_code": null, "gift_card_or_coupon_code": null, "subtotal_amount_cents": 3480, "subtotal_amount_float": 34.8, "formatted_subtotal_amount": "$34.80", "shipping_amount_cents": 700, "shipping_amount_float": 7.0, "formatted_shipping_amount": "$7.00", "payment_method_amount_cents": 0, "payment_method_amount_float": 0.0, "formatted_payment_method_amount": "$0.00", "discount_amount_cents": 0, "discount_amount_float": 0.0, "formatted_discount_amount": "$0.00", "adjustment_amount_cents": 0, "adjustment_amount_float": 0.0, "formatted_adjustment_amount": "$0.00", "gift_card_amount_cents": 0, "gift_card_amount_float": 0.0, "formatted_gift_card_amount": "$0.00", "total_tax_amount_cents": 0, "total_tax_amount_float": 0.0, "formatted_total_tax_amount": "$0.00", "subtotal_tax_amount_cents": 0, "subtotal_tax_amount_float": 0.0, "formatted_subtotal_tax_amount": "$0.00", "shipping_tax_amount_cents": 0, "shipping_tax_amount_float": 0.0, "formatted_shipping_tax_amount": "$0.00", "payment_method_tax_amount_cents": 0, "payment_method_tax_amount_float": 0.0, "formatted_payment_method_tax_amount": "$0.00", "adjustment_tax_amount_cents": 0, "adjustment_tax_amount_float": 0.0, "formatted_adjustment_tax_amount": "$0.00", "total_amount_cents": 4180, "total_amount_float": 41.8, "formatted_total_amount": "$41.80", "total_taxable_amount_cents": 4180, "total_taxable_amount_float": 41.8, "formatted_total_taxable_amount": "$41.80", "subtotal_taxable_amount_cents": 3480, "subtotal_taxable_amount_float": 34.8, "formatted_subtotal_taxable_amount": "$34.80", "shipping_taxable_amount_cents": 700, "shipping_taxable_amount_float": 7.0, "formatted_shipping_taxable_amount": "$7.00", "payment_method_taxable_amount_cents": 0, "payment_method_taxable_amount_float": 0.0, "formatted_payment_method_taxable_amount": "$0.00", "adjustment_taxable_amount_cents": 0, "adjustment_taxable_amount_float": 0.0, "formatted_adjustment_taxable_amount": "$0.00", "total_amount_with_taxes_cents": 4180, "total_amount_with_taxes_float": 41.8, "formatted_total_amount_with_taxes": "$41.80", "fees_amount_cents": 0, "fees_amount_float": 0.0, "formatted_fees_amount": "$0.00", "duty_amount_cents": null, "duty_amount_float": null, "formatted_duty_amount": null, "skus_count": 1, "line_item_options_count": 0, "shipments_count": 1, "payment_source_details": null, "token": "y0ur-t0K3n", "cart_url": null, "return_url": null, "terms_url": null, "privacy_url": null, "checkout_url": "https://your-checkout-url/yzXKjYzaCx", "placed_at": null, "approved_at": null, "cancelled_at": null, "payment_updated_at": null, "fulfillment_updated_at": null, "refreshed_at": null, "archived_at": null, "expires_at": null, "created_at": "2018-01-01T12:00:00.000Z", "updated_at": "2018-01-01T12:00:00.000Z", "reference": "", "reference_origin": null, "metadata": {} }, "relationships": { "market": { "links": {...} }, "customer": { "links": {...} }, "shipping_address": { "links": {...} }, "billing_address": { "links": {...} }, "available_payment_methods": { "links": {...} }, "available_customer_payment_sources": { "links": {...} }, "payment_method": { "links": {...} }, "payment_source": { "links": {...} }, "line_items": { "links": {...} }, "shipments": { "links": {...} }, "transactions": { "links": {...} }, "authorizations": { "links": {...} }, "captures": { "links": {...} }, "voids": { "links": {...} }, "refunds": { "links": {...} }, "order_subscriptions": { "links": {...} }, "order_copies": { "links": {...} }, "attachments": { "links": {...} } }, "meta": { "mode": "test", "organization_id": "JxYabZKcAw" } }, { "other": "... 9 orders (first page)" } ], "meta": { "record_count": 70, "page_count": 7 }, "links": { "first": "https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders?page[number]=1&page[size]=10", "next": "https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders?page[number]=2&page[size]=10", "last": "https://yourdomain.commercelayer.io/api/customers/xYZkjABcde/orders?page[number]=7&page[size]=10" } }

Examples

Fetching a single related resource (1:1 relationship)

Fetching a list of related resources (1:N relationship)

Examples

Fetching a single related resource (1:1 relationship)

Fetching a list of related resources (1:N relationship)