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

date

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

date

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

string

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

integer

Page number for pagination. Defaults to 1.

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.

array of uuid strings

Filter by one or more cart page UUIDs.

array of integers

Filter by one or more company IDs.

array of strings

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

array of strings

Filter by metadata key-value pairs attached to orders.

Response — `OrdersIndex`

The response contains pagination metadata in meta and a complete array of OrderData objects in data. See the full JSON response below.

Complete JSON response

This example includes every response property defined for this operation in the OpenAPI schema.

{
  "meta": {
    "current_page": 1,
    "total_pages": 4,
    "total_count": 87,
    "per_page": 25
  },
  "data": [
    {
      "id": 123,
      "uid": "example-id",
      "link": "https://example.com/resource",
      "due_date": "2026-08-25",
      "coupon_code": "string",
      "deal_id": "example-id",
      "observation": "string",
      "seller_id": 123,
      "status": "pending",
      "meta": {},
      "utms": {},
      "discount": 100.5,
      "total": 100.5,
      "created_at": "2026-08-25T12:00:00Z",
      "date": "2026-08-25",
      "scheduled_at": "2026-08-25T12:00:00Z",
      "charge_page": {
        "id": 123,
        "name": "Example"
      },
      "checkout_page": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Example"
      },
      "customer": {
        "email": "customer@example.com",
        "name": "Example",
        "identification": "12345678909",
        "phone": "+5511999990000",
        "utms": {},
        "meta": {},
        "address": {
          "street": "string",
          "neighborhood": "string",
          "number": "string",
          "complement": "string",
          "zipcode": "01310100",
          "city": "string",
          "state": "SP"
        }
      },
      "seller": {
        "name": "Example"
      },
      "items": [
        {
          "product_id": 123,
          "product_name": "Example",
          "unit_name": "Example",
          "interval": "string",
          "cycle": 1,
          "quantity": 1,
          "subscription": true,
          "total": 100.5,
          "value": 100.5
        }
      ],
      "payments": [
        {
          "gateway_id": "example-id",
          "installments": 1,
          "status": "paid",
          "type": "string",
          "amount": 100.5,
          "company": "string",
          "created_at": "2026-08-25T12:00:00Z",
          "installment_value": 100.5,
          "interest": 100.5,
          "paid_at": "2026-08-25T12:00:00Z",
          "cancelled_at": "2026-08-25T12:00:00Z",
          "fees": {
            "totals": {
              "gross": 10000,
              "fee": 10000,
              "net": 10000
            },
            "entries": [
              {
                "reference_id": "example-id",
                "kind": "credit",
                "status": "paid",
                "installment": 123,
                "recipient_id": "example-id",
                "split_id": "example-id",
                "gross_amount": 10000,
                "fee_amount": 10000,
                "net_amount": 10000,
                "fee_details": [
                  {
                    "type": "processing",
                    "amount": 10000,
                    "raw_type": "string"
                  }
                ],
                "settlement_date": "2026-08-25",
                "currency": "BRL",
                "source": "string",
                "raw": {
                  "example": "value"
                }
              }
            ]
          },
          "fees_status": "fees_pending",
          "gateway_fee": 100.5,
          "gateway_net": 100.5,
          "fees_synced_at": "2026-08-25T12:00:00Z"
        }
      ],
      "invoices": [
        {
          "number": "string",
          "series": "string",
          "status": "paid",
          "type": "string",
          "value": 100.5
        }
      ],
      "freight": {
        "brand": "string",
        "charge": 100.5,
        "type": "string",
        "quantity": 1,
        "total": 100.5,
        "carrier": {
          "email": "customer@example.com",
          "name": "Example",
          "identification": "12345678909",
          "phone": "+5511999990000"
        }
      }
    }
  ]
}

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.

string

Order UID. Present when the order has an associated charge page.

string (uri)

Charge link URL when the order was invoiced.

date

The date by which the order must be paid.

string | null

Coupon code applied to this order, or null when no coupon was used.

string | null

CRM deal identifier associated with this order, or null.

string | null

Internal observation or note attached to the order, or null.

integer | null

ID of the assigned seller, or null.

string

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

object

Arbitrary key-value metadata attached to the order.

object

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

number

Total discount amount applied to the order.

number

Final total amount of the order after discounts.

datetime

ISO 8601 timestamp of when the order was created.

date

The order date.

datetime | null

ISO 8601 timestamp of when the order is scheduled, or null.

object | null

The charge page associated with this order.

Show charge_page fields

integer

Charge page ID.

string

Charge page display name.

object | null

The checkout page associated with this order, or null.

Show checkout_page fields

string (uuid)

Checkout page UUID.

string

Checkout page display name.

object

The customer who placed the order.

Show customer fields

string

Customer email address.

string

Customer full name.

string

CPF or CNPJ of the customer.

string

Customer phone number.

object

UTM parameters captured for the customer.

object

Arbitrary metadata attached to the customer.

object

Customer address details.

Show address fields

string

Street name.

string

Neighborhood or district.

string

Street number.

string

Address complement.

string

Postal code.

string

City.

string

State acronym, such as SP.

object

The seller assigned to this order.

Show seller fields

string | null

Seller full name, or null.

array

Line items included in this order.

Show items fields

integer

Product ID.

string

Product display name.

string

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

string

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

integer

Billing cycle number for subscriptions.

number

Number of units ordered.

boolean

Whether this item is a subscription.

number

Total price for this line item.

number

Unit price of the item.

array

Payment records associated with this order.

Show payments fields

string

Transaction ID from the payment gateway.

integer

Number of installments.

string

Payment status.

string

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

number

Total payment amount.

string

Company associated with the payment.

datetime

ISO 8601 timestamp when the payment was created.

number

Value of each installment.

number

Interest amount applied.

datetime | null

ISO 8601 timestamp when the payment was confirmed, or null.

datetime | null

ISO 8601 timestamp when the payment was cancelled, or null.

object | null

Gateway fee breakdown. Amounts inside this object are integer cents. It is null until fee synchronization succeeds or when the gateway does not support fee data.

Show fees fields

object

Aggregated fee totals.

Show totals fields

integer

Gross amount in cents.

integer

Total fee in cents.

integer

Net amount in cents.

array

Settlement entries returned by the gateway.

Show entry fields

string

Gateway settlement reference.

string

Entry kind.

string

Settlement status.

integer

Installment number.

string

Gateway recipient identifier.

string

Split identifier.

integer

Gross amount in cents.

integer

Fee amount in cents.

integer

Net amount in cents.

array

Individual fee components.

Show fee detail fields

string

Normalized fee type.

integer

Fee amount in cents.

string

Gateway-specific fee type.

date

Settlement date.

string

ISO 4217 currency code.

string

Fee data source.

object

Raw gateway payload.

string

Fee synchronization state: fees_pending, fees_settled, fees_unavailable, or fees_failed.

number

Total gateway fee in the order currency. This mirrors fees.totals.fee after unit conversion.

number

Net amount after gateway fees in the order currency. This mirrors fees.totals.net after unit conversion.

datetime

Timestamp of the latest successful fee synchronization. Omitted until the first successful sync.

array

Fiscal invoices issued for this order.

Show invoices fields

string

Invoice number.

string

Invoice series.

string

Invoice status.

string

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

number

Invoice total value.

object | null

Shipping details for the order, or null.

Show freight fields

string

Carrier brand name.

number

Shipping charge amount.

string

Shipping service type.

integer

Number of packages.

number

Total shipping cost.

object | null

Carrier details, or null.

Show carrier fields

string

Carrier email.

string

Carrier name.

string

Carrier tax identifier.

string

Carrier phone number.

Example request

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

Complete JSON response

This example includes every response property defined for this operation in the OpenAPI schema.

{
  "id": 123,
  "uid": "example-id",
  "link": "https://example.com/resource",
  "due_date": "2026-08-25",
  "coupon_code": "string",
  "deal_id": "example-id",
  "observation": "string",
  "seller_id": 123,
  "status": "pending",
  "meta": {},
  "utms": {},
  "discount": 100.5,
  "total": 100.5,
  "created_at": "2026-08-25T12:00:00Z",
  "date": "2026-08-25",
  "scheduled_at": "2026-08-25T12:00:00Z",
  "charge_page": {
    "id": 123,
    "name": "Example"
  },
  "checkout_page": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Example"
  },
  "customer": {
    "email": "customer@example.com",
    "name": "Example",
    "identification": "12345678909",
    "phone": "+5511999990000",
    "utms": {},
    "meta": {},
    "address": {
      "street": "string",
      "neighborhood": "string",
      "number": "string",
      "complement": "string",
      "zipcode": "01310100",
      "city": "string",
      "state": "SP"
    }
  },
  "seller": {
    "name": "Example"
  },
  "items": [
    {
      "product_id": 123,
      "product_name": "Example",
      "unit_name": "Example",
      "interval": "string",
      "cycle": 1,
      "quantity": 1,
      "subscription": true,
      "total": 100.5,
      "value": 100.5
    }
  ],
  "payments": [
    {
      "gateway_id": "example-id",
      "installments": 1,
      "status": "paid",
      "type": "string",
      "amount": 100.5,
      "company": "string",
      "created_at": "2026-08-25T12:00:00Z",
      "installment_value": 100.5,
      "interest": 100.5,
      "paid_at": "2026-08-25T12:00:00Z",
      "cancelled_at": "2026-08-25T12:00:00Z",
      "fees": {
        "totals": {
          "gross": 10000,
          "fee": 10000,
          "net": 10000
        },
        "entries": [
          {
            "reference_id": "example-id",
            "kind": "credit",
            "status": "paid",
            "installment": 123,
            "recipient_id": "example-id",
            "split_id": "example-id",
            "gross_amount": 10000,
            "fee_amount": 10000,
            "net_amount": 10000,
            "fee_details": [
              {
                "type": "processing",
                "amount": 10000,
                "raw_type": "string"
              }
            ],
            "settlement_date": "2026-08-25",
            "currency": "BRL",
            "source": "string",
            "raw": {
              "example": "value"
            }
          }
        ]
      },
      "fees_status": "fees_pending",
      "gateway_fee": 100.5,
      "gateway_net": 100.5,
      "fees_synced_at": "2026-08-25T12:00:00Z"
    }
  ],
  "invoices": [
    {
      "number": "string",
      "series": "string",
      "status": "paid",
      "type": "string",
      "value": 100.5
    }
  ],
  "freight": {
    "brand": "string",
    "charge": 100.5,
    "type": "string",
    "quantity": 1,
    "total": 100.5,
    "carrier": {
      "email": "customer@example.com",
      "name": "Example",
      "identification": "12345678909",
      "phone": "+5511999990000"
    }
  }
}

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.

string

Coupon code to apply to the order.

integer

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

datetime

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

string

Internal observation or note to attach to the order.

boolean

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

boolean

When true, applies retention pricing logic during order creation.

object

Arbitrary key-value metadata to store on the order.

object

required

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

Show customer fields

string

required

Customer email address.

string

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

string

Customer full name.

string

Neighborhood / district.

string

Street number.

string

Phone number (up to 11 digits).

string

Street address.

string

Postal code.

string

State abbreviation (e.g., SP).

string

City name.

string

Address complement (apartment, suite, etc.).

boolean

Whether to apply retention pricing for this customer.

object

Arbitrary metadata to store on the customer record.

object

CRM integration settings for this order.

Show crm_info fields

boolean

Whether to create a CRM deal for this order.

string

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

uri

Source URL to attach to the CRM deal.

string

Tags to apply to the CRM deal.

array

Line items for the order.

Show items fields

integer

required

ID of the product to add.

integer

Quantity to order. Defaults to 1.

array

Payment records to attach to the order at creation time.

Show payments fields

string

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

string

Transaction ID from the gateway.

integer

ID of the payment plan to use.

number

Payment amount.

string

Initial payment status.

object

Shipping configuration for the order.

Show freight fields

string

Carrier brand name.

integer

Carrier ID.

string

Shipping service type.

number

Shipping charge amount.

integer

Number of packages.

number

Total shipping cost.

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

string

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

string

Transaction or charge ID from the external gateway.

integer

ID of the payment plan associated with this payment.

integer

Number of installments for the payment.

number

Total payment amount in the account currency.

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`

Complete JSON response

Retrieve an order

Path parameters

Response — `OrderData`

Example request

Complete JSON response

Create an order

Request body — `OrderCreateRequest`

Response

Example request

Register an external payment

Path parameters

Request body

Response

List orders

Query parameters

Response — OrdersIndex

Complete JSON response

Retrieve an order

Path parameters

Response — OrderData

Example request

Complete JSON response

Create an order

Request body — OrderCreateRequest

Response

Example request

Register an external payment

Path parameters

Request body

Response

Response — `OrdersIndex`

Response — `OrderData`

Request body — `OrderCreateRequest`