---
title: "Create Customer"
method: POST
path: "/api/v1/customers"
tags: ["Customer"]
---

# Create Customer

`POST /api/v1/customers`

## Request body

- object
  - `customer` CustomerClientInsertSchema, required
    - `email` string, required
    - `name` string, required
    - `archived` boolean
    - `logoURL` string, nullable
    - `iconURL` string, nullable
    - `domain` string, nullable
    - `externalId` string, required
    - `userId` string, nullable

## Response `200`

Successful response

- object
  - `data` object, required
    - `customer` CustomerClientSelectSchema, required
      - `id` string, required
      - `createdAt` integer, required — Epoch milliseconds.
      - `updatedAt` integer, required — Epoch milliseconds.
      - `livemode` boolean, required
      - `organizationId` string, required
      - `email` string, required
      - `name` string, required
      - `invoiceNumberBase` string, nullable, required
      - `archived` boolean, required
      - `logoURL` string, nullable, required
      - `iconURL` string, nullable, required
      - `domain` string, nullable, required
      - `billingAddress` BillingAddress
        - `name` string, nullable
        - `firstName` string, nullable
        - `lastName` string, nullable
        - `email` string, email, nullable
        - `address` object, required
          - `name` string, nullable
          - `line1` string, nullable
          - `line2` string, nullable
          - `city` string, nullable
          - `state` string, nullable
          - `postal_code` string, nullable
          - `country` string, required
        - `phone` string, nullable
      - `externalId` string, required
      - `userId` string, nullable, required
      - `pricingModelId` string, required
    - `subscription` union
      - object
        - `id` string, required
        - `createdAt` integer, required — Epoch milliseconds.
        - `updatedAt` integer, required — Epoch milliseconds.
        - `livemode` boolean, required
        - `startDate` integer, required — Epoch milliseconds.
        - `customerId` string, required
        - `organizationId` string, required
        - `status` 'trialing' | 'active' | 'past_due' | 'unpaid' | 'cancellation_scheduled' | 'incomplete' | 'incomplete_expired' | 'canceled' | 'paused', required
        - `defaultPaymentMethodId` string, nullable, required
        - `backupPaymentMethodId` string, nullable, required
        - `trialEnd` integer, nullable — Epoch milliseconds.
        - `currentBillingPeriodStart` integer, nullable — Epoch milliseconds.
        - `currentBillingPeriodEnd` integer, nullable — Epoch milliseconds.
        - `metadata` Metadata — JSON object
        - `canceledAt` integer, nullable — Epoch milliseconds.
        - `cancelScheduledAt` integer, nullable — Epoch milliseconds.
        - `cancellationReason` string, nullable, required
        - `replacedBySubscriptionId` string, nullable, required
        - `isFreePlan` boolean, nullable, required
        - `doNotCharge` boolean, nullable, required
        - `priceId` string, required
        - `runBillingAtPeriodStart` boolean, nullable, required
        - `interval` 'day' | 'week' | 'month' | 'year', required
        - `intervalCount` integer, required — A positive integer
        - `billingCycleAnchorDate` integer, nullable — Epoch milliseconds.
        - `name` string, nullable, required
        - `renews` true, required
        - `pricingModelId` string, required
        - `current` boolean, required — Whether the subscription is current (statuses "active", "trialing", "past_due", or "cancellation_scheduled")
      - object
        - `id` string, required
        - `createdAt` integer, required — Epoch milliseconds.
        - `updatedAt` integer, required — Epoch milliseconds.
        - `livemode` boolean, required
        - `startDate` integer, required — Epoch milliseconds.
        - `customerId` string, required
        - `organizationId` string, required
        - `status` 'active' | 'canceled' | 'credit_trial', required
        - `defaultPaymentMethodId` string, nullable, required
        - `backupPaymentMethodId` string, nullable, required
        - `trialEnd` unknown, required
        - `currentBillingPeriodStart` unknown, required
        - `currentBillingPeriodEnd` unknown, required
        - `metadata` Metadata — JSON object
        - `canceledAt` integer, nullable — Epoch milliseconds.
        - `cancelScheduledAt` integer, nullable — Epoch milliseconds.
        - `cancellationReason` string, nullable, required
        - `replacedBySubscriptionId` string, nullable, required
        - `isFreePlan` boolean, nullable, required
        - `doNotCharge` boolean, nullable, required
        - `priceId` string, required
        - `runBillingAtPeriodStart` boolean, nullable, required
        - `interval` unknown, required
        - `intervalCount` unknown, required
        - `billingCycleAnchorDate` unknown, required
        - `name` string, nullable, required
        - `renews` false, required
        - `pricingModelId` string, required
        - `current` boolean, required — Whether the subscription is current (statuses "active", "trialing", "past_due", "cancellation_scheduled", or "credit_trial")
    - `subscriptionItems` SubscriptionItemRecordOutput[]
      - `id` string, required
      - `createdAt` integer, required — Epoch milliseconds.
      - `updatedAt` integer, required — Epoch milliseconds.
      - `livemode` boolean, required
      - `subscriptionId` string, required
      - `name` string, nullable, required
      - `addedDate` integer, required — Epoch milliseconds.
      - `priceId` string, nullable, required
      - `unitPrice` union, required
        - integer — A positive integer
        - 0
      - `quantity` union, required
        - integer — A positive integer
        - 0
      - `metadata` Metadata — JSON object
      - `type` 'static', required
      - `externalId` string, nullable, required
      - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds.
      - `manuallyCreated` boolean, required
      - `pricingModelId` string, required

## Other responses

- `400` — Invalid input data
- `401` — Authorization not provided
- `403` — Insufficient access
- `500` — Internal server error

## Changes

- **2026-01-14** `7fcbd2dbf3c1` — 1 warning, 1 info
  - removed the request property `customer/pricingModelId`
  - response property `data/customer/pricingModelId` list-of-types was narrowed by removing types `null` from media type `application/json` of response `200`
- **2026-01-11** `599bbd902d65` — 6 info
  - response property `data/subscription/oneOf[#/components/schemas/NonRenewingSubscriptionRecord]/priceId` list-of-types was narrowed by removing types `null` from media type `application/json` of response `200`
  - response property `data/subscription/oneOf[#/components/schemas/StandardSubscriptionRecord]/priceId` list-of-types was narrowed by removing types `null` from media type `application/json` of response `200`
  - added the required property `data/subscription/oneOf[#/components/schemas/NonRenewingSubscriptionRecord]/doNotCharge` to the response with the `200` status
  - added the required property `data/subscription/oneOf[#/components/schemas/NonRenewingSubscriptionRecord]/pricingModelId` to the response with the `200` status
  - …2 more
- **2025-10-18** `a1eeb4fac4d6` — 17 breaking, 6 warning, 13 info
  - the request property `customer/domain` became not nullable
  - the request property `customer/iconURL` became not nullable
  - the request property `customer/logoURL` became not nullable
  - the request property `customer/userId` became not nullable
  - …32 more
- …earlier changes not shown

[Full history](https://skmtc.dev/flowglad/apis/flowglad-api/changes/api/v1/customers/post.md)

---

[API](https://skmtc.dev/flowglad/apis/flowglad-api.md) · [All operations](https://skmtc.dev/flowglad/apis/flowglad-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/flowglad/flowglad-api/revisions/06c4dd78e137/schema)