Retrieve a customer
GET / v1 / customers /:id
Retrieves a Customer object.
Parameters
No parameters.
Returns
Returns the Customer object for a valid identifier. If it’s for a deleted Customer, a subset of the customer’s information is returned, including a deleted property that’s set to true.
Response
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", "address": null, "balance": 0, "created": 1680893993, "currency": null, "default_source": null, "delinquent": false, "description": null, "email": "jennyrosen@example.com", "invoice_prefix": "0759376C", "invoice_settings": { "custom_fields": null, "default_payment_method": null, "footer": null, "rendering_options": null }, "livemode": false, "metadata": {}, "name": "Jenny Rosen", "next_invoice_sequence": 1, "phone": null, "preferred_locales": [], "shipping": null, "tax_exempt": "none", "test_clock": null}
List all customers
GET / v1 / customers
Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.
Parameters
- email string A case-sensitive filter on the list based on the customer’s
emailfield. The value must be a string. The maximum length is 512 characters.
More parameters
- created object
- ending _ before string
- limit integer
- starting _ after string
- test _ clock string
Returns
A dictionary with a data property that contains an array of up to limit customers, starting after customer starting_after. Passing an optional email will result in filtering to customers with only that exact email address. Each entry in the array is a separate customer object. If no more customers are available, the resulting array will be empty.
Response
{ "object": "list", "url": "/v1/customers", "has_more": false, "data": [ { "id": "cus_NffrFeUfNV2Hib", "object": "customer", "address": null, "balance": 0, "created": 1680893993, "currency": null, "default_source": null, "delinquent": false, "description": null, "email": "jennyrosen@example.com", "invoice_prefix": "0759376C", "invoice_settings": { "custom_fields": null, "default_payment_method": null, "footer": null, "rendering_options": null }, "livemode": false, "metadata": {}, "name": "Jenny Rosen", "next_invoice_sequence": 1, "phone": null, "preferred_locales": [], "shipping": null, "tax_exempt": "none", "test_clock": null } ]}
Delete a customer
DELETE / v1 / customers /:id
Permanently deletes a customer. It cannot be undone. Also immediately cancels any active subscriptions on the customer.
Parameters
No parameters.
Returns
Returns an object with a deleted parameter on success. If the customer ID does not exist, this call raises an error.
Unlike other objects, deleted customers can still be retrieved through the API in order to be able to track their history. Deleting customers removes all credit card details and prevents any further operations to be performed (such as adding a new subscription).
Response
{ "id": "cus_NffrFeUfNV2Hib", "object": "customer", "deleted": true}