Quickstart

This guide takes you from credentials to a tracked shipment in three API calls.

Before you start

Get your Client ID and Client Secret from Integrations > API in your Perform.AI account. If no credentials exist yet, select Request Credentials. See the authentication guide for details.

Generate a Bearer token

Send your credentials as HTTP Basic authentication with a form-encoded body:

curl --request POST \
  --url https://api.perform.ai/auth/oauth/token/ \
  --header "Authorization: Basic $(echo -n 'your_client_id:your_client_secret' | base64)" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials'

The response contains your token, valid for 1 hour:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Create a shipment

Only shipment_id — your own unique identifier — is required to create a shipment:

curl --request POST \
  --url https://api.perform.ai/v5/shipment/ \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "shipment_id": "SHP-2026-000001"
  }'

A successful response returns the identifiers Perform.AI assigned:

{
  "api_response": "200",
  "data": {
    "shipment_uuid": "0d9b917b-74f7-4b0e-a2d6-6a1b7f3f2f11",
    "order_uuid": null,
    "documents": [],
    "created_date": "2026-09-18T08:30:00+00:00"
  }
}

shipment_id must be unique across your account and cannot be changed after creation, so use a stable identifier from your own system.

To have Perform.AI track the shipment with a carrier, also provide tracking_number and carrier_reference. The carrier_reference must first be configured under Settings > Carriers in your account — an unconfigured value blocks creation:

{
  "shipment_id": "SHP-2026-000002",
  "tracking_number": "00340434616780000001",
  "carrier_reference": "dhl-ecommerce-de"
}

Retrieve the shipment

Fetch the shipment you created, by your ID or the returned UUID:

curl --request GET \
  --url 'https://api.perform.ai/v5/shipment/details/?shipment_id=SHP-2026-000002' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

The response includes the shipment’s status, carrier, and an all_events array that fills with tracking events as Perform.AI retrieves them from the carrier.

Next steps

Create shipments in full

Addresses, line items, costs, documents, and notification settings.

Receive webhooks

Push shipment updates to your systems instead of polling.

Search shipments

Filter and paginate across your shipment data.

API reference

Every endpoint, parameter, and response, with a live playground.

Get Started

Core Concepts

API Essentials

Shipments

Booking & Labels

Returns

Events

Webhooks

Checkout

Customer Experience

Integrations

Resources

Before you start

Next steps

Create shipments in full

Receive webhooks

Search shipments

API reference

​Before you start

​Next steps

Create shipments in full

Receive webhooks

Search shipments

API reference

Before you start

Next steps