Customers API — Create and Update Customer Records

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.

POST /customers

Request body

string

required

Customer email address. Must be a valid email format. Used as the unique identifier for upsert behaviour.

name

string

required

Customer full name.

phone

string

required

Customer phone number. Maximum 11 characters. Use only digits (e.g., 11999998888).

identification

string

Brazilian CPF (11 digits) or CNPJ (14 digits). Maximum 14 characters.

foreign

boolean

Set to true for customers outside Brazil. When true, identification validation is relaxed.

neighborhood

string

Neighborhood or district of the customer’s address.

number

string

Street number of the customer’s address.

street

string

Street name of the customer’s address.

zipcode

string

Postal/ZIP code of the customer’s address.

state

string

State abbreviation (e.g., SP, RJ).

city

string

City name.

complement

string

Address complement (apartment number, suite, floor, etc.).

Response — `CustomerResponse`

integer

Unique numeric ID of the created or updated customer record.

string

Customer email address.

identification

string

CPF or CNPJ stored on the customer record.

Example request and response

{
  "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"
  }
}

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
  }'

{
  "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
}

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.

Checkout

Payments

Management

Webhooks

Customers API — Create and Update Customer Records

Create or update a customer

Request body

Response — `CustomerResponse`

Example request and response

​Create or update a customer

​Request body

​Response — CustomerResponse

​Example request and response

Create or update a customer

Request body

Response — `CustomerResponse`

Example request and response