Orders Guide

Document Type: Order
Document Type ID: 3 (verify with /document-type)

Overview

Orders are documents that:

📦 Register customer orders
⚠️ OPTIONALLY reserve stock
🔄 Can be converted to invoices (full or partial)
📋 Serve as order confirmation
🚚 Base for picking and shipping

When to Use

✅ Customer confirms order
✅ Need to reserve stock
✅ Track pending orders
✅ Billing after order

Order Characteristics

Characteristic	Value	Description
Affects Stock	⚠️ Optional	Can reserve stock
Requires Payment	❌ No	Confirmed order
Can be Closed	✅ Yes	Can be finalized
Fiscal Validation	❌ No	Not a fiscal document
Allows Editing	✅ Yes	While not closed
Conversion	✅ Yes	Can generate Invoice

Create Order

Basic Order

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "entityDescription": "Example Client, Ltd",
  "obs": "Order confirmed via phone",
  "docReference": "PO-2025-001",
  "dueDate": "2025-12-15",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "itemDescription": "Product 1",
      "quantity": 10.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 0,              // Does not affect stock
      "stockBehavior": 0,          // No stock validation
      "secondTaxId": 0
    }
  ]
}

Order with Stock Reservation

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "obs": "Stock reserved until 12/31/2025",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10.0,
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 2,              // Stock reservation
      "stockBehavior": 1,          // Validate availability
      "originWarehouse": 1,
      "secondTaxId": 0
    }
  ]
}

Stock Reservation

Use stockFlow = 2 to reserve stock. The stock is blocked for other sales.

Conversion to Invoice

Full Conversion

1. Get order:

GET /api/v1/invoices/456
Authorization: Bearer {token}

2. Create invoice:

POST /api/v1/invoices
Content-Type: application/json
Authorization: Bearer {token}

{
  "serieId": 1,
  "documentTypeId": 5,             // Invoice
  "entityKeyId": "CLI001",
  "docReference": "ORD A/456",     // Reference to order
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 10.0,            // Full quantity
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,              // Stock outbound
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

3. Close order:

PUT /api/v1/invoices/456

{
  "id": 456,
  "close": true,
  "obs": "Fully invoiced - INV A/789"
}

Partial Conversion

To invoice only part of the order, create an invoice with a smaller quantity:

{
  "serieId": 1,
  "documentTypeId": 5,
  "entityKeyId": "CLI001",
  "docReference": "ORD A/456 (Partial)",
  "obs": "Partial billing - 5 of 10 units",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 5.0,             // Only 5 units
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 1,
      "stockBehavior": 1,
      "secondTaxId": 0
    }
  ]
}

Order Remains Open

In partial conversion, the order remains open for future invoices.

Backorder Management

Scenario: Insufficient Stock

If there's not enough stock, create an order without reservation:

{
  "serieId": 11,
  "documentTypeId": 3,
  "entityKeyId": "CLI001",
  "obs": "Backorder - awaiting stock replenishment",
  "documentBodies": [
    {
      "itemKeyId": "PROD001",
      "quantity": 100.0,           // Requested quantity
      "retailPrice": 50.00,
      "taxId": 1,
      "paymentType": 1,
      "stockFlow": 0,              // No reservation (backorder)
      "stockBehavior": 0,          // No validation
      "secondTaxId": 0
    }
  ]
}

When stock is available, convert to invoice.

Best Practices

✅ Recommended

Validate stock before reserving
Use customer's purchase order reference
Set delivery deadline in dueDate
Close fully invoiced orders
Keep history in obs field
Use stock reservation when appropriate

❌ Avoid

Reserving stock unnecessarily
Leaving orders open after invoicing
Forgetting to reference order in invoice
Creating multiple orders for the same request

Common Use Cases

Standard Order

Customer places order, stock available, immediate billing.

Order with Reservation

Customer places order, stock reserved, later billing.

Partial Order

Customer places large order, partial deliveries/invoices.

Backorder

Customer places order, insufficient stock, awaits replenishment.

Stock Flows

`stockFlow` Value	Behavior	When to Use
`0`	Does not affect stock	Backorder, order without reservation
`1`	Stock outbound	DO NOT use for orders
`2`	Stock reservation	Order with reservation
`-1`	Stock inbound	DO NOT use for orders

Differences vs Quotes

Aspect	Quote	Order
Commitment	Proposal	Confirmed order
Stock	Never affects	Can reserve
Validity	Limited	Until fulfilled
Purpose	Negotiation	Confirmation

Differences vs Invoices

Aspect	Order	Invoice
Stock	Reservation (optional)	Outbound
Fiscal	No	Yes
Payment	Not required	Required
Purpose	Order	Definitive sale

Next Steps

Invoices Guide - Convert order to invoice
Quotes Guide - From quote to order
Usage Guide - General API information

Last Updated: December 2, 2025

Overview​

When to Use​

Order Characteristics​

Create Order​

Basic Order​

Order with Stock Reservation​

Conversion to Invoice​

Full Conversion​

Partial Conversion​

Backorder Management​

Scenario: Insufficient Stock​

Best Practices​

✅ Recommended​

❌ Avoid​

Common Use Cases​

Standard Order​

Order with Reservation​

Partial Order​

Backorder​

Stock Flows​

Differences vs Quotes​

Differences vs Invoices​

Next Steps​