---
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
    - `pricingModelId` 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, nullable, 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
        - `priceId` string, nullable, 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
        - `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
        - `priceId` string, nullable, required
        - `runBillingAtPeriodStart` boolean, nullable, required
        - `interval` unknown, required
        - `intervalCount` unknown, required
        - `billingCycleAnchorDate` unknown, required
        - `name` string, nullable, required
        - `renews` false, 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, required
      - `unitPrice` union, required
        - integer — A positive integer
        - 0
      - `quantity` integer, required — A positive integer
      - `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.

## Other responses

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

## Changes

- **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
- **2025-04-28** `00982324965d` — 4 info
  - added the optional property `data/customer/billingAddress/address/name` to the response with the `200` status
  - added the optional property `data/customer/billingAddress/email` to the response with the `200` status
  - added the required property `data/customer/createdByCommit` to the response with the `200` status
  - added the required property `data/customer/updatedByCommit` to the response with the `200` status
- **2025-04-04** `230d72f3d008` — 5 breaking
  - the response property `data/customer/billingAddress/address/city` became nullable for the status `200`
  - the response property `data/customer/billingAddress/address/line1` became nullable for the status `200`
  - the response property `data/customer/billingAddress/address/postal_code` became nullable for the status `200`
  - the response property `data/customer/billingAddress/address/state` became nullable for the status `200`
  - …1 more
- **2025-03-24** `085889adb3c1` — 2 info
  - added the new optional request property `customer/catalogId`
  - added the required property `data/customer/catalogId` to the response with the `200` status
- …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/d53efdb1a902/schema)