Skip to main content
Available to all Platform customers.

​
Summary

Carrier Integration is how Perform.AI collects tracking data from each carrier you ship with, standardises it into one event vocabulary and one shipment status, and, where you use Logistics, books shipments and provisions labels with the same carriers. Perform.AI builds and maintains the carrier connections; you configure which carriers your account uses and the references your shipments carry.

​
Who it’s for

Operations and IT teams whose carrier mix spans more than one carrier, market or 3PL, and who need every carrier’s updates to mean the same thing. It answers “do you cover our carriers”, “why does this carrier’s data look different” and “what happens when we add a carrier”.

​
Key benefits

  • You do not build or maintain carrier integrations. Perform.AI connects to each carrier by whichever method that carrier supports and keeps the connection working when the carrier changes its interface.
  • More than one way in, chosen per carrier. Tracking data is collected through the carrier’s public tracking and API, through the carrier’s API with your own credentials, through SFTP file exchange, or through webhooks the carrier sends. A carrier with no API, or one that will not issue credentials, is still covered.
  • Every carrier speaks one language. Raw carrier events are mapped to a standard event key, phase and location before anything reads them, so “Picked up” at one carrier and “Origin scan” at another become the same event.
  • Status is derived, not copied. A shipment’s status is recomputed from its mapped events, so a delay or an exception means the same thing on every carrier.
  • One record serves every surface. The Tracking Page, Delivery Notifications, Shipment Overview, the delivery date and your reporting all read the same standardised shipment, so they never show different states.

​
How it works

​
Carrier configurations

Before you upload shipments, configure each carrier under Settings > Carriers. A configuration pairs a carrier from the Perform.AI carrier catalogue with a carrier reference: a unique ID you choose, which you then send on every shipment as carrier_reference. The same references are what Create Shipment and Create Booking expect, and the carrier_id values of your configured carriers are what List Shipments and the PUDO location search filter on.

​
Tracking integrations

Perform.AI supports two kinds of tracking integration with a carrier. Setting up a private integration is work on the Perform.AI side with inputs from you and the carrier: the carrier provides documentation and credentials or test messages, Perform.AI builds the parser and configures the connection, and the carrier starts sending live data. If a carrier offers a method other than these three, share its documentation with your account team, who will assess feasibility and timeline. A new carrier integration, or an upgrade from public to private, may involve development work; your account team confirms what applies to your agreement. Where more than one source exists for a carrier, one can fall back to another, so a single feed going quiet does not leave you without data.

​
Standardised events and status

Each raw carrier event is mapped to a standard event with a key, a display name, a phase and a state. Phases follow the journey in order: order events, fulfillment events, pre-alert, pick-up, transit, customs, out for delivery, delivery, return to sender, and others. Each event is regular, delay or exception. Mapped events, with their standardised location, are what appear in Parcel Details, on the Tracking Page, in notifications and in webhooks; an event the carrier sends that has not been mapped yet is shown with its original description and no event key. From the mapped events Perform.AI recomputes the shipment’s status. Because the number and type of events vary by carrier, a mapping is not always the best fit for every case. If you see an event that could be mapped better, ask your account team for a mapping review; Perform.AI adjusts the mapping when it better reflects the shipment journey. Tracking events in Perform.AI can differ from the carrier’s own tracking site. The number of events, their timestamps and their descriptions depend on what the carrier shares through the integration in place, and private integrations often carry more detail than the public page.

​
Booking and labels

Carrier configurations also carry a Booking status, which tells you whether the carrier can be booked through Perform.AI. A booking connection needs the credentials your carrier issued to you and a warehouse, which is also the return address printed on the label. Warehouses are set up once and reused across connections. Once connected, Create Booking books an Open Shipment with the carrier and returns the carrier tracking number, the booking status and the label documents; labels are available as PDF, ZPL or PNG. Booking is part of Logistics and is enabled per subscription.

​
Reassigning a carrier

A shipment uploaded without a carrier reference, or with the wrong one, may not receive tracking updates. While the shipment is Pending or Expired, you can change its carrier from Parcel Details. Once a shipment has tracking events, or for bulk reassignments, contact your account team.

​
Set up in the portal

​
Add a carrier

  1. Go to Settings > Carriers and select Add Carrier.
  2. Select the Carrier Name and enter a Carrier Reference.
  3. Save. The reference appears in the list as Active and can be used on shipment uploads immediately.

​
Connect a carrier for booking

  1. Go to Settings > Carriers and open a carrier whose Booking status is Active.
  2. Select Add Booking.
  3. Enter the connection details and choose the Warehouse. Set your warehouses up beforehand to reuse them across carriers.
  4. Enter the credentials your carrier assigned to you and select Connect.
For a carrier whose Booking status is Not Supported or Draft, contact your account team. Each carrier needs certain details from you; once they are provided and the configuration is confirmed, the status moves to Draft and you can activate the connection.

​
Reassign a shipment’s carrier

  1. Go to Shipment Overview and open the shipment. It must be Pending or Expired.
  2. In Parcel Details, open the carrier dropdown and select the correct carrier. It becomes the Main Carrier.

​
Use via API and MCP

  • Guides: Carrier configurations, Create Booking, Retrieve labels.
  • API reference: Retrieve Carrier Configurations lists the carriers configured in Settings > Carriers with their carrier_reference and carrier_id values, up to 2,000 per page.
  • MCP tools: list_carriers searches the Perform.AI carrier catalogue, what Perform.AI supports independent of your organization, by country, tracking integration type, retrievable data points, booking type and collection-point support; get_carrier returns one catalogue record; list_carrier_configs returns the carriers your organization has configured with name, code, reference, status and outbound or return definition. Documented on the MCP tools page.

​
FAQ

​
Do you support our carriers?

Check your carrier list against the carrier catalogue: in the portal under Settings > Carriers > Add Carrier, or by asking your own assistant through the MCP server. Anything not listed, raise with your account team.

​
What is a carrier reference and why does it matter?

It is the unique ID you give a carrier in your account and send on every shipment. With it, the shipment is assigned to its carrier at once and tracking starts immediately. Without it, Perform.AI has to work out the carrier first, which takes longer and can go wrong.

​
Our carrier will not give us API credentials. Can you still track it?

Yes. Every supported carrier has a public integration by default, and a private integration can also run over webhooks the carrier sends or an SFTP folder, not only an API. Share what the carrier offers with your account team.

​
Why does a shipment show a different status in Perform.AI than on the carrier site?

Perform.AI derives the status from the mapped events rather than copying the carrier’s wording, so the same state means the same thing across carriers. If an event looks wrongly mapped, ask for a mapping review.

​
What happens when we add a carrier or a market?

Add the carrier and a reference under Settings > Carriers. If the carrier is already in the catalogue, tracking starts with the default public integration. For a private integration or booking, your account team confirms the timeline.

​
Troubleshooting