Skip to main content

​
Overview

By default, related objects are returned as IDs. For example, a PaymentIntent’s customer_id field contains just the customer ID string. With the expand parameter, you can ask the API to replace these IDs with the full object in a single request, reducing the number of API calls you need to make.

​
Usage

Pass one or more expand[] query parameters on a GET request to expand nested objects. 
curl "https://api.leanrails.com/v1/payment_intents/pi_1abc123def456?expand[]=customer" \
  -u "$API_KEY:"

​
Without expand

{
  "id": "pi_1abc123def456",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "succeeded",
  "customer_id": "cus_abc123",
  "metadata": {},
  "livemode": false,
  "created_at": "2026-03-09T10:00:00Z",
  "updated_at": "2026-03-09T10:00:05Z"
}

​
With expand[]=customer

{
  "id": "pi_1abc123def456",
  "object": "payment_intent",
  "amount": 2000,
  "currency": "usd",
  "status": "succeeded",
  "customer_id": "cus_abc123",
  "customer": {
    "id": "cus_abc123",
    "object": "customer",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "metadata": {},
    "livemode": false,
    "created_at": "2026-02-15T08:30:00Z",
    "updated_at": "2026-03-01T12:00:00Z"
  },
  "metadata": {},
  "livemode": false,
  "created_at": "2026-03-09T10:00:00Z",
  "updated_at": "2026-03-09T10:00:05Z"
}

​
Code example

const fetch = require("node-fetch");

const API_KEY = process.env.API_KEY;
const credentials = Buffer.from(`${API_KEY}:`).toString("base64");

const url = new URL("https://api.leanrails.com/v1/payment_intents/pi_1abc123def456");
url.searchParams.append("expand[]", "customer");

const response = await fetch(url.toString(), {
  headers: {
    Authorization: `Basic ${credentials}`,
  },
});

const paymentIntent = await response.json();

// Access the full customer object directly
console.log(paymentIntent.customer.name);  // "Jane Doe"
console.log(paymentIntent.customer.email); // "jane@example.com"

​
Supported expansions

Expand is currently supported on the PaymentIntent detail endpoint (GET /v1/payment_intents/:id).
EndpointExpandable fields
GET /v1/payment_intents/:idcustomer
Support for additional expandable fields and endpoints will be added in future API versions.

​
Multiple expansions

You can expand multiple fields in a single request by passing multiple expand[] parameters: 
curl "https://api.leanrails.com/v1/payment_intents/pi_1abc123def456?expand[]=customer&expand[]=payment_method" \
  -u "$API_KEY:"

​
Error handling

If you request an expansion that is not supported, the API returns a 400 error: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "The field 'invoice' is not expandable on this endpoint.",
    "param": "expand[]",
    "doc_url": "https://docs.leanrails.com/errors/parameter_invalid"
  }
}