Expanding relationships

Expanding relationships helps you reduce the number of requests you make to the Pelcro API.

🚧

This functionality is currently in Beta

  • This functionality is only offered on selected endpoints of the Subscription object for now, capabilities can change at any time.
  • Please report any unexpected behavior to [email protected]

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 return the relationships for the Subscription Address & Plan endpoints, 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"
}

As shown, you'll be able to see the expanded relationships for each selected endpoint in one consolidated view.

For more information regarding object relationships which can be expanded, please refer to the Subscription object attributes.