Orders Guide

Document type (business): Order (NE)

Illustrative IDs

The values in the JSON examples (e.g. "documentTypeId": 3) are illustrations; the same number can represent a different document type in another client's database. Resolve the correct id with GET /gateway/document-type and match description / keyId to an order (NE) in the client's database. See Resolving document type IDs.

Orders use the same POST /gateway/invoice/invoices endpoint. See the Usage Guide for the shared contract (currencyId, payments[], discountPercentage).

Overview

Orders are documents that:

📦 Register confirmed customer orders
📋 Serve as order confirmation and picking reference
🔄 Can be converted to invoices (full or partial) through a new document
🚚 Support fulfilment workflows before billing

Stock reservation or movement on orders depends on how NE is in the client's database.

When to Use

✅ Customer confirms an order
✅ Track pending orders before invoicing
✅ Bill after delivery or fulfilment
✅ Partial deliveries over time

Order Characteristics

Characteristic	Value	Description
Affects Stock	⚠️ From type config	Reservation or none — configured per NE type
Requires Payment Array	✅ Yes	`payments[]` required by contract
Can be Closed	✅ Yes	Can be finalized
Fiscal Validation	❌ No	Not a fiscal document
Allows Editing	✅ Yes	While not closed
Conversion	✅ Yes	Create invoice when billing

Stock movement

Stock behaviour follows the document type configuration. To enable reservation on orders, configure the NE type in API Base / backoffice. Line quantities are always positive.

Create Order

Basic Order

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}
X-Timezone: Europe/Lisbon

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "entityDescription": "Example Client, Ltd",
  "obs": "Order confirmed via phone",
  "dueDate": "2025-12-15",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 615
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Product 1",
      "quantity": 10,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Order with Line Discount

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 553.5
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10,
      "retailPrice": 50,
      "discountPercentage": 10,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Backorder (insufficient stock)

Create the order with the requested quantities. If your NE type is configured to validate stock, the API returns a validation error when stock is insufficient; otherwise the order is accepted for later invoicing:

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "obs": "Backorder — awaiting stock replenishment",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 6150
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 100,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

When stock is available, convert to invoice (see below).

Update and Close Order

PUT /gateway/invoice/invoices/456
Content-Type: application/json
Authorization: Bearer {token}

{
  "id": 456,
  "obs": "Delivery scheduled for 2025-12-20",
  "dueDate": "2025-12-20"
}

Close when fully invoiced or cancelled:

{
  "id": 456,
  "close": true,
  "obs": "Fully invoiced — FT A/789"
}

Conversion to Invoice

Billing is done by creating a new invoice — there is no automatic conversion endpoint.

Full Conversion

1. Get the order:

GET /gateway/invoice/invoices/456
Authorization: Bearer {token}

2. Create the invoice:

POST /gateway/invoice/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 615
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Stock outbound on the invoice follows the FT document type configuration. See Invoices Guide.

3. Close the order when fully billed.

Partial Conversion

Invoice only part of the order — use a smaller positive quantity on the invoice:

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "currencyId": 1,
  "obs": "Partial billing — 5 of 10 units",
  "payments": [
    {
      "paymentTypeId": 1,
      "amount": 307.5
    }
  ],
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 5,
      "retailPrice": 50,
      "taxId": 1,
      "secondTaxId": 0
    }
  ]
}

Order remains open

In partial conversion, keep the order open until all quantities are invoiced.

Best Practices

✅ Recommended

Always send currencyId and header payments[]
Set expected delivery in dueDate
Close fully invoiced orders
Keep fulfilment notes in obs
Configure NE stock behaviour in document type settings
Resolve types with GET /gateway/document-type — Usage Guide

❌ Avoid

Negative quantities
Leaving orders open after full invoicing
Creating duplicate orders for the same customer request

Common Use Cases

Standard Order

Customer order with available stock; invoice after picking.

Order with Reservation

NE type configured to reserve stock until invoicing or cancellation.

Partial Fulfilment

Multiple invoices over time for the same order reference.

Backorder

Order accepted pending replenishment; invoice when stock arrives.

Differences vs Quotes

Aspect	Quote (ORC)	Order (NE)
Commitment	Proposal	Confirmed order
Stock	Typically none	Per NE type config
Validity	Limited	Until fulfilled
Purpose	Negotiation	Confirmation

Differences vs Invoices

Aspect	Order (NE)	Invoice (FT/FS)
Stock	Per NE type config	Outbound (typical)
Fiscal	No	Yes
Purpose	Order tracking	Definitive sale

For corrections after invoicing, use Credit Notes Guide.

Next Steps

Invoices Guide — Convert order to invoice (FT/FS)
Invoice-Receipt Guide — Bill and collect in one step (FR)
Quotes Guide — From quote to order
Usage Guide — General API information

Last Updated: June 9, 2026

Overview​

When to Use​

Order Characteristics​

Create Order​

Basic Order​

Order with Line Discount​

Backorder (insufficient stock)​

Update and Close Order​

Conversion to Invoice​

Full Conversion​

Partial Conversion​

Best Practices​

✅ Recommended​

❌ Avoid​

Common Use Cases​

Standard Order​

Order with Reservation​

Partial Fulfilment​

Backorder​

Differences vs Quotes​

Differences vs Invoices​

Next Steps​