> ## Documentation Index > Fetch the complete documentation index at: https://developers.nova.money/llms.txt > Use this file to discover all available pages before exploring further. # Orders API — List, Retrieve, Create, and Manage Orders > REST API for Nova.Pay orders. List orders with filters, retrieve order details, create orders programmatically, and register external payments. 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. ```text theme={null} GET /orders ``` ### Query parameters Start of the date range filter (inclusive). Use `YYYY-MM-DD` format. End of the date range filter (inclusive). Use `YYYY-MM-DD` format. The date field to apply the `initial_date`/`final_date` range against (e.g., `created_at`, `paid_at`). Page number for pagination. Defaults to `1`. Number of orders to return per page. Maximum value is `100`. Free-text search string. Matches against customer name, email, order ID, and other indexed fields. Filter by one or more cart page UUIDs. Filter by one or more company IDs. Filter by order status. Accepted values: `pending` `waiting_payment` `partially_paid` `paid` `cancelled` `partially_refunded` `refunded` `billed` Filter by metadata key-value pairs attached to orders. ### Response — `OrdersIndex` ```json theme={null} { "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. ```text theme={null} GET /orders/{id} ``` ### Path parameters The numeric ID of the order to retrieve. ### Response — `OrderData` Unique numeric identifier for the order. Unique UUID string identifier for the order. Public checkout link for the order. The date by which the order must be paid. Coupon code applied to this order, if any. CRM deal ID associated with this order, if any. Internal observation or note attached to the order. ID of the seller assigned to this order. Current order status. One of: `pending`, `waiting_payment`, `partially_paid`, `paid`, `cancelled`, `partially_refunded`, `refunded`, `billed`. Arbitrary key-value metadata attached to the order. UTM tracking parameters captured at order creation (e.g., `utm_source`, `utm_medium`, `utm_campaign`). Total discount amount applied to the order. Final total amount of the order after discounts. ISO 8601 timestamp of when the order was created. The order date. ISO 8601 timestamp of when the order is scheduled for, if applicable. The charge page associated with this order. Charge page ID. Charge page display name. The checkout page associated with this order. Checkout page ID. Checkout page display name. The customer who placed the order. Customer email address. Customer full name. CPF or CNPJ of the customer. Customer phone number. UTM parameters captured for the customer. Arbitrary metadata attached to the customer. Customer address details. The seller assigned to this order. Seller full name. Line items included in this order. Product ID. Product display name. Unit label (e.g., "license", "seat"). Billing interval for subscriptions (e.g., `month`, `year`). Billing cycle number for subscriptions. Number of units ordered. Whether this item is a subscription. Total price for this line item. Unit price of the item. Payment records associated with this order. Transaction ID from the payment gateway. Number of installments. Payment status. Payment method type (e.g., `credit_card`, `pix`, `boleto`). Total payment amount. Company associated with the payment. ISO 8601 timestamp when the payment was created. Value of each installment. Interest amount applied. ISO 8601 timestamp when the payment was confirmed. ISO 8601 timestamp when the payment was cancelled, if applicable. Fiscal invoices issued for this order. Invoice number. Invoice series. Invoice status. Invoice type (e.g., NF-e, NFS-e). Invoice total value. Shipping details for the order. Carrier brand name. Shipping charge amount. Shipping service type. Number of packages. Total shipping cost. Carrier identifier. ### Example request ```bash cURL theme={null} 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. ```text theme={null} POST /orders ``` ### Request body — `OrderCreateRequest` The order date in `YYYY-MM-DD` format. Defaults to today if omitted. Coupon code to apply to the order. ID of the primary product for this order. Used for routing and coupon validation. ISO 8601 datetime for scheduling the order (e.g., for appointment-based products). Internal observation or note to attach to the order. When `true`, suppresses automatic content-release actions triggered on order creation. When `true`, applies retention pricing logic during order creation. Arbitrary key-value metadata to store on the order. Customer to associate with this order. Creates or updates the customer record. Customer email address. CPF (11 digits) or CNPJ (14 digits). Customer full name. Neighborhood / district. Street number. Phone number (up to 11 digits). Street address. Postal code. State abbreviation (e.g., `SP`). City name. Address complement (apartment, suite, etc.). Whether to apply retention pricing for this customer. Arbitrary metadata to store on the customer record. CRM integration settings for this order. Whether to create a CRM deal for this order. Comma-separated list IDs to associate with the CRM deal. Source URL to attach to the CRM deal. Tags to apply to the CRM deal. Line items for the order. ID of the product to add. Quantity to order. Defaults to `1`. Payment records to attach to the order at creation time. Gateway name (e.g., `pagarme`, `stripe`). Transaction ID from the gateway. ID of the payment plan to use. Payment amount. Initial payment status. Shipping configuration for the order. Carrier brand name. Carrier ID. Shipping service type. Shipping charge amount. Number of packages. Total shipping cost. ### Response ```json theme={null} { "id": 12345 } ``` ### Example request ```json Request body theme={null} { "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" } ] } ``` ```bash cURL theme={null} 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. ```text theme={null} POST /orders/{id}/create_payment ``` ### Path parameters The numeric ID of the order to attach the payment to. ### Request body Gateway name (e.g., `pagarme`, `stripe`, `manual`). Transaction or charge ID from the external gateway. ID of the payment plan associated with this payment. Number of installments for the payment. Total payment amount in the account currency. When `true`, suppresses automatic content-release actions triggered by the payment status change. ### Response ```json theme={null} { "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. ## Related topics - [Products API — List, Create, and Retrieve Products](/api-reference/products.md) - [Nova.Pay API: Payments, Checkout & Order Management](/introduction.md) - [Customers API — Create and Update Customer Records](/api-reference/customers.md) - [Coupons API — Validate Discount Codes Before Checkout](/api-reference/coupons.md) - [Carts API — Create, Retrieve, and Pay Nova.Pay Carts](/api-reference/carts.md)