Customers

Read Customer by Reference

GET
/customers/lookup.json

Returns a customer by their unique reference ID. It will return a single match.

Authorization

BasicAuth
AuthorizationBasic <token>

The username is a Maxio Chargify API key. The password is x.

In: header

Query Parameters

reference*string

Customer reference

Response Body

application/json

curl -X GET "https://example.com/customers/lookup.json?reference=string"
{  "customer": {    "first_name": "string",    "last_name": "string",    "email": "string",    "cc_emails": "string",    "organization": "string",    "reference": "string",    "id": 0,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z",    "address": "string",    "address_2": "string",    "city": "string",    "state": "string",    "state_name": "string",    "zip": "string",    "country": "string",    "country_name": "string",    "phone": "string",    "verified": true,    "portal_customer_created_at": "2019-08-24T14:15:22Z",    "portal_invite_last_sent_at": "2019-08-24T14:15:22Z",    "portal_invite_last_accepted_at": "2019-08-24T14:15:22Z",    "tax_exempt": true,    "surcharging": true,    "vat_number": "string",    "vat_country": "string",    "entity_identifier_kind": "vat_eu",    "entity_identifier_value": "string",    "parent_id": 0,    "locale": "string",    "default_subscription_group_uid": "string",    "salesforce_id": "string",    "tax_exempt_reason": "string",    "default_auto_renewal_profile_id": 0,    "maxioid": "string",    "branding_theme_id": 0  }}

Update Customer PUT

Updates the customer. ## Tax and Business Identifiers Send `entity_identifier_kind` and `entity_identifier_value` together to store the customer's tax or business identifier, such as an EU VAT number, a French SIREN, or a LEI. A customer holds one identifier at a time, so saving an identifier of a different kind replaces the existing one. The `vat_eu` and `national_tax` kinds also require `vat_country`. An unsupported kind, a missing or mismatched `vat_country`, or a `gln`, `duns`, or `lei` value in the wrong format returns `422`. Always send the kind. `entity_identifier_value` on its own is stored as a `company_reg` when no `vat_country` is present, and returns `422` naming `entity_identifier_kind` when one is. To clear an identifier, send a supported `entity_identifier_kind` with a blank `entity_identifier_value`, or send a blank `vat_number` on its own. The first form also clears `vat_number` and `vat_country`, and it removes whichever identifier the customer holds, whatever kind you send with it. The legacy `vat_number` and `vat_country` pair still works on its own. When neither entity identifier field is sent, Advanced Billing derives the kind from `vat_country`: an EU member state code or `GB` gives `vat_eu`, one of the national tax country codes gives `national_tax`, and a blank or unrecognized country gives `company_reg`. Sending a customer response straight back leaves the tax ID alone. A blank pair, and a pair that still matches the stored identifier with `vat_country` unchanged, are read as nothing to change rather than as a request to clear. For `gln`, `duns`, and `lei` that also covers the `vat_number` the response mirrors back, so the kind survives the round trip. What you do change is applied, and the entity identifier fields take precedence over `vat_number`. A different kind or value writes that identifier, and `vat_number` and `vat_country` follow from it. A different `vat_country` next to an unchanged pair is a real edit, so it is validated and can return `422`. Changing only `vat_number` leaves the pair unchanged, so the derivation above decides the kind, which turns a `gln`, `duns`, or `lei` customer into a `company_reg`. Setting `vat_number` to `null` or a blank string still clears the identifier. The response reports the stored identifier in `entity_identifier_kind` and `entity_identifier_value`, and repeats its value in `vat_number`.

List Customer Subscriptions GET

Lists all subscriptions that belong to a customer. If you have the new [Catalog experience](https://maxio-test-wp.pages.dev/support/announcements/2026-announcements#new-catalog-experience-and-terminology) enabled, subscriptions no longer require an associated product. For subscriptions without an associated product, 'product', 'product_price_point_id', and 'product_price_point_type' are returned as 'null'.