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

# Create a customer

> Creates a new customer record within kelviq.

<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>


## OpenAPI

````yaml /api-reference/openapi.json post /customers/
openapi: 3.0.0
info:
  title: kelviq API
  version: 1.0.0
  description: >-
    API for interacting with kelviq services, derived from Python SDK
    documentation.
servers:
  - url: https://sandboxapi.kelviq.com/api/v1
    description: Sandbox — Test payments
  - url: https://api.kelviq.com/api/v1
    description: Production — Live payments
security:
  - bearerAuth: []
tags:
  - name: Products
    description: Catalog products.
  - name: Product Settings
    description: Per-product settings (currency, VPN/Tor/proxy, product URL).
  - name: Product Files
    description: Product images and downloadable assets.
  - name: Features
    description: Catalog features that can be granted as plan entitlements.
  - name: Plans
    description: Catalog plans (CRUD, publish, versions, prices).
  - name: Plan Entitlements
    description: Feature entitlements attached to a plan.
  - name: Plan Files
    description: Files attached to plans, and signed download links.
  - name: Media
    description: Generate presigned S3 upload URLs for product/plan images and files.
  - name: Partner
    description: Partner integration APIs (organization provisioning, lookup).
  - name: Charges
    description: >-
      One-time payments charged immediately against a customer's default payment
      method.
  - name: Refunds
    description: Full and partial refunds for paid orders.
  - name: Payment Methods
    description: Saved customer payment methods (cards, etc.).
paths:
  /customers/:
    post:
      tags:
        - Customers
      summary: Create a customer
      description: Creates a new customer record within kelviq.
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerCreateRequest'
      responses:
        '201':
          description: Customer Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerResponse'
              example:
                id: a1b2c3d4-e5f6-7890-1234-567890abcdef
                customerId: unique-customer-id-123
                name: John Doe
                email: new.customer@example.com
                details: {}
                metadata:
                  source: sdk_import
                  priority: high
                billingAddress:
                  country: IN
                  line1: 123 Main Street
                  line2: Apt 4B
                  postalCode: '560001'
                  city: Bangalore
                  state: Karnataka
                createdOn: '2025-06-04T06:03:30.195790Z'
                modifiedOn: '2025-06-04T06:03:30.195831Z'
components:
  schemas:
    CustomerCreateRequest:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
          description: A unique identifier for the customer that you define.
          example: unique-customer-id-456
        email:
          type: string
          format: email
          nullable: true
          description: The email address of the customer.
          example: another.new.customer@example.com
        name:
          type: string
          nullable: true
          description: The name of the customer.
          example: Jane Roe
        metadata:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: A dictionary of custom key-value pairs.
          example:
            source: sdk_import
            priority: low
        billingAddress:
          $ref: '#/components/schemas/BillingAddress'
    CustomerResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Server-generated unique UUID for the customer record.
          readOnly: true
          example: a1b2c3d4-e5f6-7890-1234-567890abcdef
        customerId:
          type: string
          description: The client-provided customer identifier.
          example: unique-customer-id-123
        name:
          type: string
          nullable: true
          description: The customer's name.
          example: John Doe
        email:
          type: string
          format: email
          nullable: true
          description: The customer's email.
          example: new.customer@example.com
        details:
          type: object
          additionalProperties: true
          description: Any server-added details about the customer (typically read-only).
          readOnly: true
          example: {}
        metadata:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: The metadata associated with the customer.
          example:
            source: sdk_import
            priority: high
        billingAddress:
          $ref: '#/components/schemas/BillingAddress'
        createdOn:
          type: string
          nullable: false
          description: Customer created date and time
          example: '2025-06-04T06:03:30.195790Z'
        modifiedOn:
          type: string
          nullable: false
          description: Customer updated date and time
          example: '2025-06-04T06:03:30.195790Z'
    BillingAddress:
      type: object
      nullable: true
      description: The billing address of the customer.
      properties:
        country:
          type: string
          description: The country code (e.g., ISO 3166-1 alpha-2).
          example: IN
        line1:
          type: string
          description: Address line 1.
          example: 123 Main Street
        line2:
          type: string
          nullable: true
          description: Address line 2.
          example: Apt 4B
        postalCode:
          type: string
          description: The postal or ZIP code.
          example: '560001'
        city:
          type: string
          description: The city name.
          example: Bangalore
        state:
          type: string
          description: The state or province.
          example: Karnataka
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Server API Key obtained from the kelviq application. Pass as a
        Bearer token in the Authorization header. Example: 'Authorization:
        Bearer __YOUR_API_KEY__'

````