> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integrateledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete a customer

> Remove a customer and everything Ledger holds for it, optionally with its Stripe customer.

Deletes the customer with its subscriptions, credit grants, usage and purchases. Creating the same `customerId` afterwards starts a new, empty customer.

* A customer with a paid subscription that isn't cancelled returns `409 active_paid_subscription`, because deleting only Ledger's record would leave Stripe charging them. Pass `deleteInStripe=true` to delete the Stripe customer too, which cancels its Stripe subscriptions.
* Usage events are deleted in Sandbox. In Live they're kept, as the record of what the customer used.

The SDKs don't have this method yet, so the examples call the API directly. Needs the **Customers** permission at Write.

```bash cURL theme={"system"}
curl -X DELETE "https://api.integrateledger.com/v1/customers?customerId=user_123&deleteInStripe=true" \
  -H "Authorization: Bearer $LEDGER_API_KEY"
```

```typescript TypeScript theme={"system"}
import ledger from "integrateledger";

const client = new ledger({ apiKey: process.env.LEDGER_API_KEY ?? "" });

const url = new URL("https://api.integrateledger.com/v1/customers");
url.searchParams.set("customerId", "user_123");
url.searchParams.set("deleteInStripe", "true");

const response = await fetch(url, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.LEDGER_API_KEY}` },
});
console.log(response.status, await response.json());
```

```python Python theme={"system"}
import os
from integrateledger import ledger

client = ledger(api_key=os.environ["LEDGER_API_KEY"])

import json
from urllib.parse import urlencode
from urllib.request import Request, urlopen

query = urlencode({"customerId": "user_123", "deleteInStripe": "true"})
request = Request(
    f"https://api.integrateledger.com/v1/customers?{query}",
    method="DELETE",
    headers={"Authorization": f"Bearer {os.environ['LEDGER_API_KEY']}"},
)
with urlopen(request) as response:
    print(json.load(response))
```

```json 200 theme={"system"}
{
  "customerId": "user_123",
  "deleted": true
}
```

```json 409 theme={"system"}
{
  "error": "active_paid_subscription"
}
```


## OpenAPI

````yaml openapi.json DELETE /v1/customers
openapi: 3.1.0
info:
  title: Ledger API
  version: 0.1.0
servers:
  - url: https://api.integrateledger.com
    description: Hosted Ledger API
security: []
paths:
  /v1/customers:
    delete:
      tags:
        - Customers
      summary: Delete a customer
      description: >-
        Leave out deleteInStripe to keep the Stripe customer; a customer with an
        uncanceled paid subscription then returns 409.
      operationId: deleteCustomer
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 255
          required: true
          name: customerId
          in: query
        - schema:
            type: boolean
            description: >-
              Also delete the customer's Stripe customer, which cancels its
              Stripe subscriptions. Required when it has one that isn't
              canceled.
          required: false
          description: >-
            Also delete the customer's Stripe customer, which cancels its Stripe
            subscriptions. Required when it has one that isn't canceled.
          name: deleteInStripe
          in: query
      responses:
        '200':
          description: Customer deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDeleted'
        '400':
          description: Invalid customer ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '401':
          description: Missing or invalid Ledger API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '404':
          description: Customer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '409':
          description: >-
            The customer has a paid Stripe subscription that isn't canceled;
            pass deleteInStripe=true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: deleteInStripe was set, but Stripe isn't connected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerError'
      security:
        - ApiKey: []
      x-codeSamples:
        - lang: python
          label: Python SDK
          source: >-
            import os

            from integrateledger import ledger


            client = ledger(api_key=os.environ["LEDGER_API_KEY"])

            client.delete_customer(customer_id="user_123",
            delete_in_stripe=True)
        - lang: bash
          label: cURL
          source: >-
            curl --request DELETE
            'https://api.integrateledger.com/v1/customers?customerId=user_123&deleteInStripe=true'
            \
              -H "Authorization: Bearer $LEDGER_API_KEY"
        - lang: typescript
          label: TypeScript SDK
          source: >-
            import ledger from "integrateledger";


            const client = new ledger({ apiKey: process.env.LEDGER_API_KEY ?? ""
            });

            await client.deleteCustomer({ customerId: "user_123",
            deleteInStripe: true });
components:
  schemas:
    CustomerDeleted:
      type: object
      properties:
        customerId:
          type: string
        deleted:
          type: boolean
          const: true
      required:
        - customerId
        - deleted
    CustomerError:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: rate_limited
      required:
        - error
  responses:
    RateLimited:
      description: >-
        Too many requests. Wait Retry-After seconds, then retry. See the rate
        limits guide.
      headers:
        Retry-After:
          description: Seconds until a request is allowed again
          schema:
            type: integer
        RateLimit-Limit:
          description: 'The burst: requests allowed at once'
          schema:
            type: integer
        RateLimit-Remaining:
          description: Requests left right now
          schema:
            type: integer
        RateLimit-Reset:
          description: Seconds until the full burst is back
          schema:
            type: integer
        RateLimit-Policy:
          description: >-
            The sustained rate per second and the burst, such as
            200;w=1;burst=1000
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.