> ## Documentation Index > Fetch the complete documentation index at: https://lava.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create customer > Create a customer record with merchant-scoped contact info. The customer can be assigned free plans and use the proxy immediately. To link a payment method, direct them through checkout. Idempotent when reference_id is provided (strongly recommended) — returns the existing customer if one matches. ## OpenAPI ````yaml /openapi.json post /customers openapi: 3.0.0 info: title: Lava API description: >- Lava API enables businesses to implement usage-based billing for AI services. This API allows tracking, managing, and billing for third-party AI API usage through a forwarding system. version: 1.0.0 contact: name: Lava support url: https://www.lava.so/contact servers: - url: https://api.lava.so/v1/ description: Lava API v1 security: [] tags: - name: Authentication - name: Core Endpoints - name: Models - name: Services - name: Requests - name: Wallet - name: Payment Methods - name: Spend Keys - name: Usage - name: Checkout Sessions - name: Customers - name: Plans - name: Subscriptions - name: Meters - name: Webhooks - name: Secret Keys - name: Credit Bundles - name: Gateway Settings - name: Skills - name: News Data - name: Search - name: Enrich paths: /customers: post: tags: - Customers summary: Create customer description: >- Create a customer record with merchant-scoped contact info. The customer can be assigned free plans and use the proxy immediately. To link a payment method, direct them through checkout. Idempotent when reference_id is provided (strongly recommended) — returns the existing customer if one matches. requestBody: required: true content: application/json: schema: type: object properties: reference_id: type: string maxLength: 255 example: usr_abc123 description: >- Your external identifier for this customer (strongly recommended). When provided, acts as an idempotency key — creating a customer with the same reference_id returns the existing one. Cannot start with "con_" (reserved prefix). Can be used interchangeably with customer_id in all API endpoints. name: type: string maxLength: 255 example: Jane Smith description: >- Display name. Used as contact hint until the customer authenticates. email: type: string format: email example: jane@example.com description: >- Email address. Used as contact hint and for checkout pre-population. phone: type: string example: '+14155552671' description: >- Phone number in E.164 format. Used as contact hint and for checkout pre-population. metadata: type: object additionalProperties: true nullable: false example: tier: premium source: api description: Arbitrary key-value metadata (max 16KB serialized). responses: '201': description: Customer created content: application/json: schema: $ref: '#/components/schemas/Customer' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' security: - Auth: [] components: schemas: Customer: type: object properties: customer_id: type: string example: con_test_01EXAMPLE00000000000000001 description: Unique identifier for the customer reference_id: type: string nullable: true example: usr_abc123 description: >- Merchant's external identifier for this customer. Used for idempotent creation — POST with the same reference_id returns the existing customer. contact: type: object properties: phone: type: string example: '+14155552671' description: User's phone number in E.164 format email: type: string example: user@example.com description: User's email address first_name: type: string example: Jane description: User's first name last_name: type: string example: Smith description: User's last name required: - phone - email - first_name - last_name subscription: type: object nullable: true properties: subscription_id: type: string description: Subscription ID plan_id: type: string description: Plan ID name: type: string description: Display name of the plan status: type: string enum: - active - cancelled description: Subscription status required: - subscription_id - plan_id - name - status description: Active subscription summary, or null if none metadata: type: object nullable: true additionalProperties: true example: plan_tier: enterprise internal_id: '12345' description: Arbitrary key-value metadata stored on the customer. Set via PATCH. created_at: type: string format: date-time example: '2023-05-15T08:35:42Z' description: ISO 8601 timestamp when the customer was created required: - customer_id - reference_id - contact - subscription - metadata - created_at Error: type: object properties: error: type: object properties: message: type: string description: Human-readable error message describing what went wrong example: Invalid authentication credentials code: type: string description: Machine-readable error code describing what went wrong example: forward_token_json_invalid status: type: integer description: HTTP status code of the error example: 400 issues: type: array items: type: object properties: path: type: array items: type: string description: Path to the field that caused the validation error message: type: string description: Error message describing the validation issue required: - path - message description: >- Optional array of specific validation issues with their paths and messages example: - path: - model message: 'Missing required field: model' - path: - messages - '0' - content message: Invalid message content format required: - message - code - status required: - error securitySchemes: Auth: type: http scheme: bearer description: >- Bearer token authentication used for standard API calls. Format: 'Bearer YOUR_API_KEY' ````