> ## 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.

# Create or get a customer

> Create a customer from an application ID in the selected environment, or return the existing customer.

Creates a customer using your application's stable user ID in the environment selected by your API key, or returns the customer already associated with that ID. Send a nonempty `customerId` of at most 255 characters. The response echoes it with `created: true` for a new record or `created: false` for a repeat call.

This operation is safe to retry and does not attach a plan, create a Stripe customer, or grant credits by itself. The API key scopes the ID to your organization; another organization can use the same customer ID independently. After creation, use [Attach a plan or add-on](https://docs.integrateledger.com/api-reference/billing/attach.md) to start billing, then [Check credits](https://docs.integrateledger.com/api-reference/usage/check.md) to read the balance.

Invalid input returns `400 invalid_request`; a missing or invalid key returns `401 unauthorized`. See [Customers](https://docs.integrateledger.com/customers.md) for the complete lifecycle.


## OpenAPI

````yaml openapi.json POST /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:
    post:
      tags:
        - Customers
      summary: Create or get a customer
      operationId: createOrGetCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerInput'
      responses:
        '200':
          description: Customer created or returned without granting credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
        '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'
      security:
        - ApiKey: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request POST 'https://api.integrateledger.com/v1/customers' \
              -H "Authorization: Bearer $LEDGER_API_KEY" \
              -H 'Content-Type: application/json' \
              --data '{"customerId":"user_123"}'
        - lang: python
          label: Python SDK (source only)
          source: |-
            import os
            from ledger_sdk import Ledger

            ledger = Ledger(api_key=os.environ["LEDGER_API_KEY"])
            ledger.create_or_get_customer(customer_id="user_123")
        - lang: typescript
          label: TypeScript SDK (source only)
          source: >-
            import { Ledger } from "@ledger/sdk";


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

            await ledger.createOrGetCustomer({ customerId: "user_123" });
components:
  schemas:
    CreateCustomerInput:
      type: object
      properties:
        customerId:
          type: string
          minLength: 1
          maxLength: 255
      required:
        - customerId
      additionalProperties: false
    CustomerResponse:
      type: object
      properties:
        customerId:
          type: string
        created:
          type: boolean
      required:
        - customerId
        - created
    CustomerError:
      type: object
      properties:
        error:
          type: string
      required:
        - error
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer

````

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