Orders API

Sync orders from your system, download shipping labels, and manage shipments. Everything you do in your panel, now automated.

POST/orders/create

Sync an order

Send order details from your system. This is the same as filling out the "Create Order" form in your panel.

Request Body

Name
sender_name
Type
string
Description
Name of the sender or business. Max 255 characters. Required.
Name
sender_phone
Type
string
Description
Sender phone number. Max 50 characters.
Name
sender_email
Type
string
Description
Sender email address.
Name
sender_company
Type
string
Description
Sender company name.
Name
recipient_name
Type
string
Description
Name of the recipient. Max 255 characters. Required.
Name
recipient_phone
Type
string
Description
Recipient phone number.
Name
recipient_email
Type
string
Description
Recipient email address.
Name
recipient_company
Type
string
Description
Recipient company name.
Name
destination_address
Type
string
Description
Destination street address. Required.
Name
destination_locality
Type
string
Description
Destination locality (comuna) name. Required.
Name
destination_reference
Type
string
Description
Reference or landmark for the destination.
Name
destination_building_number
Type
string
Description
Building or apartment number at destination.
Name
external_reference
Type
string
Description
Your custom order reference for tracking in your system. Max 255 characters.
Name
cost_center
Type
string
Description
Cost center for internal accounting. Max 255 characters.
Name
purchase_order
Type
string
Description
Purchase order number. Max 255 characters.
Name
bill_of_lading
Type
string
Description
Bill of lading reference. Max 255 characters.
Name
service_id
Type
integer
Description
Delivery service ID. Must belong to your merchant account.
Name
weight
Type
number
Description
Package weight in kilograms. Must be >= 0.
Name
valuation
Type
integer
Description
Declared value of the package. Must be >= 0.
Name
packages_count
Type
integer
Description
Number of packages in this order. Must be >= 1.

POST

/orders/create

curl -X POST https://api.4nortes.app/api/v1/orders/create \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_name": "John Store",
    "sender_phone": "+56912345678",
    "sender_email": "store@example.com",
    "recipient_name": "Jane Doe",
    "recipient_phone": "+56987654321",
    "recipient_email": "jane@example.com",
    "destination_address": "Calle Secundaria 456",
    "destination_locality": "Providencia",
    "destination_reference": "Near the plaza",
    "weight": 2.5,
    "external_reference": "ORDER-001",
    "service_id": 1,
    "packages_count": 1
  }'

Response

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "id": 12345,
    "tracking_number": "4N000000012345",
    "external_reference": "ORDER-001",
    "cost_center": null,
    "purchase_order": null,
    "bill_of_lading": null,
    "merchant_id": 42,
    "service_id": 1,
    "destination": {
      "address_line": "Calle Secundaria 456",
      "locality_id": 2,
      "locality_name": "Providencia",
      "reference": "Near the plaza"
    },
    "recipient": {
      "name": "Jane Doe",
      "phone": "+56987654321",
      "email": "jane@example.com"
    },
    "sender": {
      "name": "John Store",
      "phone": "+56912345678",
      "email": "store@example.com"
    },
    "delivery_state": "pending",
    "packages_count": 1,
    "weight": 2.5,
    "valuation": 0,
    "created_at": "2025-02-03T10:30:00.000000Z"
  },
  "timestamp": "2025-02-03T10:30:00.000000Z"
}

GET/orders/{tracking_number}

Get order details

Fetch order details using the tracking number. Same info you see when clicking an order in your panel.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number (e.g., 4N000000012345). Required.

GET

/orders/{tracking_number}

curl https://api.4nortes.app/api/v1/orders/4N000000012345 \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Order retrieved successfully",
  "data": {
    "id": 12345,
    "tracking_number": "4N000000012345",
    "external_reference": "ORDER-001",
    "cost_center": null,
    "purchase_order": null,
    "bill_of_lading": null,
    "delivery_state": "in_transit",
    "internal_state": "in_transit",
    "sender": {
      "name": "John Store",
      "phone": "+56912345678",
      "email": "store@example.com"
    },
    "recipient": {
      "name": "Jane Doe",
      "phone": "+56987654321",
      "email": "jane@example.com"
    },
    "destination": {
      "address_line": "Calle Secundaria 456",
      "locality_id": 2,
      "locality_name": "Providencia",
      "reference": "Near the plaza"
    },
    "packages_count": 1,
    "delivered_packages_count": 0,
    "delivery_progress": 0,
    "weight": 2.5,
    "valuation": 0,
    "estimated_delivery_date": "2025-02-05T00:00:00.000000Z",
    "delivery_date": null,
    "timeline": [
      {
        "state": "pending",
        "timestamp": "2025-02-03T10:30:00.000000Z"
      },
      {
        "state": "picked_up",
        "timestamp": "2025-02-03T14:30:00.000000Z"
      },
      {
        "state": "in_transit",
        "timestamp": "2025-02-03T18:00:00.000000Z"
      }
    ],
    "created_at": "2025-02-03T10:30:00.000000Z"
  },
  "timestamp": "2025-02-04T08:00:00.000000Z"
}

GET/orders

List your orders

Get a list of your orders. Like the orders table in your panel, but in your code.

Query Parameters

Name
page
Type
integer
Description
Page number for pagination. Default: 1
Name
per_page
Type
integer
Description
Number of results per page. Default: 15, Max: 100

GET

/orders

curl "https://api.4nortes.app/api/v1/orders?page=1&per_page=10" \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Orders retrieved successfully",
  "data": {
    "items": [
      {
        "id": 12345,
        "tracking_number": "4N000000012345",
        "external_reference": "ORDER-001",
        "cost_center": null,
        "purchase_order": null,
        "bill_of_lading": null,
        "destination": {
          "address_line": "Calle Secundaria 456",
          "locality_id": 2,
          "locality_name": "Providencia",
          "reference": "Near the plaza"
        },
        "recipient": {
          "name": "Jane Doe",
          "phone": "+56987654321",
          "email": "jane@example.com"
        },
        "delivery_state": "pending",
        "packages_count": 1,
        "delivered_packages_count": 0,
        "delivery_progress": 0,
        "weight": 2.5,
        "valuation": 0,
        "created_at": "2025-02-03T10:30:00.000000Z"
      }
    ],
    "meta": {
      "current_page": 1,
      "from": 1,
      "to": 10,
      "last_page": 5,
      "per_page": 10,
      "total": 47
    }
  },
  "timestamp": "2025-02-04T08:00:00.000000Z"
}

PATCH/orders/{tracking_number}

Update an order

Edit an existing order. All fields are optional — send only the ones you want to change. Orders in a final state (delivered, nulled) cannot be updated.

This endpoint can update recipient details, the destination address, and order metadata. It cannot change sender_*, packages_count, or service_id — use Update package count for package counts.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number. Required.

Request Body

All fields are optional. Only include the ones you want to change.

Name
recipient_name
Type
string
Description
Name of the recipient. Max 255 characters.
Name
recipient_company
Type
string
Description
Recipient company name. Max 255 characters.
Name
recipient_phone
Type
string
Description
Recipient phone number. Max 50 characters.
Name
recipient_email
Type
string
Description
Recipient email address. Max 255 characters.
Name
destination_address
Type
string
Description
Destination street address. Max 500 characters.
Name
destination_locality
Type
string
Description
Destination locality (comuna) name or ID. Max 100 characters.
Name
destination_reference
Type
string
Description
Reference or landmark. Max 500 characters.
Name
destination_building_number
Type
string
Description
Building or apartment number. Max 50 characters.
Name
external_reference
Type
string
Description
Your custom order reference. Max 255 characters.
Name
cost_center
Type
string
Description
Cost center for internal accounting. Max 255 characters.
Name
purchase_order
Type
string
Description
Purchase order number. Max 255 characters.
Name
bill_of_lading
Type
string
Description
Bill of lading reference. Max 255 characters.
Name
valuation
Type
integer
Description
Declared value of the package. Must be >= 0.
Name
weight
Type
number
Description
Package weight in kilograms. Must be >= 0.

PATCH

/orders/{tracking_number}

curl -X PATCH https://api.4nortes.app/api/v1/orders/4N000000012345 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_phone": "+56911112222",
    "destination_address": "Nueva Avenida 789",
    "destination_reference": "Building B, gate 3"
  }'

Response

{
  "success": true,
  "message": "Order updated successfully",
  "data": {
    "id": 12345,
    "tracking_number": "4N000000012345",
    "external_reference": "ORDER-001",
    "cost_center": null,
    "purchase_order": null,
    "bill_of_lading": null,
    "delivery_state": "pending",
    "internal_state": "received",
    "sender": {
      "name": "John Store",
      "phone": "+56912345678",
      "email": "store@example.com"
    },
    "recipient": {
      "name": "Jane Doe",
      "phone": "+56911112222",
      "email": "jane@example.com"
    },
    "destination": {
      "address_line": "Nueva Avenida 789",
      "locality_id": 2,
      "locality_name": "Providencia",
      "reference": "Building B, gate 3"
    },
    "packages_count": 1,
    "delivered_packages_count": 0,
    "delivery_progress": 0,
    "weight": 2.5,
    "valuation": 0,
    "timeline": [
      {
        "state": "pending",
        "timestamp": "2025-02-03T10:30:00.000000Z"
      }
    ],
    "estimated_delivery_date": "2025-02-05T00:00:00.000000Z",
    "delivery_date": null,
    "created_at": "2025-02-03T10:30:00.000000Z"
  },
  "timestamp": "2025-02-03T11:15:00.000000Z"
}

Final-state Error

{
  "success": false,
  "message": "Order cannot be updated. Current state: delivered",
  "errors": null
}

POST/orders/{tracking_number}/cancel

Cancel an order

Cancel an order that hasn't reached a final state. Same as the cancel button in your panel.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number to cancel. Required.

Orders can be cancelled while in any non-final state. Once an order reaches delivered or nulled, it cannot be cancelled.

POST

/orders/{tracking_number}/cancel

curl -X POST https://api.4nortes.app/api/v1/orders/4N000000012345/cancel \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Order cancelled successfully",
  "data": {
    "tracking_number": "4N000000012345",
    "delivery_state": "nulled"
  },
  "timestamp": "2025-02-03T11:00:00.000000Z"
}

GET/orders/{tracking_number}/labels

Get labels

Get the shipping label information for an order.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number. Required.

Response Fields

Name
url
Type
string
Description
URL to download the label.
Name
packages_count
Type
integer
Description
Number of packages in the order (one label per package).
Name
generated_at
Type
string
Description
Timestamp when the label was generated.

GET

/orders/{tracking_number}/labels

curl "https://api.4nortes.app/api/v1/orders/4N000000012345/labels" \
  -H "Authorization: Bearer {token}"

Response

{
  "success": true,
  "message": "Label generated successfully",
  "data": {
    "url": "https://storage.example.com/labels/4N000000012345.pdf",
    "packages_count": 1,
    "generated_at": "2025-02-03T10:35:00.000000Z"
  },
  "timestamp": "2025-02-03T10:35:00.000000Z"
}

Error Response

{
  "success": false,
  "message": "Order not found",
  "errors": null
}

POST/orders/labels/batch

Batch labels

Generate labels for multiple orders at once.

Request Body

Name
tracking_numbers
Type
array
Description
Array of tracking numbers to generate labels for. Required.

POST

/orders/labels/batch

curl -X POST https://api.4nortes.app/api/v1/orders/labels/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tracking_numbers": ["4N000000012345", "4N000000012346"]
  }'

Response

{
  "success": true,
  "message": "Labels generated successfully",
  "data": {
    "url": "https://storage.example.com/labels/batch-abc123.pdf",
    "orders_count": 2,
    "packages_count": 3,
    "missing_tracking_numbers": [],
    "generated_at": "2025-02-03T10:35:00.000000Z"
  },
  "timestamp": "2025-02-03T10:35:00.000000Z"
}

POST/orders/{tracking_number}/packages/set

Update package count

Update the number of packages for an order.

Path Parameters

Name
tracking_number
Type
string
Description
The order tracking number. Required.

Request Body

Name
packages_count
Type
integer
Description
New number of packages. Required.

POST

/orders/{tracking_number}/packages/set

curl -X POST https://api.4nortes.app/api/v1/orders/4N000000012345/packages/set \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "packages_count": 3
  }'

Response

{
  "success": true,
  "message": "Successfully added 2 package(s)",
  "data": {
    "tracking_number": "4N000000012345",
    "packages_count": 3,
    "previous_count": 1,
    "change": 2
  },
  "timestamp": "2025-02-03T11:00:00.000000Z"
}