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": "jsmith@example.com"
},
"customer_location": {
"id": 2,
"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>"
}
'import requests
url = "https://api.parceltracer.com/v1/external/orders/"
payload = {
"merchant_location": 123,
"customer": {
"id": 2,
"phone_number": "<string>",
"secondary_phone_number": "<string>",
"name": "<string>",
"email": "jsmith@example.com"
},
"customer_location": {
"id": 2,
"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>"
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchant_location: 123,
customer: {
id: 2,
phone_number: '<string>',
secondary_phone_number: '<string>',
name: '<string>',
email: 'jsmith@example.com'
},
customer_location: {id: 2, 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>'
})
};
fetch('https://api.parceltracer.com/v1/external/orders/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.parceltracer.com/v1/external/orders/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'merchant_location' => 123,
'customer' => [
'id' => 2,
'phone_number' => '<string>',
'secondary_phone_number' => '<string>',
'name' => '<string>',
'email' => 'jsmith@example.com'
],
'customer_location' => [
'id' => 2,
'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>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.parceltracer.com/v1/external/orders/"
payload := strings.NewReader("{\n \"merchant_location\": 123,\n \"customer\": {\n \"id\": 2,\n \"phone_number\": \"<string>\",\n \"secondary_phone_number\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n },\n \"customer_location\": {\n \"id\": 2,\n \"directions\": \"<string>\"\n },\n \"reference_id\": \"\",\n \"is_critical\": false,\n \"is_exchange\": false,\n \"workflow\": \"STANDARD\",\n \"cod\": [\n [\n \"<string>\"\n ]\n ],\n \"number_of_packages\": 1,\n \"description\": \"<string>\",\n \"notes\": \"<string>\",\n \"return_reason\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.parceltracer.com/v1/external/orders/")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchant_location\": 123,\n \"customer\": {\n \"id\": 2,\n \"phone_number\": \"<string>\",\n \"secondary_phone_number\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n },\n \"customer_location\": {\n \"id\": 2,\n \"directions\": \"<string>\"\n },\n \"reference_id\": \"\",\n \"is_critical\": false,\n \"is_exchange\": false,\n \"workflow\": \"STANDARD\",\n \"cod\": [\n [\n \"<string>\"\n ]\n ],\n \"number_of_packages\": 1,\n \"description\": \"<string>\",\n \"notes\": \"<string>\",\n \"return_reason\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.parceltracer.com/v1/external/orders/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"merchant_location\": 123,\n \"customer\": {\n \"id\": 2,\n \"phone_number\": \"<string>\",\n \"secondary_phone_number\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n },\n \"customer_location\": {\n \"id\": 2,\n \"directions\": \"<string>\"\n },\n \"reference_id\": \"\",\n \"is_critical\": false,\n \"is_exchange\": false,\n \"workflow\": \"STANDARD\",\n \"cod\": [\n [\n \"<string>\"\n ]\n ],\n \"number_of_packages\": 1,\n \"description\": \"<string>\",\n \"notes\": \"<string>\",\n \"return_reason\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"order_id": "179",
"reference_id": "123",
"is_exchange": false,
"workflow": "STANDARD",
"tracking_link": "https://prod.parceltracer.app/tracking/9kQz2Lp4x",
"order_url": "https://acme.parceltracer.app/order/79",
"is_critical": true,
"merchant_location": 1,
"cod": [
[
"LBP",
"2000000.00"
],
[
"USD",
"50.50"
]
],
"delivery_fee": [
[
"USD",
"3.00"
]
],
"number_of_packages": 1,
"description": "2x T-Shirt (Size: M)",
"notes": "",
"return_reason": "",
"delivery_state": "CREATED",
"payment_state": "UNPAID",
"merchant_invoice": null,
"integration_items": [
{
"name": "T-Shirt (Size: M)",
"quantity": 2,
"price": "19.99",
"currency": "USD",
"image_url": "https://shop.example.com/img/tshirt.png",
"source_url": "https://shop.example.com/products/tshirt"
}
],
"source_url": "https://shop.example.com/orders/1042",
"statestamps": [
{
"delivery_state": "CREATED",
"payment_state": "UNPAID",
"timestamp": "2026-07-22T23:02:34.268588+03:00"
}
],
"customer": {
"id": 9707,
"name": "Joelle",
"phone_number": "+96131234567",
"secondary_phone_number": null,
"email": ""
},
"customer_location": {
"id": 9689,
"area": {
"id": 55,
"name_ar": "بلدي",
"name_en": "Balde",
"district": "Akkar",
"lat": "34.560760000000000",
"long": "36.144910000000000",
"maps_link": "http://maps.google.com/maps?q=34.56076,36.14491",
"code": "LBN0055",
"is_external": false,
"area_group": null
},
"directions": ""
}
}{
"error": "true",
"message": "Validation failed.",
"details": "workflow: \"STANDARDS\" is not a valid choice."
}{
"error": "true",
"message": "Unexpected error.",
"details": "Internal server error"
}Orders
Create order
Create a new order with customer and location details.
- If
customer.idis provided, an existing customer is updated. - If only
phone_numberis provided, a customer is looked up or created. customer_location.idworks similarly, but must belong to the customer.codis a list of currency/amount pairs. Example: [[‘USD’, ‘10’], [‘LBP’, ‘1000000’]]
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": "jsmith@example.com"
},
"customer_location": {
"id": 2,
"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>"
}
'import requests
url = "https://api.parceltracer.com/v1/external/orders/"
payload = {
"merchant_location": 123,
"customer": {
"id": 2,
"phone_number": "<string>",
"secondary_phone_number": "<string>",
"name": "<string>",
"email": "jsmith@example.com"
},
"customer_location": {
"id": 2,
"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>"
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchant_location: 123,
customer: {
id: 2,
phone_number: '<string>',
secondary_phone_number: '<string>',
name: '<string>',
email: 'jsmith@example.com'
},
customer_location: {id: 2, 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>'
})
};
fetch('https://api.parceltracer.com/v1/external/orders/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.parceltracer.com/v1/external/orders/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'merchant_location' => 123,
'customer' => [
'id' => 2,
'phone_number' => '<string>',
'secondary_phone_number' => '<string>',
'name' => '<string>',
'email' => 'jsmith@example.com'
],
'customer_location' => [
'id' => 2,
'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>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.parceltracer.com/v1/external/orders/"
payload := strings.NewReader("{\n \"merchant_location\": 123,\n \"customer\": {\n \"id\": 2,\n \"phone_number\": \"<string>\",\n \"secondary_phone_number\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n },\n \"customer_location\": {\n \"id\": 2,\n \"directions\": \"<string>\"\n },\n \"reference_id\": \"\",\n \"is_critical\": false,\n \"is_exchange\": false,\n \"workflow\": \"STANDARD\",\n \"cod\": [\n [\n \"<string>\"\n ]\n ],\n \"number_of_packages\": 1,\n \"description\": \"<string>\",\n \"notes\": \"<string>\",\n \"return_reason\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.parceltracer.com/v1/external/orders/")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchant_location\": 123,\n \"customer\": {\n \"id\": 2,\n \"phone_number\": \"<string>\",\n \"secondary_phone_number\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n },\n \"customer_location\": {\n \"id\": 2,\n \"directions\": \"<string>\"\n },\n \"reference_id\": \"\",\n \"is_critical\": false,\n \"is_exchange\": false,\n \"workflow\": \"STANDARD\",\n \"cod\": [\n [\n \"<string>\"\n ]\n ],\n \"number_of_packages\": 1,\n \"description\": \"<string>\",\n \"notes\": \"<string>\",\n \"return_reason\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.parceltracer.com/v1/external/orders/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"merchant_location\": 123,\n \"customer\": {\n \"id\": 2,\n \"phone_number\": \"<string>\",\n \"secondary_phone_number\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n },\n \"customer_location\": {\n \"id\": 2,\n \"directions\": \"<string>\"\n },\n \"reference_id\": \"\",\n \"is_critical\": false,\n \"is_exchange\": false,\n \"workflow\": \"STANDARD\",\n \"cod\": [\n [\n \"<string>\"\n ]\n ],\n \"number_of_packages\": 1,\n \"description\": \"<string>\",\n \"notes\": \"<string>\",\n \"return_reason\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"order_id": "179",
"reference_id": "123",
"is_exchange": false,
"workflow": "STANDARD",
"tracking_link": "https://prod.parceltracer.app/tracking/9kQz2Lp4x",
"order_url": "https://acme.parceltracer.app/order/79",
"is_critical": true,
"merchant_location": 1,
"cod": [
[
"LBP",
"2000000.00"
],
[
"USD",
"50.50"
]
],
"delivery_fee": [
[
"USD",
"3.00"
]
],
"number_of_packages": 1,
"description": "2x T-Shirt (Size: M)",
"notes": "",
"return_reason": "",
"delivery_state": "CREATED",
"payment_state": "UNPAID",
"merchant_invoice": null,
"integration_items": [
{
"name": "T-Shirt (Size: M)",
"quantity": 2,
"price": "19.99",
"currency": "USD",
"image_url": "https://shop.example.com/img/tshirt.png",
"source_url": "https://shop.example.com/products/tshirt"
}
],
"source_url": "https://shop.example.com/orders/1042",
"statestamps": [
{
"delivery_state": "CREATED",
"payment_state": "UNPAID",
"timestamp": "2026-07-22T23:02:34.268588+03:00"
}
],
"customer": {
"id": 9707,
"name": "Joelle",
"phone_number": "+96131234567",
"secondary_phone_number": null,
"email": ""
},
"customer_location": {
"id": 9689,
"area": {
"id": 55,
"name_ar": "بلدي",
"name_en": "Balde",
"district": "Akkar",
"lat": "34.560760000000000",
"long": "36.144910000000000",
"maps_link": "http://maps.google.com/maps?q=34.56076,36.14491",
"code": "LBN0055",
"is_external": false,
"area_group": null
},
"directions": ""
}
}{
"error": "true",
"message": "Validation failed.",
"details": "workflow: \"STANDARDS\" is not a valid choice."
}{
"error": "true",
"message": "Unexpected error.",
"details": "Internal server error"
}Authorizations
Body
application/jsonapplication/x-www-form-urlencodedmultipart/form-data
("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 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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Reference ID of the order, for internal tracking by the shop.
Mark the order as critical for prioritized handling (subject to the delivery company load and availability)
('Require pickup of a return package upon delivery.\n', 'This option is only applicable when workflow is STANDARD')
Order workflow: STANDARD or RETURN.
STANDARD- STANDARDRETURN- RETURN
Available options:
STANDARD, RETURN Total amount to be collected upon delivery (or upon return). Example: [['USD', '123.5']]
Required array length:
2 elements('Number of packages in the order.\n', 'Should be greater than or equal to 1.')
Optional description of the order contents.
Extra notes about the order, visible to delivery company, carriers and customers.
Applicable if the order is a return. Reason for the return.
Response
Successful creation
Unique order identifier, auto-generated by Parcel Tracer (e.g. '11').
Reference ID of the order, for internal tracking by the shop.
Mark the order as critical for prioritized handling (subject to the delivery company load and availability)
('Require pickup of a return package upon delivery.\n', 'This option is only applicable when workflow is STANDARD')
Order workflow: STANDARD or RETURN.
STANDARD- STANDARDRETURN- RETURN
Available options:
STANDARD, RETURN ("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 for the order.
Show child attributes
Show child attributes
Customer location for delivery or pickup.
Show child attributes
Show child attributes
Total amount to be collected upon delivery (or upon return). Example: [['USD', '123.5']]
Required array length:
2 elements('Number of packages in the order.\n', 'Should be greater than or equal to 1.')
Optional description of the order contents.
Extra notes about the order, visible to delivery company, carriers and customers.
Payment state of the order.
UNPAID- UNPAIDPENDING_PAYMENT_BY_DRIVER- PENDING_PAYMENT_BY_DRIVERPAID_BY_DRIVER- PAID_BY_DRIVERPENDING_PAYMENT_TO_MERCHANT- PENDING_PAYMENT_TO_MERCHANTPAID_TO_MERCHANT- PAID_TO_MERCHANT
Available options:
UNPAID, PENDING_PAYMENT_BY_DRIVER, PAID_BY_DRIVER, PENDING_PAYMENT_TO_MERCHANT, PAID_TO_MERCHANT Publicly accessible link to track the order's delivery journey.
Link to the order in the merchant's Parcel Tracer dashboard.
Current delivery state of the order. One of: 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.
Chronological history of the order's delivery and payment states.
Show child attributes
Show child attributes
Total amount charged for the delivery operation. Required only if workflow is STANDARD. Example: [['USD', '123.5']]
Required array length:
2 elementsApplicable if the order is a return. Reason for the return.
Identifier of the merchant invoice this order was billed on, or null if not yet invoiced.
Structured line items from an integrated platform (e.g. Shopify/WooCommerce).
Show child attributes
Show child attributes
Link back to the order on the originating platform.