Shipments

Create Shipment

Creates a Shipment in your account. Only shipment_id is required; a Shipment created without a tracking_number and carrier is an Open Shipment — a standalone record you can complete later, or hand to the Booking API to book with a carrier.

To have Perform.AI track the Shipment, also provide tracking_number and carrier_reference. The carrier_reference must exist in your account’s carrier configuration (Settings > Carriers) — an unconfigured value blocks creation with a validation error.

Only the notification_email / notification_phone arrays subscribe recipients to tracking notifications; the email / phone inside address objects never do.

POST

shipment

Create Shipment

curl --request POST \
  --url https://api.perform.ai/v5/shipment/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "shipment_id": "SHP-2026-000002",
  "tracking_number": "00340434616780000001",
  "carrier_reference": "dhl-ecommerce-de",
  "order_id": "ORD-2026-000114",
  "tags": [
    "webshop"
  ],
  "notification_email": [
    "jane.doe@example.com"
  ],
  "to_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "line1": "52 Bread Street",
    "postal_code": "049145",
    "city": "Singapore",
    "country_code": "SG"
  },
  "from_address": {
    "city": "Berlin",
    "country_code": "DE"
  }
}
'

import requests

url = "https://api.perform.ai/v5/shipment/"

payload = {
    "shipment_id": "SHP-2026-000002",
    "tracking_number": "00340434616780000001",
    "carrier_reference": "dhl-ecommerce-de",
    "order_id": "ORD-2026-000114",
    "tags": ["webshop"],
    "notification_email": ["jane.doe@example.com"],
    "to_address": {
        "first_name": "Jane",
        "last_name": "Doe",
        "line1": "52 Bread Street",
        "postal_code": "049145",
        "city": "Singapore",
        "country_code": "SG"
    },
    "from_address": {
        "city": "Berlin",
        "country_code": "DE"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    shipment_id: 'SHP-2026-000002',
    tracking_number: '00340434616780000001',
    carrier_reference: 'dhl-ecommerce-de',
    order_id: 'ORD-2026-000114',
    tags: ['webshop'],
    notification_email: ['jane.doe@example.com'],
    to_address: {
      first_name: 'Jane',
      last_name: 'Doe',
      line1: '52 Bread Street',
      postal_code: '049145',
      city: 'Singapore',
      country_code: 'SG'
    },
    from_address: {city: 'Berlin', country_code: 'DE'}
  })
};

fetch('https://api.perform.ai/v5/shipment/', 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.perform.ai/v5/shipment/",
  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([
    'shipment_id' => 'SHP-2026-000002',
    'tracking_number' => '00340434616780000001',
    'carrier_reference' => 'dhl-ecommerce-de',
    'order_id' => 'ORD-2026-000114',
    'tags' => [
        'webshop'
    ],
    'notification_email' => [
        'jane.doe@example.com'
    ],
    'to_address' => [
        'first_name' => 'Jane',
        'last_name' => 'Doe',
        'line1' => '52 Bread Street',
        'postal_code' => '049145',
        'city' => 'Singapore',
        'country_code' => 'SG'
    ],
    'from_address' => [
        'city' => 'Berlin',
        'country_code' => 'DE'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.perform.ai/v5/shipment/"

	payload := strings.NewReader("{\n  \"shipment_id\": \"SHP-2026-000002\",\n  \"tracking_number\": \"00340434616780000001\",\n  \"carrier_reference\": \"dhl-ecommerce-de\",\n  \"order_id\": \"ORD-2026-000114\",\n  \"tags\": [\n    \"webshop\"\n  ],\n  \"notification_email\": [\n    \"jane.doe@example.com\"\n  ],\n  \"to_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"line1\": \"52 Bread Street\",\n    \"postal_code\": \"049145\",\n    \"city\": \"Singapore\",\n    \"country_code\": \"SG\"\n  },\n  \"from_address\": {\n    \"city\": \"Berlin\",\n    \"country_code\": \"DE\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.perform.ai/v5/shipment/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"shipment_id\": \"SHP-2026-000002\",\n  \"tracking_number\": \"00340434616780000001\",\n  \"carrier_reference\": \"dhl-ecommerce-de\",\n  \"order_id\": \"ORD-2026-000114\",\n  \"tags\": [\n    \"webshop\"\n  ],\n  \"notification_email\": [\n    \"jane.doe@example.com\"\n  ],\n  \"to_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"line1\": \"52 Bread Street\",\n    \"postal_code\": \"049145\",\n    \"city\": \"Singapore\",\n    \"country_code\": \"SG\"\n  },\n  \"from_address\": {\n    \"city\": \"Berlin\",\n    \"country_code\": \"DE\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.perform.ai/v5/shipment/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"shipment_id\": \"SHP-2026-000002\",\n  \"tracking_number\": \"00340434616780000001\",\n  \"carrier_reference\": \"dhl-ecommerce-de\",\n  \"order_id\": \"ORD-2026-000114\",\n  \"tags\": [\n    \"webshop\"\n  ],\n  \"notification_email\": [\n    \"jane.doe@example.com\"\n  ],\n  \"to_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"line1\": \"52 Bread Street\",\n    \"postal_code\": \"049145\",\n    \"city\": \"Singapore\",\n    \"country_code\": \"SG\"\n  },\n  \"from_address\": {\n    \"city\": \"Berlin\",\n    \"country_code\": \"DE\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "api_response": "200",
  "data": {
    "shipment_uuid": "5b8ed503-20d2-46cf-8675-ce77a059f691",
    "order_uuid": "a0144751-6530-4135-8d73-f258a28ba27d",
    "documents": [],
    "created_date": "2026-09-19T03:26:29+00:00"
  }
}

Authorizations

Authorization

string

header

required

Used by every functional endpoint. Generate the token with POST /auth/oauth/token/ and send it as Authorization: Bearer {token}.

Body

application/json

shipment_id

string

required

Your unique identifier. Unique across the account; cannot be changed after creation. Accepts A–Z a–z 0–9 _ - ., no spaces.

Maximum string length: 50

tracking_number

string

Carrier tracking number — optional, but needed (with carrier_reference) for tracking. A–Z a–z 0–9 _ - . /, no spaces, at least one digit. Stored uppercase.

Required string length: 6 - 50

carrier_reference

string

A carrier reference configured under Settings > Carriers. An unconfigured value blocks creation.

Maximum string length: 50

shipment_reference

string

Maximum string length: 50

additional_reference

string

Maximum string length: 50

order_uuid

string<uuid>

Attach to an existing order by its Perform.AI identifier. Preferred over order_id if both are sent.

order_id

string

Your order identifier. Creates the order if it doesn't exist.

Maximum string length: 50

order_reference

string

Settable only together with a new order_id.

Maximum string length: 50

order_source_type

string

Maximum string length: 500

order_source_name

string

Maximum string length: 500

Response

Shipment created.

Response of Create Shipment and Update Shipment.

api_response

string

data

object

Show child attributes

Create Shipment

curl --request POST \
  --url https://api.perform.ai/v5/shipment/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "shipment_id": "SHP-2026-000002",
  "tracking_number": "00340434616780000001",
  "carrier_reference": "dhl-ecommerce-de",
  "order_id": "ORD-2026-000114",
  "tags": [
    "webshop"
  ],
  "notification_email": [
    "jane.doe@example.com"
  ],
  "to_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "line1": "52 Bread Street",
    "postal_code": "049145",
    "city": "Singapore",
    "country_code": "SG"
  },
  "from_address": {
    "city": "Berlin",
    "country_code": "DE"
  }
}
'

import requests

url = "https://api.perform.ai/v5/shipment/"

payload = {
    "shipment_id": "SHP-2026-000002",
    "tracking_number": "00340434616780000001",
    "carrier_reference": "dhl-ecommerce-de",
    "order_id": "ORD-2026-000114",
    "tags": ["webshop"],
    "notification_email": ["jane.doe@example.com"],
    "to_address": {
        "first_name": "Jane",
        "last_name": "Doe",
        "line1": "52 Bread Street",
        "postal_code": "049145",
        "city": "Singapore",
        "country_code": "SG"
    },
    "from_address": {
        "city": "Berlin",
        "country_code": "DE"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    shipment_id: 'SHP-2026-000002',
    tracking_number: '00340434616780000001',
    carrier_reference: 'dhl-ecommerce-de',
    order_id: 'ORD-2026-000114',
    tags: ['webshop'],
    notification_email: ['jane.doe@example.com'],
    to_address: {
      first_name: 'Jane',
      last_name: 'Doe',
      line1: '52 Bread Street',
      postal_code: '049145',
      city: 'Singapore',
      country_code: 'SG'
    },
    from_address: {city: 'Berlin', country_code: 'DE'}
  })
};

fetch('https://api.perform.ai/v5/shipment/', 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.perform.ai/v5/shipment/",
  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([
    'shipment_id' => 'SHP-2026-000002',
    'tracking_number' => '00340434616780000001',
    'carrier_reference' => 'dhl-ecommerce-de',
    'order_id' => 'ORD-2026-000114',
    'tags' => [
        'webshop'
    ],
    'notification_email' => [
        'jane.doe@example.com'
    ],
    'to_address' => [
        'first_name' => 'Jane',
        'last_name' => 'Doe',
        'line1' => '52 Bread Street',
        'postal_code' => '049145',
        'city' => 'Singapore',
        'country_code' => 'SG'
    ],
    'from_address' => [
        'city' => 'Berlin',
        'country_code' => 'DE'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.perform.ai/v5/shipment/"

	payload := strings.NewReader("{\n  \"shipment_id\": \"SHP-2026-000002\",\n  \"tracking_number\": \"00340434616780000001\",\n  \"carrier_reference\": \"dhl-ecommerce-de\",\n  \"order_id\": \"ORD-2026-000114\",\n  \"tags\": [\n    \"webshop\"\n  ],\n  \"notification_email\": [\n    \"jane.doe@example.com\"\n  ],\n  \"to_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"line1\": \"52 Bread Street\",\n    \"postal_code\": \"049145\",\n    \"city\": \"Singapore\",\n    \"country_code\": \"SG\"\n  },\n  \"from_address\": {\n    \"city\": \"Berlin\",\n    \"country_code\": \"DE\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.perform.ai/v5/shipment/")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"shipment_id\": \"SHP-2026-000002\",\n  \"tracking_number\": \"00340434616780000001\",\n  \"carrier_reference\": \"dhl-ecommerce-de\",\n  \"order_id\": \"ORD-2026-000114\",\n  \"tags\": [\n    \"webshop\"\n  ],\n  \"notification_email\": [\n    \"jane.doe@example.com\"\n  ],\n  \"to_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"line1\": \"52 Bread Street\",\n    \"postal_code\": \"049145\",\n    \"city\": \"Singapore\",\n    \"country_code\": \"SG\"\n  },\n  \"from_address\": {\n    \"city\": \"Berlin\",\n    \"country_code\": \"DE\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.perform.ai/v5/shipment/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"shipment_id\": \"SHP-2026-000002\",\n  \"tracking_number\": \"00340434616780000001\",\n  \"carrier_reference\": \"dhl-ecommerce-de\",\n  \"order_id\": \"ORD-2026-000114\",\n  \"tags\": [\n    \"webshop\"\n  ],\n  \"notification_email\": [\n    \"jane.doe@example.com\"\n  ],\n  \"to_address\": {\n    \"first_name\": \"Jane\",\n    \"last_name\": \"Doe\",\n    \"line1\": \"52 Bread Street\",\n    \"postal_code\": \"049145\",\n    \"city\": \"Singapore\",\n    \"country_code\": \"SG\"\n  },\n  \"from_address\": {\n    \"city\": \"Berlin\",\n    \"country_code\": \"DE\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "api_response": "200",
  "data": {
    "shipment_uuid": "5b8ed503-20d2-46cf-8675-ce77a059f691",
    "order_uuid": "a0144751-6530-4135-8d73-f258a28ba27d",
    "documents": [],
    "created_date": "2026-09-19T03:26:29+00:00"
  }
}

Overview

Authentication

Shipments

Booking

Documents

PUDO locations

Carrier configurations

Events

Returns

Webhooks

Checkout

Create Shipment

Authorizations

Body

Response