Orders API — List, Retrieve, Create, and Manage Orders

The Orders API lets you list and filter orders in your Nova.Pay account, retrieve the full details of a single order, create new orders programmatically, and register external payments against existing orders. All endpoints are relative to the base URL https://pay.nova.money/api/v1.

List orders

This endpoint requires an API key passed in the request headers.

Retrieve a paginated list of orders. You can narrow results with date ranges, status filters, a free-text search, and more.

GET /orders

Query parameters

initial_date

date

Start of the date range filter (inclusive). Use YYYY-MM-DD format.

final_date

date

End of the date range filter (inclusive). Use YYYY-MM-DD format.

period_date_filter

string

The date field to apply the initial_date/final_date range against (e.g., created_at, paid_at).

page

integer

Page number for pagination. Defaults to 1.

limit

integer

Number of orders to return per page. Maximum value is 100.

string

Free-text search string. Matches against customer name, email, order ID, and other indexed fields.

cart_page_uuids

array of uuid strings

Filter by one or more cart page UUIDs.

company_ids

array of integers

Filter by one or more company IDs.

status

array of strings

Filter by order status. Accepted values:pending waiting_payment partially_paid paid cancelled partially_refunded refunded billed

meta

array of strings

Filter by metadata key-value pairs attached to orders.

Response — `OrdersIndex`

{
  "meta": {
    "current_page": 1,
    "total_pages": 4,
    "total_count": 87,
    "per_page": 25
  },
  "data": [ /* array of OrderData */ ]
}

Retrieve an order

This endpoint requires an API key passed in the request headers.

Fetch the complete details of a single order by its numeric ID.

GET /orders/{id}

Path parameters

integer

required

The numeric ID of the order to retrieve.

Response — `OrderData`

integer

Unique numeric identifier for the order.

uid

string

Unique UUID string identifier for the order.

link

string

Public checkout link for the order.

due_date

date

The date by which the order must be paid.

coupon_code

string

Coupon code applied to this order, if any.

deal_id

integer

CRM deal ID associated with this order, if any.

observation

string

Internal observation or note attached to the order.

seller_id

integer

ID of the seller assigned to this order.

status

string

Current order status. One of: pending, waiting_payment, partially_paid, paid, cancelled, partially_refunded, refunded, billed.

meta

object

Arbitrary key-value metadata attached to the order.

utms

object

UTM tracking parameters captured at order creation (e.g., utm_source, utm_medium, utm_campaign).

discount

number

Total discount amount applied to the order.

total

number

Final total amount of the order after discounts.

created_at

datetime

ISO 8601 timestamp of when the order was created.

date

The order date.

scheduled_at

datetime

ISO 8601 timestamp of when the order is scheduled for, if applicable.

charge_page

object

The charge page associated with this order.

Show charge_page fields

integer

Charge page ID.

name

string

Charge page display name.

checkout_page

object

The checkout page associated with this order.

Show checkout_page fields

integer

Checkout page ID.

name

string

Checkout page display name.

customer

object

The customer who placed the order.

Show customer fields

string

Customer email address.

name

string

Customer full name.

identification

string

CPF or CNPJ of the customer.

phone

string

Customer phone number.

utms

object

UTM parameters captured for the customer.

meta

object

Arbitrary metadata attached to the customer.

address

object

Customer address details.

seller

object

The seller assigned to this order.

Show seller fields

name

string

Seller full name.

items

array

Line items included in this order.

Show items fields

product_id

integer

Product ID.

product_name

string

Product display name.

unit_name

string

Unit label (e.g., “license”, “seat”).

interval

string

Billing interval for subscriptions (e.g., month, year).

cycle

integer

Billing cycle number for subscriptions.

quantity

integer

Number of units ordered.

subscription

boolean

Whether this item is a subscription.

total

number

Total price for this line item.

value

number

Unit price of the item.

payments

array

Payment records associated with this order.

Show payments fields

gateway_id

string

Transaction ID from the payment gateway.

installments

integer

Number of installments.

status

string

Payment status.

type

string

Payment method type (e.g., credit_card, pix, boleto).

amount

number

Total payment amount.

company

string

Company associated with the payment.

created_at

datetime

ISO 8601 timestamp when the payment was created.

installment_value

number

Value of each installment.

interest

number

Interest amount applied.

paid_at

datetime

ISO 8601 timestamp when the payment was confirmed.

cancelled_at

datetime

ISO 8601 timestamp when the payment was cancelled, if applicable.

invoices

array

Fiscal invoices issued for this order.

Show invoices fields

number

string

Invoice number.

series

string

Invoice series.

status

string

Invoice status.

type

string

Invoice type (e.g., NF-e, NFS-e).

value

number

Invoice total value.

freight

object

Shipping details for the order.

Show freight fields

brand

string

Carrier brand name.

charge

number

Shipping charge amount.

type

string

Shipping service type.

quantity

integer

Number of packages.

total

number

Total shipping cost.

carrier

string

Carrier identifier.

Example request

curl --request GET \
  --url "https://pay.nova.money/api/v1/orders/12345" \
  --header "Authorization: Bearer YOUR_API_KEY"

Create an order

Create a new order programmatically. You can supply customer info, line items, payment details, and shipping in a single request.

POST /orders

Request body — `OrderCreateRequest`

date

The order date in YYYY-MM-DD format. Defaults to today if omitted.

coupon

string

Coupon code to apply to the order.

main_product_id

integer

ID of the primary product for this order. Used for routing and coupon validation.

scheduled_at

datetime

ISO 8601 datetime for scheduling the order (e.g., for appointment-based products).

observation

string

Internal observation or note to attach to the order.

skip_content_release

boolean

When true, suppresses automatic content-release actions triggered on order creation.

calculate_retention

boolean

When true, applies retention pricing logic during order creation.

meta

object

Arbitrary key-value metadata to store on the order.

customer

object

required

Customer to associate with this order. Creates or updates the customer record.

Show customer fields

string

required

Customer email address.

identification

string

CPF (11 digits) or CNPJ (14 digits).

name

string

Customer full name.

neighborhood

string

Neighborhood / district.

number

string

Street number.

phone

string

Phone number (up to 11 digits).

street

string

Street address.

zipcode

string

Postal code.

state

string

State abbreviation (e.g., SP).

city

string

City name.

complement

string

Address complement (apartment, suite, etc.).

retention

boolean

Whether to apply retention pricing for this customer.

meta

object

Arbitrary metadata to store on the customer record.

crm_info

object

CRM integration settings for this order.

Show crm_info fields

create_deal

boolean

Whether to create a CRM deal for this order.

list_ids

string

Comma-separated list IDs to associate with the CRM deal.

url

uri

Source URL to attach to the CRM deal.

Response

{
  "id": 12345
}

Example request

{
  "date": "2024-09-15",
  "coupon": "SUMMER20",
  "main_product_id": 101,
  "customer": {
    "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"
  },
  "items": [
    { "product_id": 101, "quantity": 1 }
  ],
  "payments": [
    {
      "gateway": "pagarme",
      "gateway_id": "ch_abc123",
      "amount": 199.90,
      "status": "paid"
    }
  ]
}

curl --request POST \
  --url "https://pay.nova.money/api/v1/orders" \
  --header "Content-Type: application/json" \
  --data '{
    "date": "2024-09-15",
    "main_product_id": 101,
    "customer": {
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "phone": "11999998888"
    },
    "items": [{ "product_id": 101, "quantity": 1 }]
  }'

Register an external payment

This endpoint requires an API key passed in the request headers.

Register an external payment transaction against an existing order. Use this when a payment is processed outside the standard Nova.Pay checkout flow and you need to record it manually.

POST /orders/{id}/create_payment

Path parameters

integer

required

The numeric ID of the order to attach the payment to.

Request body

gateway

string

Gateway name (e.g., pagarme, stripe, manual).

gateway_id

string

Transaction or charge ID from the external gateway.

payment_plan_id

integer

ID of the payment plan associated with this payment.

installments

integer

Number of installments for the payment.

amount

number

Total payment amount in the account currency.

skip_content_release

boolean

When true, suppresses automatic content-release actions triggered by the payment status change.

Response

{
  "id": 67890
}

After calling this endpoint, you can verify the payment was recorded correctly by fetching the order with GET /orders/{id} and inspecting the payments array.

Checkout

Payments

Management

Webhooks

Orders API — List, Retrieve, Create, and Manage Orders

List orders

Query parameters

Response — `OrdersIndex`

Retrieve an order

Path parameters

Response — `OrderData`

Example request

Create an order

Request body — `OrderCreateRequest`

Response

Example request

Register an external payment

Path parameters

Request body

Response

​List orders

​Query parameters

​Response — OrdersIndex

​Retrieve an order

​Path parameters

​Response — OrderData

​Example request

​Create an order

​Request body — OrderCreateRequest

​Response

​Example request

​Register an external payment

​Path parameters

​Request body

​Response

List orders

Query parameters

Response — `OrdersIndex`

Retrieve an order

Path parameters

Response — `OrderData`

Example request

Create an order

Request body — `OrderCreateRequest`

Response

Example request

Register an external payment

Path parameters

Request body

Response