Skip to main content
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.

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.
string
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.
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

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.