# Orders

> Understand how orders work in 4N NextDay. Same statuses you see in your panel, now synced with your system.

Source: https://api-doc.4nortes.app/orders

When you sync an order from your system, it works just like creating one in your panel. You'll see the same information: sender, recipient, destination, and tracking status.

<a id="order-model"></a>

## What's in an order

Every order has the same fields you fill out in your panel:

### Identifiers

- **`id`**: Internal order ID
- **`tracking_number`**: Public tracking number (e.g., `4N000000012345`)
- **`external_reference`**: Your own order code, unique within your account. Orders created with one can also be looked up by it in the [event history](#event-history)
- **`cost_center`**: Cost center for internal accounting
- **`purchase_order`**: Purchase order number
- **`bill_of_lading`**: Bill of lading reference

### Sender Information

- **`sender_name`**: Name of the sender or business
- **`sender_phone`**: Contact phone number
- **`sender_email`**: Contact email address
- **`sender_company`**: Company name (defaults to your account name)

### Recipient Information

- **`recipient_name`**: Name of the recipient
- **`recipient_phone`**: Contact phone number
- **`recipient_email`**: Contact email address
- **`recipient_company`**: Company name

### Destination

- **`destination_address`**: Street address
- **`destination_locality`**: Locality (comuna) name or numeric ID
- **`destination_reference`**: Reference or landmark
- **`destination_building_number`**: Building or apartment number

### Package Details

- **`weight`**: Package weight in kilograms
- **`packages_count`**: Number of packages
- **`picked_up_packages_count`**: Packages already scanned at pickup (`null` until per-package scanning starts)
- **`pending_pickup_packages_count`**: Packages not yet scanned at pickup (`null` until per-package scanning starts)
- **`delivered_packages_count`**: Packages delivered so far (for per-package deliveries)
- **`failed_packages_count`**: Packages whose last delivery attempt failed
- **`returned_packages_count`**: Packages returned to the sender
- **`pending_packages_count`**: Packages neither delivered nor returned
- **`delivery_progress`**: Packages delivered vs. total, as a fraction string (e.g. `"2/3"`)
- **`packages`**: One entry per package with its own `tracking_number` (e.g. `4N000000012345-305`), `delivery_state` (`pending`, `delivered`, `failed`, `returned`) and `picked_up_at` / `delivered_at` / `returned_at` timestamps. Only on the order detail
- **`valuation`**: Declared value (integer)

### Delivery Information

- **`delivery_state`**: Current state of the delivery — the field to build your logic on
- **`internal_state`**: The courier-side status name as shown in the 4 Nortes panel (free text, Spanish, may be `null`). Managed by our operations team and subject to change — display it if you like, never branch on it
- **`service_id`**: Type of delivery service
- **`estimated_delivery_date`**: Expected delivery date
- **`delivery_date`**: Actual delivery date (when delivered)

<a id="delivery-states"></a>

## Delivery states

These are the same statuses you see in your panel. Your orders move through them as they're picked up and delivered:

- `pending`
- `picked_up`
- `in_transit`
- `out_for_delivery`
- `delivered`
- `partially_delivered`
- `failed`
- `closed_with_return`
- `nulled`

### State Descriptions

| State                 | Final | Description                                                                                                                   |
| --------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------- |
| `pending`             | no    | Order has been created and is awaiting pickup                                                                                 |
| `picked_up`           | no    | Package has been collected from the sender                                                                                    |
| `in_transit`          | no    | Package is being transported to the destination area                                                                          |
| `out_for_delivery`    | no    | Package is on the delivery vehicle for final delivery                                                                         |
| `delivered`           | yes   | Package has been successfully delivered to the recipient                                                                      |
| `partially_delivered` | no    | Some packages were delivered, others failed                                                                                   |
| `failed`              | no    | Delivery attempt failed (recipient unavailable, wrong address, etc.)                                                          |
| `closed_with_return`  | yes   | Order closed with at least one package returned to the sender after a failed delivery (any remaining packages were delivered) |
| `nulled`              | yes   | Order has been cancelled                                                                                                      |

Final states (`delivered`, `closed_with_return`, `nulled`) can't be updated or cancelled through the API.

<a id="state-flow"></a>

## How orders flow

Orders move through these states - same as what you see in your panel:

```
pending → picked_up → in_transit → out_for_delivery → delivered
                                         ↓
                                      failed → (retry) → delivered
                                         ↓
                                closed_with_return
```

### Normal flow

1. **pending**: You sync the order from your system
2. **picked\_up**: Courier collects the package from you
3. **in\_transit**: Package is on its way
4. **out\_for\_delivery**: Package is out with the driver
5. **delivered**: Customer receives the package

### When things don't go as planned

- **Failed delivery**: If the driver can't deliver, the order moves to `failed`. It can be retried.
- **Return to sender**: If failed packages are sent back to you instead of retried, the order ends in `closed_with_return` once every package is either delivered or returned. This is a final state.
- **Cancellation**: You can cancel orders in any non-final state. They move to `nulled`.

> **Note:**
>
> Want to know when statuses change? Set up [webhooks](https://api-doc.4nortes.app/webhooks.md) to get notified automatically - no need to check your panel.

<a id="event-history"></a>

## Event history

`delivery_state` tells you where an order is now. When you need to know how it got there — when it was created, every state change, each failed attempt, and (if enabled for your account) the warehouse receptions and route assignments in between — fetch its step-by-step history with [`GET /orders/{reference}/events`](https://api-doc.4nortes.app/api/orders.md#order-events). You can look an order up by our tracking number or by your own `external_reference`, and events come back oldest first.

## Proof of delivery

When an order is delivered, you get the same proof you see in your panel:

- **Recipient name**: Who signed for the package
- **Recipient RUT**: Their Chilean ID (if provided)
- **Recipient role**: Their relationship to the order
- **Location**: GPS coordinates of where it was delivered
- **Photos**: Pictures taken at delivery

You can fetch this through the [Tracking API](https://api-doc.4nortes.app/api/tracking.md) to show customers in your app.