---
title: "Create a customer"
method: POST
path: "/v1/customers"
tags: ["Customers"]
---

# Create a customer

`POST /v1/customers`

Create a customer. Just pass `externalCustomerId` (your user ID). Add `onchainAddress` later for on-chain billing.

> **Requires a secret key (`sk_*`) with at least the `OPERATOR` role.**

## Request body

- object — Create a customer. At least one of `externalCustomerId` or `onchainAddress` must be provided.
  - `externalCustomerId` string — Your system customer ID. Required if `onchainAddress` is not provided.
  - `onchainAddress` string — Smart account address. Required if `externalCustomerId` is not provided. Optional for ledger-only use.
  - `email` string, email — Optional end-customer email. When set, invoice PDFs are emailed here automatically on issue, past-due, and payment.
  - `isInternal` boolean — Internal customer (visibility only, no billing)
  - `metadata` object — Optional metadata

## Response `201`

Customer created successfully

- object — Customer created successfully
  - `id` string, required — Internal customer ID
  - `businessId` string, required — Business ID this customer belongs to
  - `name` string, nullable — Customer display name
  - `externalCustomerId` string, nullable — Your system customer ID (null if created with onchainAddress only)
  - `stripeCustomerId` string, nullable — Stripe customer ID linked via Connect or migration
  - `onchainAddress` string, nullable — Smart account address (null for internal customers)
  - `email` string, email, nullable — End-customer email used for invoice receipt delivery (null if not set)
  - `isInternal` boolean, required — Internal customer (visibility only, no billing)
  - `status` 'ACTIVE' | 'LOW_BALANCE' | 'PAUSED', required — Customer status
  - `metadata` object, nullable — Arbitrary metadata attached to the customer
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `provisioningStatus` 'provisioned' | 'pending' | 'skipped', required — Provisioning outcome for the customer smart account
  - `fundingRequired` boolean — True when the smart account exists but still needs funding before billing can proceed
  - `_warnings` string[] — Non-fatal warnings generated while creating the customer

## Other responses

- `401` — Unauthorized - invalid or missing API key
- `403` — Forbidden - customer blocked
- `409` — Customer already exists
- `422` — Validation error
- `429` — Rate limit exceeded
- `503` — Service temporarily unavailable: retry with backoff

---

[API](https://skmtc.net/usedrip/apis/drip-api.md) · [All operations](https://skmtc.net/usedrip/apis/drip-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usedrip/drip-api/revisions/2cb1567969ca/schema)