# Connect Microsoft Dynamics 365 Business Central to Starshipit
URL: https://support.starshipit.com/articles/12093647173647-connect-microsoft-dynamics-365-business-central-to-starshipit
Canonical: https://support.starshipit.com/articles/12093647173647-connect-microsoft-dynamics-365-business-central-to-starshipit
Markdown: https://support.starshipit.com/articles/12093647173647-connect-microsoft-dynamics-365-business-central-to-starshipit.md
Updated: 2026-11-09

> For the complete documentation index, see [llms.txt](https://support.starshipit.com/llms.txt).

> Connect Microsoft Dynamics 365 Business Central to import sales documents and write back tracking information.

Connect Starshipit to Microsoft Dynamics 365 Business Central to import sales orders or sales invoices and write back package tracking information.

:::important
This connector is specifically for **Microsoft Dynamics 365 Business Central**. It does not connect Starshipit to every product in the Dynamics 365 suite.
:::

## Before you begin

You need:

- A Microsoft Dynamics 365 Business Central account with admin access to authorise Starshipit.
- An environment and company in Business Central to import from.
- The [Starshipit Integration extension from Microsoft AppSource](https://marketplace.microsoft.com/en-us/product/dynamics-365-business-central/PUBID.shipitlimited1742346367585%7CAID.starshipit%7CPAPPID.37578f37-5111-40bc-ac9f-744211f27790) if you want tracking-number writeback. The extension is not used to import orders.

## Connect Business Central

1. In Starshipit, go to **Settings > Integrations**.
2. Select **Add a new integration**, then select **D365BC**.
3. Turn on **Enable Dynamics 365 Business Central**.
4. Select **Authorize**, then sign in with a Microsoft account that can approve access to Business Central.
5. Select the Business Central **Environment** and **Company** to import from.
6. Select an **Import Type**, **Bound Action**, and **Status**.
7. Select **Save**.
8. Go to your orders and select **Fetch latest orders** to test the import.

After the enabled integration is saved, Starshipit also imports matching documents automatically.

## Choose what to import

| Setting | Available options | How it works |
| --- | --- | --- |
| **Import Type** | **Sales Order**, **Sales Invoice** | Selects the standard Business Central API document to import. **Sales Order** is the default. |
| **Status** | **DRAFT**, **OPEN** | Filters the status returned by the Business Central API. **DRAFT** is the default. |
| **Bound Action** for Sales Order | **NONE**, **SHIPANDINVOICE** | **NONE** prepares the selected **Qty. to Ship** without posting. **SHIPANDINVOICE** prepares ship and invoice quantities, then requests posting for the selected units. **NONE** is the default. |
| **Bound Action** for Sales Invoice | **NONE**, **POST**, **POSTANDSEND**, **SEND** | After tracking writeback, the selected action asks Business Central to process the invoice. **NONE** is the default. |

## Import released sales orders

Business Central uses different labels for document status in its UI and its standard API:

| Business Central UI status | Standard API status | Starshipit **Status** |
| --- | --- | --- |
| **Open** | `Draft` | **DRAFT** |
| **Pending Approval** | `In Review` | Not available as a Starshipit status option |
| **Released** | `Open` | **OPEN** |
| **Pending Prepayment** | `Open` | **OPEN** |

To import released sales orders, select **Sales Order** as the **Import Type** and **OPEN** as the **Status**.

:::important
Microsoft's standard API maps both **Released** and **Pending Prepayment** sales orders to API status `Open`. Starshipit's native status filter cannot import only **Released** while excluding **Pending Prepayment**. If you need that distinction, you need a custom integration or product change.
:::

## Understand how imports and writeback work

Starshipit imports documents through Microsoft's standard [Business Central API v2.0 sales order](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_salesorder) and [sales invoice](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/api-reference/v2.0/resources/dynamics_salesinvoice) endpoints. The Starshipit Integration extension does not provide an order-import endpoint.

The extension provides a separate endpoint for tracking writeback. When an imported document is fulfilled in Starshipit, Starshipit sends the first package's tracking number to Business Central's **Package Tracking No.** field.

For Sales Orders, **NONE** and **SHIPANDINVOICE** first check the imported line links and set the selected quantities in Business Central. **NONE** leaves posting manual; **SHIPANDINVOICE** then requests shipment and invoice posting for those units. Follow [Ship Business Central sales orders in parts](/articles/1794240000001-ship-business-central-sales-orders-in-parts) for the complete workflow, remaining-order checks and recovery limits.

For Draft Sales Invoices, **POST** and **POSTANDSEND** require complete matching invoice lines and quantities. They do not provide Sales Order partial-quantity synchronisation.

Tracking writeback supports only:

- Sales Orders.
- Draft Sales Invoices.

## Choose where Address Line 2 imports

By default, Business Central **Ship-to Address Line 2** imports into Starshipit's **Suburb** field. You can map it to **Building** instead, for example when it contains a unit or building name.

1. Go to **Settings > Integrations > D365BC**.
2. Enable **Map address line 2 into the Building field** to use Building, or leave it disabled to use Suburb.
3. Select **Save**, then reopen the settings to confirm your choice.
4. Import a new eligible document with a recognisable Ship-to Address Line 2 value.
5. Open the imported order and check that the value appears in the selected field and that City still matches Business Central.

Address Line 2 goes into one of these fields, not both. If it appears in the wrong field, check the saved mapping and the source document's Ship-to fields before creating a label.

## Check the destination address mapping

Starshipit maps the destination directly from the imported document's Ship-to fields:

| Starshipit destination field | Business Central API field or rule |
| --- | --- |
| Recipient | `shipToName`; if empty, `shipToContact`; if empty, `customerName` |
| Company | `shipToName` when `shipToContact` is also present and is different from `shipToName`; otherwise blank |
| Street | `shipToAddressLine1` |
| Building / address line 2 | `shipToAddressLine2` when **Map address line 2 into the Building field** is enabled; otherwise blank |
| Suburb | `shipToAddressLine2` when that option is disabled; otherwise blank. City is not copied here when Address Line 2 is empty. |
| City | `shipToCity` |
| State | `shipToState` |
| Country | `shipToCountry` |
| Postcode | `shipToPostCode` |
| Phone | Order-level `phoneNumber` |
| Email | Order-level `email` |

Street and address values therefore come from the sales order's **Ship-to** fields. Starshipit does not perform a separate customer-card address lookup during import.

There is no configurable address-source selector. Using Sell-to, Bill-to, or custom fields requires customisation.

## Use location tags for fulfilment rules

Starshipit reads the locations on positive-quantity document lines and adds a location tag during import:

| Imported tag | Meaning |
| --- | --- |
| `location:<code>` | All relevant lines resolve to one Business Central Location Code, such as `location:AUCKLAND`. |
| `location-status:multiple` | The lines resolve to more than one Location Code. Review where the order should be fulfilled. |
| `location-status:unresolved` | Some lines have missing locations or a location could not be resolved. Check the source lines and location access in Business Central. |
| No location tag | None of the relevant lines has a location. |

To use a location for child-account allocation:

1. Import a new eligible order and check its exact location tag in Starshipit.
2. Go to **Settings > Rules** and create a rule using that **Tags** value as a condition.
3. Select the existing action to allocate the order to the intended child account. See [Allocate an order to another account](/articles/115001657023-allocate-an-order-to-another-account-child-account) for the routing setup.
4. Save the rule and import a new matching test order.
5. Confirm the order arrives in the intended account, then check a nonmatching order stays in its expected account.

A location tag identifies the source location; it does not move an order by itself. Avoid routing `multiple` or `unresolved` orders as though they have a single confirmed location. Review those orders before fulfilment.

## Verify released-order and Ship-to imports

Use a small test before relying on automatic imports:

1. In Starshipit, configure **Import Type** as **Sales Order**, **Status** as **OPEN**, and **Bound Action** as **NONE**.
2. In the selected Business Central company, create two recent sales orders with unique order numbers.
3. Leave one sales order with the Business Central UI status **Open**.
4. Override the other sales order's **Ship-to** address so it differs from the customer card, then release that order.
5. In Starshipit, select **Fetch latest orders**.
6. Confirm that the released order imports and the unreleased order does not.
7. Open the imported order and confirm that its destination matches the overridden **Ship-to** address.

If a **Pending Prepayment** order also imports, this is expected because the standard API reports it as `Open`.

## Troubleshooting

If the expected order does not import:

- Confirm the integration is enabled and authorised.
- Confirm you selected the environment and company containing the order.
- For a released sales order, confirm **Import Type** is **Sales Order** and **Status** is **OPEN**.
- Fetch the latest orders again after changing or releasing the order.
- Check the order's Ship-to fields in Business Central if the destination is unexpected.

If tracking does not write back, confirm the Starshipit Integration extension is installed and that the imported document is a Sales Order or Draft Sales Invoice. For line-link, partial-quantity or posting errors, check the original Business Central document before retrying and follow [Recover from a writeback error](/articles/1794240000001-ship-business-central-sales-orders-in-parts#recover-from-a-writeback-error).

## Configure Business Central settings

| Setting | What it controls |
| --- | --- |
| **Enable** | Turns the Dynamics 365 Business Central connection on or off. |
| **Connection status** | Shows whether Starshipit has a current Microsoft authorisation. This is a status indicator, not an editable setting. |
| **Environment** | Selects the Business Central environment to use. |
| **Company** | Selects the Business Central company whose records Starshipit imports. The list is filtered by the selected environment. |
| **Import type** | Selects **Sales Order** or **Sales Invoice** as the source record type. |
| **Action** | Selects the action applied to the chosen import type, such as `SHIPANDINVOICE` for sales orders or `POST`, `POSTANDSEND`, and `SEND` for sales invoices. |
| **Status** | Selects the source status to import: `DRAFT` or `OPEN`. |
| **Map address line 2 into the Building field** | Sends Ship-to Address Line 2 to Building when enabled, or Suburb when disabled. City remains separate. |

Use **Authorize** to connect or refresh Microsoft access. Click **Save** after changing settings, then use **Test connection** to verify the selected environment and company.
