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://yourcompany.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.

string

required

Customer full name.

string

required

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

string

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

boolean

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

string

Neighborhood or district of the customer’s address.

string

Street number of the customer’s address.

string

Street name of the customer’s address.

string

Postal/ZIP code of the customer’s address.

string

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

string

City name.

string

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

string

Comma-separated tags to attach to the customer record.

string

Comma-separated list IDs to associate with this customer in connected CRM or email marketing tools.

string

Carrier name or identifier, used for shipping preferences.

uri

Source URL where the customer originated (e.g., a landing page). Stored for attribution purposes.

integer

ID of the primary product to associate with this customer record.

string

ID of the checkout page to associate with this customer request.

string

Coupon code to apply when create_deal: true creates an order.

number

Minimum order value to apply when evaluating retention pricing for this customer.

string

State tax inscription number (Inscrição Estadual). Relevant for business customers.

Legal company name (Razão Social) for business customers.

string

Municipal tax inscription number (Inscrição Municipal). Relevant for service providers.

array of strings

Additional email addresses to associate with this customer. Each entry must be a valid email.

object

Arbitrary key-value metadata to store on the customer record. Values must be strings.

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.

datetime

ISO 8601 datetime for scheduling the order, when create_deal: true and the product requires scheduling.

string

Internal observation or note to attach to the order, when create_deal: true.

Response — `CustomerResponse`

integer

Unique numeric ID of the created or updated customer record.

string

Customer email address.

string

CPF or CNPJ stored on the customer record.

object

Arbitrary metadata stored on the customer record.

string

Customer full name.

string

Customer phone number.

boolean

Whether the customer is flagged as foreign.

object

Customer address details.

Show address fields

string

Street name.

string

Neighborhood or district.

string

Street number.

string

Address complement.

string

Postal/ZIP code.

string

City name.

string

State abbreviation.

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.

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://yourcompany.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