Orbit Partner Organisations as Carriers

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: 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:

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.
Optionally, create a team and a user within that Shipper. The user appears as the contact on every booked order.
Choose the region in which your Shipments are created, and note its short region code, for example berlin.
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.
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:

Create a Carrier and turn on the Integrated Carrier switch at the end of the form.
As Provider, choose Orbit (partner organization).
Keep the prefilled Partner API address. Change it only if your partner tells you that it works on a different Orbit installation.
Enter the Partner API key.
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).
Select Test Connection.
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 for the endpoints and schemas.

FAQ

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.

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.

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.

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.

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.

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.