--- 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, which statuses, proofs, documents and locations come back, and how the price can travel between you." url: "https://support.pr-5.orbit.do/en/advanced-features/orbit-partner-carriers" locale: "en" lastReviewed: "2026-10-26" --- # 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, which statuses, proofs, documents and locations come back, and how the price can travel between you. > **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-5.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 * **Prices, when you want them:** your `Tour`'s line items can go to the partner at booking, and the partner's later price changes can come back to your `Tour` ## 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. The key is shown once, in the dialog after **Create**: copy it before selecting **I have saved the key**. See [API keys](https://support.pr-5.orbit.do/en/advanced-features/api-keys). 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. Review the settings under **Settings** and **Prices**. They are described in [Carrier settings](#carrier-settings) below. 7. Select **Test Connection**. 8. 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, and, when the carrier takes over price changes, every change to the orders you booked. 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. ## Carrier settings The **Integration** section of the carrier holds four settings. You choose them when you create the carrier and can change them at any time on the carrier's detail page. **Tours at the Partner** and **Send Price at Booking** apply to the tours you assign afterwards. How **Take Over Price Changes** acts on booked tours is described in [Prices](#prices). Under **Settings**: | Setting | Options | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tours at the Partner** | **Original tour** (default): the partner receives one tour with the same stop sequence as the original tour. **No tour**: the partner receives the shipments unrouted, without a tour, and plans them itself. **One tour per shipment**: the partner receives one separate tour for each shipment. | Under **Prices**: | Setting | Options | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Send Price at Booking** | **Don't Send** (default): the partner receives the order without a price. **Send the Tour's Line Items**: the partner receives the tour's line items as the order's starting price. | | **Take Over Price Changes** | **Don't Take Over** (default): the partner's price changes don't reach the tour. **Take Over Continuously**: when the partner changes the order's line items, the tour takes over all of them and locks them. | | **Task on Price Change** | Off (default), or on with a task template: opens a task from this template for every price change that is taken over. See [A task for each price change](#a-task-for-each-price-change). | The two price settings are independent. You can send the price and keep your own, or book without a price and let the partner set it. Changing **Take Over Price Changes** also updates the registration at the partner, so the partner's Orbit must be reachable when you save. If it is not, the change is not saved; try again later. ## 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. * With **Tours at the Partner** set to **Original tour**, the partner receives a `Tour` in your stop order. Stops you combined arrive combined. * With **Send Price at Booking** set to **Send the Tour's Line Items**, the order carries your `Tour`'s line items, each with its own VAT rate. Otherwise the order has no price. * 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. ## Prices The price moves in one direction at a time. At booking, it can go from your `Tour` to the partner. After booking, it can only come back from the partner to your `Tour`. Your own price changes after booking never reach the partner. ### Taking over the partner's price changes When **Take Over Price Changes** is set to **Take Over Continuously** at the time you assign the partner, the price of the `Tour` comes from the partner from the moment the booking succeeds. Your line items stay as they are until the partner changes the price of the order. Whenever the partner changes the line items of the order, for example by adding waiting time or a tail-lift surcharge, your `Tour` takes over all of the partner's line items within seconds. Each line keeps its own VAT rate. Price changes arrive only through the partner's notifications: the check every 15 minutes covers statuses, not prices. The timeline records **Line Items Taken Over from Carrier** with the partner as the one who made the change. Your `Tour` changes only when the content differs: a line's name, quantity, unit price or VAT rate, a line added or removed, or a new order of the lines that changes the total (a percentage surcharge is calculated on the lines above it). A status change at the partner, the same lines in a different order with the same total, or the line items you sent at booking change nothing. An order without any line items never replaces your price: if the partner removes every line, set the price yourself. The takeover continues after your `Tour` is completed, for as long as the partner stays assigned. Only the price of the `Tour` changes. The price of your customer's `Order` is never touched. ### What you see on the tour While the price comes from the partner, nobody can edit the `Tour`'s line items or price, in Orbit MissionControl, through the Orbit API or through an AI assistant: * On the `Tour` detail page, the price shows the price source **from carrier** and a lock after the amount. * Neither **Edit Price** nor **Recalculate** is offered next to the price. * Hovering over the price shows the line items and a note that they come from the partner and are taken over whenever the partner changes them. After the first takeover, the note also says when the line items were last updated. * If you can edit the `Tour`, the note offers **Set Price Yourself**. ### Setting the price yourself To take the price of one `Tour` back from the partner: 1. On the `Tour` detail page in Orbit MissionControl, hover over the price. 2. Select **Set Price Yourself**. 3. Read the dialogue **Set the Price for This Tour Yourself?** and confirm with **Set Price Yourself**. The line items stay as they are, and you can edit them again. Price changes from the partner are no longer taken over for this `Tour`, and the partner is not told about your changes, so settle the price with the partner directly. The timeline records **Price Set Manually**. This affects only this `Tour`; other tours booked with the same partner keep taking over its price changes. ### Ending the takeover * **For one tour:** set the price yourself, as described above. * **For every tour of the carrier:** set **Take Over Price Changes** to **Don't Take Over**. The partner's price changes stop reaching your tours, and their line items can be edited again. * **By removing the carrier:** removing the partner from the `Tour` ends the booking and the takeover. The line items stay as they are. ### A task for each price change Switch on **Task on Price Change** and choose a template beside it to have someone check every price your `Tour` takes over from the partner: each taken-over price change opens a task from that template. The list offers only [task templates](https://support.pr-5.orbit.do/en/tasks/task-templates) with the trigger **Opened by a Setting**, so create one there first. The setting is not saved while it is on without a template. As long as a carrier uses a template, the template cannot be deleted or given another trigger; set it to inactive to stop the tasks. The task belongs to the `Tour`. Its name and description come from the template and can show what changed: the net total before and after the change, the difference, and the lines the partner added, removed or changed. The placeholders are listed in [Task Templates](https://support.pr-5.orbit.do/en/tasks/task-templates#price-change-placeholders). The assignee, the due date, the notifications and whether the task blocks the tour also come from the template. Each `Tour` has at most one open task from the template: * **While the task is open,** a further price change opens no second task. The task's name and description are filled in again with the latest change, and its history records **Price change from … taken over** with the net totals before and after. * **Once the task is completed or skipped,** the next price change opens a new task. Only a taken-over price change opens a task. Booking the partner, **Set Price Yourself** and removing the carrier open none. While **Task on Price Change** is off or the template is inactive or deleted, price changes are still taken over, but they open no task, and none is opened for them later. ## 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. Changes to the `Tour`'s line items are never sent to the partner and never show **Update Pending at Carrier**. **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. Cancellation costs the partner charges after that do not reach your `Tour`; settle them with the partner directly. **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`, and a price taken over from the partner stays locked until then. **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, with **Take Over Price Changes** on, for your orders, and documents move through the document endpoints. See the [Orbit API Reference](https://orbit-api.readme.io) for the endpoints and schemas. The Orbit API offers the carrier settings and setting the price yourself as well: * The carrier action `edit-integration-toggles` changes the carrier's settings and leaves the API key and the other connection details untouched. **Task on Price Change** is the setting `priceChangeTask`, with the value `{ "enabled": true, "templateId": "" }`. Orbit refuses it with a template that does not exist or has another trigger than **Opened by a Setting**, and when it is on without a template. * The tour action `detach-carrier-price` sets the price of one `Tour` yourself, like **Set Price Yourself**. * A change to a locked price is refused with an error that names the partner and the `detach-carrier-price` action. [AI assistants connected to Orbit](https://support.pr-5.orbit.do/en/advanced-features/connecting-ai-assistants-to-orbit) can do both, under your login and permissions. ## 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?** Yes, when you set **Take Over Price Changes** to **Take Over Continuously** on the carrier. Every change the partner makes to the line items of the order then replaces the line items of your `Tour`, and the price stays locked until you select **Set Price Yourself**. With **Don't Take Over**, your `Tour` keeps the price you calculated, and you agree on prices with the partner directly. **Q: Does the partner see my price changes?** No. After booking, the price only travels from the partner to you. If you set the price of a `Tour` yourself, settle it with the partner directly. **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.