> ## 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. # Multi-Carrier Shipping > Multi-Carrier Shipping books shipments with your connected carriers from Booking Overview or the API and returns labels and tracking numbers. **Available to all Logistics customers.** ## Summary Multi-Carrier Shipping books your shipments with the carriers configured in your account and returns the tracking number and shipping label, from the Booking Overview in the portal or through the Booking API. Every booking moves through the same statuses whichever carrier it uses, and failed bookings show the error so you can fix the data and try again. ## Who it’s for Logistics and fulfilment teams that ship with several carriers and want one place to assign a carrier, book, print labels and resolve failures, and engineering teams that want one booking integration instead of one per carrier. ## Key benefits * **One flow for every carrier.** Carrier credentials and shipping preferences are set once per carrier reference; bookings then use the same statuses and actions for all of them. * **Book from the portal or the API.** Operations teams book and re-book from Booking Overview, including in bulk; systems call the Booking API with a shipment ID. * **Failures are actionable.** A failed booking shows the error type, error code and the fields that need correcting; fix them and book again. * **Labels in one place.** Download labels from Booking Overview or retrieve them with the labels API. * **Status you can filter on.** Booking Overview tracks Unassigned, Assigned, Booked, Shipped and Failed, and Shipment Overview filters shipments by booking outcome. ## How it works ### Carrier set-up Bookings use a **carrier reference**: a configured carrier account under **Settings** > **Carriers**. Each carrier in the list shows a booking status: | Booking status | Meaning | | - | - | | Active | The booking integration is ready. Open the carrier, select **Add Booking** and connect your credentials. | | Draft | Perform.AI has completed the backend configuration for your account; you can activate the connection. | | Not Supported | The booking integration is not ready for instant connection. Request it through Customer Success. | A carrier reference holds the booking type (outbound or return), the shipping service, the shipping label type, the warehouse address and the carrier account credentials. Warehouses are set up once and reused across carrier references; the warehouse you choose is the return address printed on the label. Credentials are issued by the carrier; Perform.AI does not hold them for you. The same carrier can appear several times with different references, for example two accounts with the same carrier. ### Booking statuses A shipment needs to exist as an Open Shipment before it can be booked: a shipment without a tracking number, created through the API, file upload or SFTP. Its booking status and shipment status move together: | Booking status | Shipment status | Definition | | - | - | - | | Unassigned | Open | No carrier reference, no tracking number, no booking | | Assigned | Open | Carrier reference set, no tracking number yet | | Booked | Pending | Carrier reference, tracking number and booking exist; the carrier confirmed the booking | | Shipped | Active | Tracking number exists and the parcel has moved | | Failed | Open | A booking attempt failed; no tracking number | ### Actions by status | Status | Available actions | | - | - | | Unassigned | Assign Carrier, Archive | | Assigned | Assign Carrier, Book, Archive | | Booked | Download Label, Archive | | Shipped | Download Label, Archive | | Failed | Assign Carrier, Book, Archive | When you select shipments with mixed statuses, only the actions common to all of them are enabled. Selecting Unassigned and Assigned shipments together allows Assign Carrier and Archive but not Book. ### Booking Overview **Logistics** > **Booking Overview** opens with a dashboard of the bookings created in the last 14 days and their current statuses, followed by the booking list with sortable columns: Status, Shipment ID, Carrier (Reference), Booking UUID, Tracking ID, Time Passed, Date Updated and Date Added. Select several shipments to book or archive them in bulk; a confirmation is shown before booking. Routing tags from [Auto Carrier Selection](https://developers.perform.ai/products/logistics/auto-carrier-selection.md) are available as filters. ### Booking details Clicking a shipment opens a panel with the Shipment ID, Booking UUID, tracking number, booking status and the actions for that status (Assign Carrier, Book, Download Label, Try Again). A progress tracker shows the stages Unassigned, Assigned, Booked and Shipped, and a timeline lists the booking events with timestamps: * Carrier assignment successful, or Carrier assignment failed * Booking validation failed (an internal check failed before the request reached the carrier) * Carrier booking successful, or Carrier booking failed (an error from the carrier) * Shipment has been shipped (a tracking event shows the parcel moved) For a Failed booking the panel shows the error type, the error code and the fields required for a successful booking. ### Fixing a failed booking Correct the data the error names, then book again from Booking Overview or the API: * Update the shipment through the API for the field mentioned in the error. * Update the shipment in the portal for fields that are editable there. * Adjust the carrier configuration when the error concerns the carrier account or service. If no specific error is shown, the booking integration may have a connectivity problem; contact Customer Success. ### What a bookable shipment needs The shipment must carry a valid `to_address`: name, address lines, postal code, city or region and country. Some carriers also require fields such as product weight or unit; your account team can provide the list of mandatory shipment and line item fields per carrier before you integrate. A `carrier_reference` is best set when the shipment is created; it can also be assigned later in Booking Overview or passed in the booking request. ### After booking A successful booking sets the tracking number on the shipment and moves it to Booked. In Shipment Overview, the **Booking** filter has three options: No Booking, Successful and Unsuccessful. Labels are downloaded from Booking Overview or the booking panel, or retrieved through the API in the formats the carrier returns, such as PDF, ZPL or PNG. ## Set up in the portal Connect a carrier: 1. Go to **Settings** > **Carriers** and open a carrier whose booking status is Active. 2. Select **Add Booking**. 3. Fill in the connection details, choose the warehouse and enter the account credentials assigned by the carrier. 4. Select **Connect**. A message confirms the connection. Book shipments: 1. Go to **Logistics** > **Booking Overview**. 2. For Unassigned shipments, select them and choose **Assign Carrier**. 3. Select Assigned or Failed shipments and choose **Book**, then confirm. 4. Once the status is Booked, select **Download Label**. > [!TIP] > > Set up all your warehouse addresses before connecting carriers; each booking connection picks one from the list. > [!NOTE] > > For a carrier marked Not Supported, contact Customer Support through the live chat. You will receive a list of the mandatory details for that carrier; once the configuration is done, the status changes to Draft and you can activate the connection. ## Use via API and MCP * [Create a Booking](https://developers.perform.ai/guides/create-booking.md) ([`POST /v5/booking/`](https://developers.perform.ai/api-reference/v5/booking/create-booking)): book an Open Shipment by `shipment_id` or `shipment_uuid`, with an optional `carrier_reference`. * [Retrieve shipping labels](https://developers.perform.ai/guides/retrieve-labels.md) ([`GET /v5/shipments/documents/labels/`](https://developers.perform.ai/api-reference/v5/documents/list-labels)): fetch the labels of booked shipments. * [Retrieve carrier configurations](https://developers.perform.ai/guides/carrier-configurations.md) ([`GET /v5/carrier-configs/`](https://developers.perform.ai/api-reference/v5/carrier-configurations/retrieve-carrier-configurations)): list the carrier references configured in your account. From an AI assistant connected through the [Perform.AI MCP](https://developers.perform.ai/mcp/overview.md), `list_bookings`, `get_booking_detail` and `get_booking_metrics` read your bookings and their statuses, and `list_carrier_configs` lists the carriers configured for your organization. See [Tools](https://developers.perform.ai/mcp/tools.md). ## FAQ ### Do I have to set the carrier when I create the shipment? It is recommended, because the booking then needs only the shipment ID. You can also assign the carrier later in Booking Overview, pass `carrier_reference` in the booking request, or let [Auto Carrier Selection](https://developers.perform.ai/products/logistics/auto-carrier-selection.md) assign it. ### My carrier is listed as Not Supported. What do I do? Request the booking integration through Customer Support in the live chat. You will be asked for the carrier credentials and details the integration needs; when the backend configuration is done the status changes to Draft and you activate the connection. If you have a direct contact at the carrier, share it to speed things up. ### Why did my booking fail? Either the carrier returned an error (Carrier booking failed) or an internal validation failed before the request was sent (Booking validation failed). Open the booking panel: the error section names the type, the code and the fields to correct. Fix them and book again. ### Can I book many shipments at once? Yes. Select several Assigned or Failed shipments in Booking Overview and choose **Book**. With mixed statuses, only the actions common to all selected shipments are available. ### Where do I get the label? From **Download Label** in Booking Overview or the booking panel for Booked and Shipped shipments, or through the labels API. ## Troubleshooting | Symptom | Cause | Fix | | - | - | - | | **Book** is disabled for the selection | The selection includes Unassigned, Booked or Shipped shipments | Filter to Assigned or Failed shipments and select again. | | Booking failed with required fields listed | The shipment lacks data the carrier needs, such as a postal code or weight | Update the shipment through the API or the portal and book again. | | Booking failed with no specific error | The booking integration cannot reach the carrier | Contact Customer Success. | | **Add Booking** is not available on a carrier | The carrier’s booking status is Draft or Not Supported | For Draft, activate the connection; for Not Supported, request the integration. | | The return address on labels is wrong | The warehouse chosen on the carrier reference is used as the return address | Edit the carrier reference and select the correct warehouse. | ## Related * [Auto Carrier Selection](https://developers.perform.ai/products/logistics/auto-carrier-selection.md) * [PUDO Delivery](https://developers.perform.ai/products/logistics/pudo-delivery.md) * [Carrier Integration](https://developers.perform.ai/products/platform/carrier-integration.md) * [Logistics overview](https://developers.perform.ai/products/logistics/overview.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.