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

# Customers API — Create and Update Customer Records

> Use POST /customers to create or update a customer record in Nova.Pay. Optionally trigger an order for that customer in the same request.

The Customers API provides a single endpoint to create or update a customer record in Nova.Pay. If the customer already exists (matched by email), their record is updated with the provided data. When you pass `create_deal: true`, Nova.Pay additionally creates an order for the customer and returns the resulting `order_id`. All endpoints are relative to the base URL `https://pay.nova.money/api/v1`.

***

## Create or update a customer

Create a new customer or update an existing one. You can also trigger an order creation in the same request by setting `create_deal` to `true`.

```text theme={null}
POST /customers
```

### Request body

<ParamField body="email" type="string" required>
  Customer email address. Must be a valid email format. Used as the unique identifier for upsert behaviour.
</ParamField>

<ParamField body="name" type="string" required>
  Customer full name.
</ParamField>

<ParamField body="phone" type="string" required>
  Customer phone number. Maximum 11 characters. Use only digits (e.g., `11999998888`).
</ParamField>

<ParamField body="identification" type="string">
  Brazilian CPF (11 digits) or CNPJ (14 digits). Maximum 14 characters.
</ParamField>

<ParamField body="foreign" type="boolean">
  Set to `true` for customers outside Brazil. When `true`, `identification` validation is relaxed.
</ParamField>

<ParamField body="neighborhood" type="string">
  Neighborhood or district of the customer's address.
</ParamField>

<ParamField body="number" type="string">
  Street number of the customer's address.
</ParamField>

<ParamField body="street" type="string">
  Street name of the customer's address.
</ParamField>

<ParamField body="zipcode" type="string">
  Postal/ZIP code of the customer's address.
</ParamField>

<ParamField body="state" type="string">
  State abbreviation (e.g., `SP`, `RJ`).
</ParamField>

<ParamField body="city" type="string">
  City name.
</ParamField>

<ParamField body="complement" type="string">
  Address complement (apartment number, suite, floor, etc.).
</ParamField>

<ParamField body="tags" type="string">
  Comma-separated tags to attach to the customer record.
</ParamField>

<ParamField body="list_ids" type="string">
  Comma-separated list IDs to associate with this customer in connected CRM or email marketing tools.
</ParamField>

<ParamField body="carrier" type="string">
  Carrier name or identifier, used for shipping preferences.
</ParamField>

<ParamField body="url" type="uri">
  Source URL where the customer originated (e.g., a landing page). Stored for attribution purposes.
</ParamField>

<ParamField body="main_product_id" type="integer">
  ID of the primary product to associate with this customer record.
</ParamField>

<ParamField body="checkout_page_id" type="string">
  ID of the checkout page to associate with this customer request.
</ParamField>

<ParamField body="coupon" type="string">
  Coupon code to apply when `create_deal: true` creates an order.
</ParamField>

<ParamField body="minimum_retention_value" type="number">
  Minimum order value to apply when evaluating retention pricing for this customer.
</ParamField>

<ParamField body="state_inscription" type="string">
  State tax inscription number (Inscrição Estadual). Relevant for business customers.
</ParamField>

<ParamField body="social_reason" type="string">
  Legal company name (Razão Social) for business customers.
</ParamField>

<ParamField body="municipal_inscription" type="string">
  Municipal tax inscription number (Inscrição Municipal). Relevant for service providers.
</ParamField>

<ParamField body="auxiliary_emails" type="array of strings">
  Additional email addresses to associate with this customer. Each entry must be a valid email.
</ParamField>

<ParamField body="meta" type="object">
  Arbitrary key-value metadata to store on the customer record. Values must be strings.
</ParamField>

<ParamField body="create_deal" type="boolean">
  When `true`, Nova.Pay creates an order for this customer after upserting the customer record. The new order's ID is returned in `order_id`.
</ParamField>

<ParamField body="scheduled_at" type="datetime">
  ISO 8601 datetime for scheduling the order, when `create_deal: true` and the product requires scheduling.
</ParamField>

<ParamField body="observation" type="string">
  Internal observation or note to attach to the order, when `create_deal: true`.
</ParamField>

### Response — `CustomerResponse`

<ResponseField name="id" type="integer">
  Unique numeric ID of the created or updated customer record.
</ResponseField>

<ResponseField name="email" type="string">
  Customer email address.
</ResponseField>

<ResponseField name="identification" type="string">
  CPF or CNPJ stored on the customer record.
</ResponseField>

<ResponseField name="meta" type="object">
  Arbitrary metadata stored on the customer record.
</ResponseField>

<ResponseField name="name" type="string">
  Customer full name.
</ResponseField>

<ResponseField name="phone" type="string">
  Customer phone number.
</ResponseField>

<ResponseField name="foreign" type="boolean">
  Whether the customer is flagged as foreign.
</ResponseField>

<ResponseField name="address" type="object">
  Customer address details.

  <Expandable title="address fields">
    <ResponseField name="street" type="string">Street name.</ResponseField>
    <ResponseField name="neighborhood" type="string">Neighborhood or district.</ResponseField>
    <ResponseField name="number" type="string">Street number.</ResponseField>
    <ResponseField name="complement" type="string">Address complement.</ResponseField>
    <ResponseField name="zipcode" type="string">Postal/ZIP code.</ResponseField>
    <ResponseField name="city" type="string">City name.</ResponseField>
    <ResponseField name="state" type="string">State abbreviation.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="order_id" type="integer">
  The ID of the order created for this customer. Only present when `create_deal: true` was sent and an order was successfully created. Returns `null` otherwise.
</ResponseField>

### Example request and response

<CodeGroup>
  ```json Request body theme={null}
  {
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "phone": "11999998888",
    "identification": "12345678901",
    "street": "Rua das Flores",
    "number": "42",
    "neighborhood": "Jardins",
    "city": "São Paulo",
    "state": "SP",
    "zipcode": "01310100",
    "main_product_id": 101,
    "coupon": "WELCOME10",
    "create_deal": true,
    "meta": {
      "source": "webinar-sept-2024"
    }
  }
  ```

  ```bash cURL theme={null}
  curl --request POST \
    --url "https://pay.nova.money/api/v1/customers" \
    --header "Content-Type: application/json" \
    --data '{
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "phone": "11999998888",
      "main_product_id": 101,
      "create_deal": true
    }'
  ```
</CodeGroup>

<CodeGroup>
  ```json Response theme={null}
  {
    "id": 9876,
    "email": "jane.doe@example.com",
    "name": "Jane Doe",
    "phone": "11999998888",
    "identification": "12345678901",
    "foreign": false,
    "meta": {
      "source": "webinar-sept-2024"
    },
    "address": {
      "street": "Rua das Flores",
      "number": "42",
      "neighborhood": "Jardins",
      "complement": null,
      "zipcode": "01310100",
      "city": "São Paulo",
      "state": "SP"
    },
    "order_id": 12345
  }
  ```
</CodeGroup>

<Warning>
  When `create_deal: true` is set, the order creation may fail independently of the customer upsert. Always check the response for `order_id` to confirm the order was created. If `order_id` is `null`, you can create the order separately using `POST /orders`.
</Warning>


## Related topics

- [Nova.Pay Checkout Flow: Pages, Carts, and Charge Links](/concepts/checkout-flow.md)
- [Nova.Pay API: Payments, Checkout & Order Management](/introduction.md)
- [Payments API — Create Payments and Issue Refunds](/api-reference/payments.md)
- [Create and Process Your First Payment with Nova.Pay](/guides/create-payment.md)
- [Carts API — Create, Retrieve, and Pay Nova.Pay Carts](/api-reference/carts.md)