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.

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
  • 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)

Delivery states

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

PendingPicked UpIn TransitOut for DeliveryDeliveredPartially DeliveredFailedReturned to SenderCancelled

State Descriptions

StateFinalDescription
pendingnoOrder has been created and is awaiting pickup
picked_upnoPackage has been collected from the sender
in_transitnoPackage is being transported to the destination area
out_for_deliverynoPackage is on the delivery vehicle for final delivery
deliveredyesPackage has been successfully delivered to the recipient
partially_deliverednoSome packages were delivered, others failed
failednoDelivery attempt failed (recipient unavailable, wrong address, etc.)
closed_with_returnyesOrder closed with at least one package returned to the sender after a failed delivery (any remaining packages were delivered)
nulledyesOrder has been cancelled

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

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.

Want to know when statuses change? Set up webhooks to get notified automatically - no need to check your panel.

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. 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 to show customers in your app.

Was this page helpful?