List or Find Customers
Lists all customers associated with your site, or filters results using the search parameter.
Find Customer
Use the search feature with the q query parameter to retrieve an array of customers that matches the search query.
Common use cases are:
- Search by an email
- Search by an Advanced Billing ID
- Search by an organization
- Search by a reference value from your application
- Search by a first or last name
To retrieve a single, exact match by reference, use the lookup endpoint.
Authorization
BasicAuth The username is a Maxio Chargify API key. The password is x.
In: header
Query Parameters
Direction to sort customers by time of creation
Value in
- "asc"
- "desc"
Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.
Use in query page=1.
1 <= value1This parameter indicates how many records to fetch in each request. Default value is 50. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.
Use in query per_page=200.
value <= 20050The type of filter you would like to apply to your search.
Use in query: date_field=created_at.
Value in
- "updated_at"
- "created_at"
The start date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified.
The end date (format YYYY-MM-DD) with which to filter the date_field. Returns subscriptions with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified.
The start date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of start_date.
The end date and time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns subscriptions with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site's time zone will be used. If provided, this parameter will be used instead of end_date.
A search query by which to filter customers (can be an email, an ID, a reference, organization)
Response Body
application/json
curl -X GET "https://example.com/customers.json"[ { "customer": { "first_name": "Kayla", "last_name": "Test", "email": "kayla@example.com", "cc_emails": "john@example.com, sue@example.com", "organization": "", "reference": null, "id": 14126091, "created_at": "2016-10-04T15:22:27-04:00", "updated_at": "2016-10-04T15:22:30-04:00", "address": "", "address_2": "", "city": "", "state": "", "zip": "", "country": "", "phone": "", "verified": null, "portal_customer_created_at": "2016-10-04T15:22:29-04:00", "portal_invite_last_sent_at": "2016-10-04T15:22:30-04:00", "portal_invite_last_accepted_at": null, "tax_exempt": false, "surcharging": false } }, { "customer": { "first_name": "Nick ", "last_name": "Test", "email": "nick@example.com", "cc_emails": "john@example.com, sue@example.com", "organization": "", "reference": null, "id": 14254093, "created_at": "2016-10-13T16:52:51-04:00", "updated_at": "2016-10-13T16:52:54-04:00", "address": "", "address_2": "", "city": "", "state": "", "zip": "", "country": "", "phone": "", "verified": null, "portal_customer_created_at": "2016-10-13T16:52:54-04:00", "portal_invite_last_sent_at": "2016-10-13T16:52:54-04:00", "portal_invite_last_accepted_at": null, "tax_exempt": false, "surcharging": true, "parent_id": 123 } }, { "customer": { "first_name": "Don", "last_name": "Test", "email": "don@example.com", "cc_emails": "john@example.com, sue@example.com", "organization": "", "reference": null, "id": 14332342, "created_at": "2016-10-19T10:49:13-04:00", "updated_at": "2016-10-19T10:49:19-04:00", "address": "1737 15th St", "address_2": "", "city": "Boulder", "state": "CO", "zip": "80302", "country": "US", "phone": "", "verified": null, "portal_customer_created_at": "2016-10-19T10:49:19-04:00", "portal_invite_last_sent_at": "2016-10-19T10:49:19-04:00", "portal_invite_last_accepted_at": null, "tax_exempt": false, "surcharging": false, "parent_id": null } }]Update Subscription Note PUT
Updates a note for a subscription.
Create Customer POST
Creates a new customer; can also be created alongside a new subscription. The only validation restriction is that you can only create one customer for a given reference value. If provided, the `reference` value must be unique. It represents a unique identifier for the customer from your own app, i.e. the customer’s ID. This allows you to retrieve a given customer via a piece of shared information. Alternatively, you can choose to leave `reference` blank, and store the system-assigned unique ID for the customer, which is in the `id` attribute. For more information, see [Customer Details](https://maxio.zendesk.com/hc/en-us/articles/24252190590093-Customer-Details). ## Required Country Format Format the country attribute of the customer using the ISO Standard Country codes. Countries should be formatted as two characters. For more information, see [ISO 3166-1](http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes). ## Required State Format Format the state attribute of the customer using the ISO Standard State codes. + US States (two characters): see [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:US). + States Outside the US (two to three characters): To find the correct state codes outside the US, go to [ISO 3166-1](http://en.wikipedia.org/wiki/ISO_3166-1#Current_codes) and click on the link in the “ISO 3166-2 codes” column next to the country you wish to populate. ## Locale You can attribute a language/region to the customer to deliver invoices in any required language. For more information, see [Customer Locale](https://maxio.zendesk.com/hc/en-us/articles/24286672013709-Customer-Locale). ## 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. 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. A blank pair is ignored rather than rejected, so a `vat_number` sent alongside it still takes effect. 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`. The response reports the stored identifier in `entity_identifier_kind` and `entity_identifier_value`, and repeats its value in `vat_number`.