--- title: "Orbit Partner Organisations as Carriers" description: "How to book another organisation that works in Orbit as your integrated carrier: what the partner prepares, how to set up the carrier, and which statuses, proofs, documents and locations come back." url: "https://support.pr-4.orbit.do/en/advanced-features/orbit-partner-carriers" locale: "en" lastReviewed: "2026-09-22" --- # Orbit Partner Organisations as Carriers How to book another organisation that works in Orbit as your integrated carrier: what the partner prepares, how to set up the carrier, and which statuses, proofs, documents and locations come back. > **Note:** You can book another organisation that works in Orbit as an integrated carrier. Assigning a `Tour` to that carrier creates a matching order in the partner's Orbit, and statuses, proofs, documents and the live location come back to your `Tour` automatically. ## Overview Many transport companies subcontract part of their work to partners. When that partner also runs its operations in Orbit, the two organisations can connect directly. You keep planning and selling the transport in your own Orbit. The partner receives the work as an ordinary order from a customer, plans it with its own drivers and vehicles, and executes it in Orbit Cockpit. Nobody copies data between the two systems by hand. For you, the partner behaves like any other [integrated carrier](https://support.pr-4.orbit.do/en/advanced-features/integrated-carriers): you assign it on the `Tour`, and the `Tour` moves on its own as the partner works. For the partner, you are a `Shipper` that books orders through the Orbit API. **Key highlights:** * **Tours with several stops:** a `Tour` with up to 50 stops and 40 `Shipments` goes to the partner as one order, in your stop order * **Status per shipment:** the partner's pickups, deliveries and failed deliveries update each of your `Shipments` and `Loads`, including arrival and departure times * **Proofs and documents in both directions:** your carrier-visible documents go to the partner, and the partner's proofs and shipper-visible documents come back to you * **Live location:** the position of the partner's vehicle appears on your `Tour` while it runs * **You stay the one who completes:** the partner's own review never completes your `Tour`; you review and complete it yourself ## Two organisations, two roles This article uses two names for the two sides of the connection: * **You, the booking organisation:** you own the customer order and the `Tour`, and you assign the partner as the carrier. * **The partner organisation:** it executes the transport. In its Orbit, your bookings arrive as orders from a `Shipper` that represents you. The partner prepares a few things first, and then you set up the carrier. Both steps happen in Orbit MissionControl. ## What the partner prepares The partner performs these steps in its own Orbit MissionControl and sends you the results: 1. Create a `Shipper` that represents your organisation. Every order you book arrives with this `Shipper` as the customer. Its id is the last part of the address of the shipper's page. 2. Optionally, create a team and a user within that `Shipper`. The user appears as the contact on every booked order. 3. Choose the region in which your `Shipments` are created, and note its short region code, for example `berlin`. 4. Open **Settings** > **API-Keys**, select **Create API-Key**, and give the key a name that identifies you, for example `ACME Ltd`. The partner sees every action you take under this name. 5. Send you the API key, the shipper id, the region code, and the team and user ids if they were created. An API key gives access to the partner's whole organisation in Orbit. The partner should create a separate key for each booking organisation and never share a key it uses for anything else. To end the connection, the partner deletes the key. ## Setting up the carrier You set up the partner in Orbit MissionControl, like any other integrated carrier: 1. Create a `Carrier` and turn on the **Integrated Carrier** switch at the end of the form. 2. As **Provider**, choose **Orbit (partner organization)**. 3. Keep the prefilled **Partner API address**. Change it only if your partner tells you that it works on a different Orbit installation. 4. Enter the **Partner API key**. 5. Under **Your identity at the partner**, enter the **Region at the partner** and **Your shipper id at the partner**. If the partner gave you a team or a user, enter them in **Team at the partner (optional)** and **User at the partner (optional)**. 6. Select **Test Connection**. 7. Save the carrier. **Test Connection** checks every value against the partner's Orbit. On success, it names the organisation you connected to. On failure, it names the value that is wrong: | Message | What to do | | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | The counterparty rejected the API key. | Ask the partner for a valid key. The key may be mistyped or deleted. | | This API key belongs to your own organization. | You entered one of your own keys. Use the key the partner created for you. | | The counterparty knows no shipper with the configured id. | Check the shipper id with the partner. The same check exists for the team and the user. | | The counterparty has no region "…". Available: … | Choose one of the listed region codes together with the partner. | | The counterparty endpoint did not answer like an Orbit external API. | Restore the prefilled **Partner API address**. | After you save, the carrier's detail page shows which organisation you are connected to and the name of the key. Saving also registers the carrier with the partner, so the partner's Orbit reports every change on your `Shipments` back to you. The partner sees this entry in **Settings** > **Webhooks** under the name `Orbit carrier integration`, followed by the key name, and must not delete it. If you change the **Partner API address** later, enter the API key again. Orbit sends a stored key only to the address it was entered for. ## Booking a tour with the partner You assign the partner from the `Tour` detail page in Orbit MissionControl, as you would any other carrier. Orbit immediately creates one order in the partner's Orbit: * The order carries your tour name as its name and as the customer reference, and your `Shipper` at the partner as the customer. * Each of your `Shipments` becomes one `Shipment` at the partner, with its addresses, time windows, `Loads`, extras, public comment and proof requirements. * The partner receives a `Tour` in your stop order. Stops you combined arrive combined. * Internal comments, custom properties and the vehicle class stay with you. The partner chooses its own vehicles. The **Carrier Integration** panel on your `Tour` shows the partner's order id as the **Reference**. Quote it when you talk to the partner about the booking. The partner decides who drives. It can assign the `Tour` to its own drivers, and it can split or combine the work with other tours. Your `Tour` keeps its own stops either way. Orbit rejects a `Tour` with more than 50 stops or more than 40 `Shipments` before it contacts the partner. Every `Load` needs a load type and its dimensions and weight. ## What comes back to your tour The partner's Orbit reports each change within seconds. As a safety net, Orbit also checks every booking at the partner every 15 minutes. ### Status | The partner's driver… | …and your Tour | | ---------------------------------------- | ------------------------------------------------------------------------------- | | drives to or arrives at the first pickup | The `Tour` goes to `Running`. | | leaves a pickup | The `Shipment` is on its way to the dropoff, and its `Loads` are `Loaded`. | | delivers a shipment | The `Shipment` is `Delivered`, with the result for each `Load` and any remarks. | | reports a failed delivery | The `Shipment` is `Failed`, with the reason. | | finishes the last shipment | The `Tour` goes to `Review Required`. | Arrival and departure times at each stop come from the partner's driver. A `Load` that the partner brought back or reported as damaged shows as not unloaded, with an exception. Every update appears in the tour's timeline as **Status Update from Carrier**. Select **Show Carrier Message** to read what the partner reported for each `Shipment`. An arrival sometimes appears only together with the departure from the same stop. The times are still exact. ### Proofs and documents * **Proofs** that the partner's driver captures, such as signatures and photos, always come back and land at the matching stop of your `Tour`. They follow the same visibility rules as proofs your own drivers capture. * **Other documents** come back only if the partner makes them visible to shippers. * **Your documents** go to the partner if they are visible to carriers. Orbit sends them right after booking and again whenever you add one while the booking is active. Tour documents go to every `Shipment` at the partner, and stop documents go to the `Shipments` at that stop. Files larger than 25 MB are not transferred in either direction. Deleting a document, or uploading a new version of one that was already sent, does not change the copy on the other side. ### Live location While your `Tour` is `Running`, Orbit reads the position of the partner's vehicle every minute and shows it on your `Tour`, including the map and the live tracking your shippers see. This works when the partner has assigned a vehicle with a tracking device to its `Tour`. The timeline records **Carrier Live Location Connected** once the first position arrives. ## Changing or removing a booking **Editing a booked tour.** Orbit does not change the order at the partner after booking. When you edit data the partner already received, the **Carrier Integration** panel shows **Update Pending at Carrier**. To send the change, remove the carrier and assign it again: the partner then receives a fresh order. Select **Acknowledge** instead if the change does not matter to the partner or you told the partner yourself. **Removing the carrier.** Removing the partner from the `Tour` cancels the whole order at the partner. If the partner's Orbit cannot confirm the cancellation, the carrier stays assigned and Orbit shows **Booking Could Not Be Cancelled**. Trying again is safe. **When the partner cancels.** If the partner deletes or cancels one of your `Shipments`, that `Shipment` is flagged in the panel and the timeline, and you decide how to continue. If the partner cancels every `Shipment`, the panel shows the booking as cancelled. Your `Tour` stays as it is until you remove the carrier or cancel the `Tour`. **When a booking has no clear answer.** If the partner's Orbit does not answer in time, Orbit cannot tell whether the order exists. Ask the partner to look for an order with your tour name as the customer reference before you try again. A duplicate order at the partner can simply be cancelled there. ## Example ACME Ltd in Lyon sells a same-day delivery of bicycle parts from its warehouse to four shops across Paris. ACME does not run vans in Paris, so Mohammad, an operator at ACME, assigns the `Tour` to Spaceport Shipping Co., a courier partner that also works in Orbit. Within seconds, Spaceport's dispatcher sees an order from the `Shipper` ACME Ltd with four `Shipments` and a `Tour` in the right stop order, and assigns it to a driver. The packing lists ACME attached arrive with the order. As the driver works through the stops in Orbit Cockpit, Mohammad's `Tour` moves to `Running`, each shop delivery appears with its signature, and ACME's customers follow the van on the live map. When the last shop signs, the `Tour` waits in `Review Required`, and Mohammad completes it. ## Technical details The connection uses the regular Orbit API on both sides. The booking creates an order with the partner's `Shipper` as customer, the updates travel as a webhook for your `Shipments`, and documents move through the document endpoints. See the [Orbit API Reference](https://orbit-api.readme.io) for the endpoints and schemas. ## FAQ **Q: Does the partner need to do anything special with my orders?** No. Your bookings arrive as ordinary orders from a `Shipper`. The partner plans and executes them like any other order. **Q: Does the partner's price come back to my tour?** No. Agree on prices with the partner directly. Your `Tour` keeps the price you calculated. **Q: What happens if the partner completes the tour in its own Orbit?** Nothing on your side. Your `Tour` goes to `Review Required` once every `Shipment` is delivered or failed, and you complete it yourself. **Q: Can the partner see my other data?** The partner receives only what you book with it, plus the documents on those tours that are visible to carriers. Your internal comments and custom properties stay with you. **Q: Can I use the same partner for several regions?** Each carrier sends its `Shipments` to one region at the partner. Create one carrier per region, each with the matching region code. **Q: How do we end the connection?** Remove the partner from all open tours first, so the orders at the partner are cancelled. The partner then deletes the API key it created for you.