Invoicing on Behalf of Another Account

This is an advanced feature for platforms that run more than one account in the same account hierarchy. If you just need to bill your own customers, see the Invoices guide — you don't need this.

An account can let another account invoice its customers on its behalf — for example, a head-office account that bills the customers of its subsidiaries. Granting servicing access is a permission grant, so it is always made by the serviced account — the one whose customers will be invoiced.

API reference

Use updateAccount on the serviced account, setting capabilities.billing.invoice.servicing_accounts to the operator accounts that should be allowed to invoice its customers. Only the fields you populate are updated; everything else is left unchanged.

curl -X POST https://api.synaptopay.com/v1/accounts/acct_SERVICED \
  -H "Authorization: Api-Key $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": {
      "capabilities": {
        "billing": {
          "invoice": {
            "servicing_accounts": ["accounts/acct_OPERATOR"]
          }
        }
      }
    }
  }'

Every listed account must belong to the same account hierarchy as the serviced account — that is, share the same top-level parent (parent_account_name) — and can't be the serviced account itself. To revoke the grant, send the same request with an empty servicing_accounts list (keep the surrounding invoice object so the backend treats it as an intentional empty list, not "leave unchanged").

Once set, acct_OPERATOR invoices the serviced account's customers using its own account: it creates the invoice under acct_OPERATOR and points the invoice's customer at the serviced customer, e.g. accounts/acct_SERVICED/customers/cus_X. The operator owns the resulting invoice (accounts/acct_OPERATOR/invoices/inv_Y) and collects it via its own MID — the customer simply lives under a different account. Customer resources themselves still belong to the serviced account and are addressed there.

The grant covers the billing-invoice surface on the public API, split two ways. On the serviced account's rows, the operator can call createCustomer, getCustomer, the invoice-item RPCs (createInvoiceItem, getInvoiceItem, deleteInvoiceItem), and createInvoice for a serviced customer. The invoices it raises are its own, so getInvoice, finalizeInvoice, payInvoice, voidInvoice, markInvoiceUncollectible, addInvoiceLine, and removeInvoiceLine act under acct_OPERATOR, not the serviced account.

Servicing invoices are collected like any other: finalize the invoice and send the customer its hosted_invoice_url, where they pay on Synapto's hosted page. The operator can't autopay a servicing invoice with the serviced customer's saved payment method — payInvoice requires the payment method and the invoice to sit on the same account, and here the invoice is the operator's while the method belongs to the serviced account. Nor can the operator save a method for the serviced customer: a setup intent or SETUP-mode checkout session needs payments.write on the account that owns the customer, so payment-method setup stays with the serviced account.

For a worked example — a platform that lets its providers bill platform-level customers — see Charging Platform Fees.

Listing is strict by URL parent: listInvoices and listCustomers return only rows owned by the account in the URL. Because the servicing invoices you raise are owned by the operator, they appear under parent=accounts/acct_OPERATOR, while the serviced account's customers appear under parent=accounts/acct_SERVICED — so to see both you make two calls.