Expanding relationships

Many of the Pelcro objects have relationships with each other; for example, a Subscription object will always be related to a Plan object, and may or may not be related to an Address object. It's sometimes useful to get a sense of the relationships which each object's endpoints has with others.

For the purpose of getting insight on object relationships, you can include the expand query parameter as part of your API calls to selected object endpoints to list the details of the objects' relationships as part of the API response.

Let's consider the following example:

If you make an API call to the https://www.pelcro.com/api/v1/core/subscriptions/{$subscription_id} to fetch a specific subscription, the default behavior for the API response is to return the unique identifiers of the related objects, as shown below:

{
  "data": {
    "id": 104,
    "address": 19,
    "plan": 327,
    "coupon": 21,
    "default_source": 61,
    "latest_invoice": 262,
    "address_required": true,
    "billing": "charge_automatically",
    "cancel_at": null,
    "cancel_at_period_end": 0,
    "canceled_at": 1616245121,
    "created": 1616245118,
    "current_period_end": 1618923518,
    "current_period_start": 1616245118,
    "days_until_due": null,
    "ended_at": 1616362240,
    "quantity": 1,
    "status": "canceled",
    "trial_end": null,
    "trial_start": null,
    "is_gift_donor": null,
    "is_gift_recipient": null,
    "due_date": null,
    "gift_code": null,
    "is_redeemed": null,
    "cancel_reason": null,
    "shipments_remaining": 5,
    "schedule": null,
    "expires_at": 1616362240,
    "renews_at": null
  },
  "status": "success"
}

But, what if you want the details of those related objects in one go? That's where the expand query parameter comes into play.

For each of the relationships which you want the details for, you can selectively amend the API call to include the desired objects in the query parameters. For example, if you would like to get the details of the address and plan associated top a single subscription, you can use the following modified API call:

https://www.pelcro.com/api/v1/core/subscriptions/{$subscription_id}?expand=address,plan

{
  "data": {
    "id": 104,
    "address": {
      "id": 19,
      "type": "shipping",
      "user_id": 14,
      "is_default": true,
      "first_name": "Lou",
      "last_name": "Barre",
      "line1": "9639 Clara Joubert",
      "line2": null,
      "city": "Wehnerland",
      "country": "CA",
      "company": null,
      "title": null,
      "department": null,
      "state": "SK",
      "postal_code": "C4R 4U8",
      "phone": "15147732577",
      "created_at": 1616081809,
      "updated_at": 1616081809
    },
    "plan": {
      "id": 327,
      "active": "active",
      "product_id": 25,
      "amount": 1000000,
      "currency": "cad",
      "countries": null,
      "entitlements": null,
      "interval": "month",
      "interval_count": 1,
      "auto_renew": false,
      "metadata": {
        "pelcro_product_id": "25",
        "pelcro_plan_id": "327"
      },
      "nickname": "10,000.00$ \/ 1 month - non auto-renew",
      "trial_period_days": 0,
      "description": null,
      "gift_description": null,
      "apple_product_id": null,
      "image": null,
      "available_online": true,
      "renewal_strategy": null,
      "shipments_per_interval": 12
    },
    "coupon": 21,
    "default_source": 61,
    "latest_invoice": 262,
    "address_required": true,
    "billing": "charge_automatically",
    "cancel_at": null,
    "cancel_at_period_end": 0,
    "canceled_at": 1616245121,
    "created": 1616245118,
    "current_period_end": 1618923518,
    "current_period_start": 1616245118,
    "days_until_due": null,
    "ended_at": 1616362240,
    "quantity": 1,
    "status": "canceled",
    "trial_end": null,
    "trial_start": null,
    "is_gift_donor": null,
    "is_gift_recipient": null,
    "due_date": null,
    "gift_code": null,
    "is_redeemed": null,
    "cancel_reason": null,
    "shipments_remaining": 5,
    "schedule": null,
    "expires_at": 1616362240,
    "renews_at": null
  },
  "status": "success"
}

See the table below for a list of all resources and their respective endpoints supporting relationships expansion.

Expandable relationships

Resource	Endpoints	Expandable relationships
Customer	List	`addresses`, `defaultSource`, `organization`, `subscriptions`
Membership	List, Get	`user`, `subscription`
Order	List	`user`, `address`, `items`
Refund	List	`charge`
Subscription	List, Get	`address`, `plan`, `coupon`, `defaultSource`, `latestInvoice`