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.
Was this article helpful?
Did not find your answer?
Ask Luna, or write to our support team.
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.
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:
Tour with up to 50 stops and 40 Shipments goes to the partner as one order, in your stop orderShipments and Loads, including arrival and departure timesTour while it runsTour; you review and complete it yourselfTour's line items can go to the partner at booking, and the partner's later price changes can come back to your TourThis article uses two names for the two sides of the connection:
Tour, and you assign the partner as the carrier.Shipper that represents you.The partner prepares a few things first, and then you set up the carrier. Both steps happen in Orbit MissionControl.
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. The key is shown once, in the dialog after Create: copy it before selecting I have saved the key. See API keys.
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.
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).
Review the settings under Settings and Prices. They are described in Carrier settings below.
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, 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.
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.
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. |
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.
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:
Shipper at the partner as the customer.Shipments becomes one Shipment at the partner, with its addresses, time windows, Loads, extras, public comment and proof requirements.Tour in your stop order. Stops you combined arrive combined.Tour's line items, each with its own VAT rate. Otherwise the order has no price.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.
The partner's Orbit reports each change within seconds. As a safety net, Orbit also checks every booking at the partner every 15 minutes.
| 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.
Tour. They follow the same visibility rules as proofs your own drivers capture.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.
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.
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.
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.
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:
Tour detail page, the price shows the price source from carrier and a lock after the amount.Tour, the note offers Set Price Yourself.To take the price of one Tour back from the partner:
On the Tour detail page in Orbit MissionControl, hover over the price.
Select Set Price Yourself.
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.
Tour ends the booking and the takeover. The line items stay as they are.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 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. 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:
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.
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.
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.
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 for the endpoints and schemas.
The Orbit API offers the carrier settings and setting the price yourself as well:
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": "<task template id>" }. 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.detach-carrier-price sets the price of one Tour yourself, like Set Price Yourself.detach-carrier-price action.AI assistants connected to Orbit can do both, under your login and permissions.
No. Your bookings arrive as ordinary orders from a Shipper. The partner plans and executes them like any other order.
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.
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.
Nothing on your side. Your Tour goes to Review Required once every Shipment is delivered or failed, and you complete it yourself.
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.
Each carrier sends its Shipments to one region at the partner. Create one carrier per region, each with the matching region code.
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.