Skip to main content

Expanding Model Relations

Many models allow you to request additional information relational models by using the with method. This parameter is available on all models, and applies to the response of that model only. Model relations can be expanded in two ways.

Expanding a single relation

In many cases, an object contains the ID of a related object in its response properties. For example, a price has an associated product ID. Those models can be queried together in one call. ID fields that can be expanded into models are noted in this documentation with the expandable label. Here's an example:

$prices = \SureCart\Models\Price::with([
])->paginate(['page'=> 1]);
$promo = \SureCart\Models\Promotion::with([

$coupon = $promotion->coupon;

Expanding list relations

In some cases, such as a list of all prices for a product, there are available fields that are not included in responses by default. You can request these fields as an expanded response by using the with method. Fields that can be included in an expanded response are noted in this documentation with the expandable label.

$products = \SureCart\Models\Product::with([
])->paginate(['page'=> 1]);

Recursively expanding relations

You can expand recursively by specifying nested fields after a dot (.). For example, requesting customer and customer.billing_address on an order will expand the customer and the customer's billing_address.

$orders = \SureCart\Models\Order::with([
])->paginate(['page'=> 1]);

foreach($orders as $order) {
$billing_address = $order->customer->billing_address;

You can use the with method on any endpoint which returns expandable fields, including list, create, and update endpoints.

Expanding list requests are plural, but expanding objects within a list are singular. For example, if you wanted to retrieve a order's line items and each line item's price, you would pass list_items and list_item.price as expand parameters.


$orders = \SureCart\Models\Order::with( [
] )->paginate( [ 'page' => 1 ] );

foreach($orders as $order) {
foreach($order->line_items as $line_item) {
$product = $line_item->price->product;

Complex Example:

$charges = \SureCart\Models\Charge::where([
'customer_ids' => [ $customer_id ],
])->with( [
] )->get();

foreach($charges as $charge) {
// get charged line items.
foreach($charge->line_items as $line_item) {
$product = $line_item->price->product;

You can expand multiple objects at once by identifying multiple items in the with array. Expansions have a maximum depth of two levels, and you can expand up to 10 objects.

This is not only limited to get or paginate. You can use this on create or update requests as well. This will allow you to create or update a model and fetch it's relations all in one request.

'name' => 'New Price',
'amount' => 5000, // $50.00
'currency' => 'usd',
'product' => '8ba8d60f-5277-4e6b-807c-dee8166446d5',