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 — see example)

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

Examples

Fetching a single related resource (1:1 relationship)

Request

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'

Response

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

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

Request

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'

Response

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": "[email protected]",
        "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"
  }
}

Pagination