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

# Create Customer

`POST /customers`

## Request

- Base URL: `https://api.monei.com/v1`
- URL: `https://api.monei.com/v1/customers`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/monei/apis/monei-api-v1/docs/customers/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a customer.

Every field is optional — a customer with no details at all is valid, and useful if you only want somewhere to attach saved payment methods.

Pass the returned `id` as `customerId` when you [create a payment](https://docs.monei.com/apis/rest/payments-create/) or a [subscription](https://docs.monei.com/apis/rest/subscriptions-create/) to link it to this buyer.

**What linking does**:

- A payment saved with `generatePaymentToken` stores its payment method under this customer
- The customer's details are copied onto the payment at the time it is made. Editing the customer later never rewrites a payment that already happened
- A subscription gains renewal failover across the customer's other saved payment methods

**Best practices**:

- Create the customer once, when the buyer first registers with you, and reuse the `id`
- Use `metadata` to store your own user identifier, so you can match your records to MONEI's

## Request body

- CreateCustomerRequest
  - `email` string: The customer's email address.
  - `name` string: The customer's full name or business name.
  - `phone` string: The customer's phone number in E.164 format.
  - `billingDetails` PaymentBillingDetails: Billing information associated with the payment method at the time of the transaction.
    - `name` string: The customer's billing full name.
    - `email` string: The customer's billing email address.
    - `phone` string: The customer's billing phone number in E.164 format.
    - `company` string: Billing company name.
    - `taxId` string: Company tax ID.
    - `address` Address
      - `country` string: Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
      - `city` string: City, district, suburb, town, or village.
      - `line1` string: Address line 1 (e.g., street, PO Box, or company name).
      - `line2` string: Address line 2 (e.g., apartment, suite, unit, or building).
      - `zip` string: ZIP or postal code.
      - `state` string: State, county, province, or region.
  - `shippingDetails` PaymentShippingDetails: Shipping information associated with the payment.
    - `name` string: The shipping customer's full name.
    - `email` string: The shipping customer's email address.
    - `phone` string: The shipping customer's phone number in E.164 format.
    - `company` string: Name of the company where the shipment is going.
    - `taxId` string: Company tax ID.
    - `address` Address
      - `country` string: Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
      - `city` string: City, district, suburb, town, or village.
      - `line1` string: Address line 1 (e.g., street, PO Box, or company name).
      - `line2` string: Address line 2 (e.g., apartment, suite, unit, or building).
      - `zip` string: ZIP or postal code.
      - `state` string: State, county, province, or region.
  - `metadata` Metadata: A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format.

## Response `200`

A customer object

- Customer
  - `id` string, uuid, required: Unique identifier for the customer.
  - `email` string: The customer's email address.
  - `name` string: The customer's full name or business name.
  - `phone` string: The customer's phone number in E.164 format.
  - `billingDetails` PaymentBillingDetails: Billing information associated with the payment method at the time of the transaction.
    - `name` string: The customer's billing full name.
    - `email` string: The customer's billing email address.
    - `phone` string: The customer's billing phone number in E.164 format.
    - `company` string: Billing company name.
    - `taxId` string: Company tax ID.
    - `address` Address
      - `country` string: Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
      - `city` string: City, district, suburb, town, or village.
      - `line1` string: Address line 1 (e.g., street, PO Box, or company name).
      - `line2` string: Address line 2 (e.g., apartment, suite, unit, or building).
      - `zip` string: ZIP or postal code.
      - `state` string: State, county, province, or region.
  - `shippingDetails` PaymentShippingDetails: Shipping information associated with the payment.
    - `name` string: The shipping customer's full name.
    - `email` string: The shipping customer's email address.
    - `phone` string: The shipping customer's phone number in E.164 format.
    - `company` string: Name of the company where the shipment is going.
    - `taxId` string: Company tax ID.
    - `address` Address
      - `country` string: Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
      - `city` string: City, district, suburb, town, or village.
      - `line1` string: Address line 1 (e.g., street, PO Box, or company name).
      - `line2` string: Address line 2 (e.g., apartment, suite, unit, or building).
      - `zip` string: ZIP or postal code.
      - `state` string: State, county, province, or region.
  - `metadata` Metadata: A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format.
  - `defaultTokenId` string: The payment method charged when a payment sets `useDefaultPaymentMethod`. MONEI fills this only while it is empty: the first reusable payment method the customer saves becomes the default, and a value you set here is kept. Deleting that payment method clears the field, so the next reusable one the customer saves becomes the new default. It must be the ID of a payment method this customer already owns, and one that can be reused for future payments.
  - `createdAt` string, date-time: Time at which the resource was created.
  - `updatedAt` string, date-time: Time at which the resource was last updated.

## Other responses

- `400`: The request is incorrect or could not be processed
- `401`: Unauthorized error. Please check your auth credentials
- `404`: The specified resource was not found
- `422`: The request was well-formed but could not be processed due to semantic errors
- `500`: Unexpected server error
- `503`: The service is temporarily unavailable

## Changes

- **2026-10-02** `2d67a2ee1e00`: 1 info
  - endpoint added

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

---

[API](https://skmtc.dev/monei/apis/monei-api-v1.md) - [All operations](https://skmtc.dev/monei/apis/monei-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/monei/apis/monei-api-v1/revisions/50bc7df2aa43?raw)