Core Resources
Payment Methods
Products
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

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.

curl https://api.stripe.com/v1/customers/ \
  -u "sk_test_VePHdqK...NInc7u56JBrQsk_test_VePHdqKTYQjKNInc7u56JBrQ:"
Response
{
  "id": "",
  "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

  • emailstring

    A case-sensitive filter on the list based on the customer’s email field. The value must be a string.

    The maximum length is 512 characters.

More parameters

  • createdobject

  • ending_beforestring

  • limitinteger

  • starting_afterstring

  • test_clockstring

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.

curl -G https://api.stripe.com/v1/customers \
  -u "sk_test_VePHdqK...NInc7u56JBrQsk_test_VePHdqKTYQjKNInc7u56JBrQ:" \
  -d limit=3
Response
{
  "object": "list",
  "url": "/v1/customers",
  "has_more": false,
  "data": [
    {
      "id": "",
      "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).

curl -X DELETE https://api.stripe.com/v1/customers/ \
  -u "sk_test_VePHdqK...NInc7u56JBrQsk_test_VePHdqKTYQjKNInc7u56JBrQ:"
Response
{
  "id": "",
  "object": "customer",
  "deleted": true
}