Skip to main content
POST
/
orders
Create order
curl --request POST \
  --url https://api.parceltracer.com/v1/external/orders/ \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "merchant_location": 123,
  "customer": {
    "id": 2,
    "phone_number": "<string>",
    "secondary_phone_number": "<string>",
    "name": "<string>",
    "email": "[email protected]"
  },
  "customer_location": {
    "id": 2,
    "area": {
      "name_ar": "",
      "name_en": "",
      "district": "Zahleh",
      "lat": "<string>",
      "long": "<string>",
      "maps_link": "<string>"
    },
    "directions": "<string>"
  },
  "reference_id": "",
  "is_critical": false,
  "is_exchange": false,
  "workflow": "STANDARD",
  "cod": [
    [
      "<string>"
    ]
  ],
  "number_of_packages": 1,
  "description": "<string>",
  "notes": "<string>",
  "return_reason": "<string>"
}
'
{
  "order_id": "179",
  "reference_id": "123",
  "is_exchange": "false",
  "workflow": "STANDARD",
  "tracking_link": "https://prod.parceltracer.app/tracking/xxxxxxx-yyyyyy",
  "is_critical": "true",
  "merchant_location": 1,
  "cod": [
    [
      "LBP",
      "2000.00"
    ],
    [
      "USD",
      "50.50"
    ]
  ],
  "number_of_packages": 1,
  "description": "",
  "notes": "",
  "return_reason": "",
  "delivery_state": "CREATED",
  "payment_state": "UNPAID",
  "merchant_invoice": null,
  "customer": {
    "id": 9707,
    "name": "Joelle",
    "phone_number": "+96131234567",
    "secondary_phone_number": null,
    "email": ""
  },
  "customer_location": {
    "id": 9689,
    "area": {
      "id": 55,
      "name_en": "Balde",
      "name_ar": "بلدي",
      "lat": 34.56076,
      "long": 36.14491,
      "district": "Akkar",
      "maps_link": "http://maps.google.com/maps?q=34.56076,36.14491"
    },
    "directions": ""
  }
}

Authorizations

​
X-Api-Key
string
header
required

Body

​
merchant_location
integer
required

("Unique identifier of the merchant's location.\n", 'This identifier should correspond to one of the pickup locations visible on the pickup locations page on Parcel Tracer.')

​
customer
object
required

Customer object for the order.

  • Provide 'id' to identify an existing customer (other fields update the record).
  • Otherwise provide 'phone_number' plus required customer fields to create a new customer.
​
customer_location
object
required

Customer location for delivery or pickup.

  • Provide 'id' to identify an existing location (other fields update it).
  • Otherwise, provide full location details to create a new location.
​
reference_id
string
default:""

Reference ID of the order, for internal tracking by the shop.

​
is_critical
boolean
default:false

Mark the order as critical for prioritized handling (subject to the delivery company load and availability)

​
is_exchange
boolean
default:false

('Require pickup of a return package upon delivery.\n', 'This option is only applicable when workflow is STANDARD')

​
workflow
enum<string>
default:STANDARD

Order workflow: STANDARD or RETURN.

  • STANDARD - STANDARD
  • RETURN - RETURN
Available options:
STANDARD,
RETURN
​
cod
string[][]

Total amount to be collected upon delivery (or upon return). Example: [['USD', '123.5']]

Required array length: 2 elements
​
number_of_packages
integer
default:1

('Number of packages in the order.\n', 'Should be greater than or equal to 1.')

​
description
string

Optional description of the order contents.

​
notes
string

Extra notes about the order, visible to delivery company, carriers and customers.

​
return_reason
string

Applicable if the order is a return. Reason for the return.

Response

Successful creation

​
order_id
string | null
required
​
tracking_link
string<uri>
required
​
resolved_customer
object
required
​
resolved_customer_location
object
required
​
merchant_location
integer
required
​
delivery_fee
string[][]
required

Delivery fees charged on the delivery operation. Irrelevant in case of RETURN orders.

Required array length: 2 elements
​
delivery_state
enum<string>
required
  • CREATED - Created
  • PICKUP_REQUESTED - Pickup Requested
  • PICKUP_ASSIGNED - Pickup Assigned
  • SCANNED_FOR_PICKUP - Scanned for Pickup
  • PICKED_UP - Picked Up
  • AT_WAREHOUSE - At Warehouse
  • DELIVERY_ASSIGNED - Delivery Assigned
  • SCANNED_FOR_DELIVERY - Scanned For Delivery
  • PICKED_UP_FOR_DELIVERY - Picked Up For Delivery
  • IN_TRANSIT - In Transit
  • DELIVERED - Delivered
  • AWAITING_RETURN - Awaiting Return
  • CANCELLED - Cancelled
  • DELIVERED_AT_WAREHOUSE - Delivered At Warehouse
Available options:
CREATED,
PICKUP_REQUESTED,
PICKUP_ASSIGNED,
SCANNED_FOR_PICKUP,
PICKED_UP,
AT_WAREHOUSE,
DELIVERY_ASSIGNED,
SCANNED_FOR_DELIVERY,
PICKED_UP_FOR_DELIVERY,
IN_TRANSIT,
DELIVERED,
AWAITING_RETURN,
CANCELLED,
DELIVERED_AT_WAREHOUSE
​
payment_state
string
required
​
merchant_invoice
integer | null
required
​
reference_id
string
Maximum string length: 40
​
is_exchange
boolean
​
workflow
enum<string>
  • STANDARD - Standard
  • RETURN - Return
Available options:
STANDARD,
RETURN
​
is_critical
boolean
​
cod
string[][]

Total amount to be collected upon delivery. Example: [['USD', '123.5']]

Required array length: 2 elements
​
number_of_packages
integer
Required range: 1 <= x <= 99
​
description
string
Maximum string length: 300
​
notes
string
​
return_reason
string
Maximum string length: 300