Expanding resources

If you look at the description of the Invoice object, you will notice that some of its fields are marked as expandable. For example, the customer field of Invoice is an expandable Customer object. What this means is that the field represents another resource object stored elsewhere. By default, only the id value of the Customer sub-resource is fetched when you fetch the Invoice object. You can use this id to retrieve the sub-resource using the find() function for that object type in a separate API call. However, you also have the option to expand the sub-resource, which means that all of its data will be included in the main resource as well as its id value.

The find() function for each resource type has an options parameter that comes after the id that you want to fetch. One of the options is an expand array that lists the names of all fields that you want to expand when you fetch the main object.

The sub-resources may have other nested sub-resources of their own. Supply a "path" to expand these nested fields using the familiar object dot notation. For example, to expand the Tokens field of a Customer in a Transaction, you can set expand to customer.tokens when you fetch the Transaction object. This will first expand the transaction's customer field, and then the Customer object's tokens field.

curl https://api.processout.com/invoices/iv_0kJ1i4d06uViosJjCKpUHzKeauffMom4 \
    -u test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x:key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB \
    --data-urlencode expand[]=customer

var ProcessOut = require("processout");
var client = new ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

client.newInvoice().find("iv_0kJ1i4d06uViosJjCKpUHzKeauffMom4", {
    expand: ["tokens"]
}).then(
    function(invoice) {
        // Invoice was fetched
    }, function(err) {
        // An error occured
    });

import processout
client = processout.ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")

customer = client.new_invoice().find("iv_0kJ1i4d06uViosJjCKpUHzKeauffMom4", {
    "expand": ["customer"]
})

require "processout"
client = ProcessOut::Client.new(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB")

customer = client.invoice.find("iv_0kJ1i4d06uViosJjCKpUHzKeauffMom4", {
    expand: ["customer"]
})

<?php
$client = new \ProcessOut\ProcessOut(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB");

$customer = $client->newInvoice()->find("iv_0kJ1i4d06uViosJjCKpUHzKeauffMom4", array(
    "expand" => array("customer")
));

import "github.com/processout/processout-go"

var client = processout.New(
    "test-proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x", 
    "key_sandbox_mah31RDFqcDxmaS7MvhDbJfDJvjtsFTB",
)

cust, err := client.NewInvoice().Find("iv_0kJ1i4d06uViosJjCKpUHzKeauffMom4", 
    processout.InvoiceFindParameters{
        Options: &processout.Options{
            Expand: []string{"customer"},
        }),
    })

If you compare the response to the one generated without expanding the customer field, you can see that both the full details of the customer and the customer_id are now included as separate fields, while the rest of the Invoice is the same as before.

{
    "invoice": {
        "id": "iv_0kJ1i4d06uViosJjCKpUHzKeauffMom4",
        "project_id": "proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
        "subscription_id": null,
        "customer": {
            "id": "cust_CgdhFgj5QEv5I8dx6tHxVVrgxBDDzAgc",
            "project_id": "proj_gAO1Uu0ysZJvDuUpOGPkUBeE3pGalk3x",
            "tokens": null,
            "subscriptions": null,
            "transactions": null,
            "balance": "0",
            "currency": "AUD",
            "email": "[email protected]",
            "first_name": "John",
            "last_name": "Smith",
            "address1": "999 Letsby Avenue",
            .
            .
        },
        "customer_id": "cust_CgdhFgj5QEv5I8dx6tHxVVrgxBDDzAgc",
        "token_id": null,
        "details": null,
        .
        .
}