> ## Documentation Index > Fetch the complete documentation index at: https://developers.perform.ai/llms.txt > Use this file to discover all available pages before exploring further. # Carrier Integration > How Perform.AI connects to carriers for tracking, booking and labels, and how carrier configurations and standard events work. **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`. | Rule | Detail | | - | - | | A reference identifies one carrier | A carrier reference cannot be used for more than one carrier. | | A carrier can have many references | There is no limit on the number of references under one carrier. Two accounts with the same carrier, for example, can be two references. | | New references are Active on creation | The reference appears in the list with the status Active and can be used for uploads at once. | | Shipments should carry the reference | A shipment uploaded with a configured `carrier_reference` is assigned to its carrier immediately and tracking starts straight away. A shipment without one has to be identified by Perform.AI first, which takes longer and can assign the wrong carrier. | 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. | Type | What it is | What to expect | | - | - | - | | Public integration | The default. Perform.AI collects tracking data from the carrier’s public tracking site or public API, without a dedicated connection. | Available for every supported carrier without setup. The timeliness, completeness and accuracy of the data depend on what the carrier publishes and are not guaranteed. | | Private integration | A dedicated connection between Perform.AI and the carrier, set up for your account. Three standard methods: the carrier’s private API, a webhook the carrier sends to a Perform.AI callback URL, or a shared SFTP folder exchanged on a schedule. | Recommended for timely and complete data. A webhook integration delivers updates close to real time and removes polling. | 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. | Status | Meaning | | - | - | | Pending | No tracking event yet. | | Expired | A Pending shipment that received no event within 10 days of its first update cycle. | | Active | At least one tracking event, not yet delivered. | | Inactive | An Active shipment with no new event for 14 days after the last one. | | Delivered | Successfully delivered or collected. | | Return | The shipment has a return-to-sender event, whether the delivery failed or the shopper initiated the return. | 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. | Booking status | Meaning | | - | - | | Active | The booking integration is ready. Add your carrier account credentials to the configuration and connect. | | Draft | Perform.AI has completed the configuration on its side; you can now activate the connection in the portal. | | Not Supported | The booking integration is not ready for instant connection. Request it through your account team. | 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](https://developers.perform.ai/products/logistics/overview.md) 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](https://developers.perform.ai/guides/carrier-configurations.md), [Create Booking](https://developers.perform.ai/guides/create-booking.md), [Retrieve labels](https://developers.perform.ai/guides/retrieve-labels.md). * API reference: [Retrieve Carrier Configurations](https://developers.perform.ai/api-reference/v5/carrier-configurations/retrieve-carrier-configurations.md) 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](https://developers.perform.ai/mcp/tools.md) 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 | Symptom | Cause | Fix | | - | - | - | | Shipment stays Pending and never receives events | No carrier reference was sent, or the reference is not configured | Add the carrier under **Settings** > **Carriers**, then reassign the shipment from Parcel Details while it is Pending or Expired. | | Shipment is assigned to the wrong carrier | A wrong or missing `carrier_reference` on upload | Reassign from Parcel Details if the shipment has no events yet; otherwise contact your account team. | | Tracking is slower or less detailed than on the carrier site | The carrier runs on the default public integration | Ask your account team about a private integration (API, webhook or SFTP) for that carrier. | | An event shows the carrier’s original text and no event key | The carrier sent an event that has not been mapped yet | Request a mapping review through your account team. | | **Add Booking** is not available for a carrier | The carrier’s Booking status is Not Supported or Draft | Request the booking integration through your account team; once the status is Draft, activate the connection. | ## Related * [Data Integration](https://developers.perform.ai/products/platform/data-integration.md) * [Multi-Carrier Shipping](https://developers.perform.ai/products/logistics/multi-carrier-shipping.md) * [Shipment Overview](https://developers.perform.ai/products/post-purchase/shipment-overview.md) * [Platform overview](https://developers.perform.ai/products/platform/overview.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.