# Connect Peoplevox to Starshipit
URL: https://support.starshipit.com/articles/360000934795-connect-peoplevox-to-starshipit
Canonical: https://support.starshipit.com/articles/360000934795-connect-peoplevox-to-starshipit
Markdown: https://support.starshipit.com/articles/360000934795-connect-peoplevox-to-starshipit.md
Updated: 2026-11-17

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

> Connect Peoplevox, preview source values, map order and item fields, and return shipping labels and tracking to Peoplevox.

Connect Peoplevox to Starshipit so allocated or despatched orders can be sent to Starshipit and labels and tracking numbers can be returned to Peoplevox.

![Flow of orders, labels, and tracking between Peoplevox and Starshipit](/uploads/articles/integrations/inventory-warehouse-retail-management/peoplevox-integration/image_360005317936.png)

:::important
Peoplevox may charge an additional subscription fee to enable its carrier integration module. Confirm access with Peoplevox before you begin.
:::

## Before you begin

You need:

- Admin access to Starshipit.
- Access to the **Integration** view in Peoplevox.
- Your Peoplevox client ID, username, password, and region if you want orders sent when stock is allocated.

## Add Peoplevox in Starshipit

1. In Starshipit, go to **Settings > Integrations**.
2. Click **Add a new integration**, then select **Peoplevox**.
3. Enter a display name for the integration.
4. Select the region used by your Peoplevox instance:
   - **Americas (US)**
   - **Asia Pacific (AP)**
   - **Europe (WMS)**
5. Choose the Peoplevox sources for company name, building, phone number, currency code, and delivery instructions. Use the field-mapping steps below if you need to inspect source values first.
6. If required, map attributes 1–15 for HS code and country of manufacture.
7. Click **Save**.

## Receive orders when stock is allocated

This optional subscription sends orders to Starshipit earlier, giving you time to correct invalid addresses before despatch.

1. Enter the **Client ID**, **Username**, and **Password** used to access Peoplevox.
2. Set **Requested Delivery Date** to a recent date to prevent historical orders from importing.
3. Click **Save**.
4. Click **Test** and confirm the result is **Successful**.
5. Click **Subscribe**.

## Add Starshipit as a carrier integration in Peoplevox

1. In Peoplevox, switch to the **Integration** view.
2. Select **Carrier Integration**, then click **Add New**.
3. Enter `Starshipit` as the name.
4. Set **Date time format** to `dd/MM/yyyy hh:mm:ss`.
5. Set **Timeout (ms)** to `30000`.
6. Copy the **API key** and **Endpoint** from **Settings > Integrations > Peoplevox** in Starshipit.
7. Paste both values into Peoplevox.
8. Set **Tracking number format** to `{returns}/{outbound}`.
9. Click **Save**.

:::note
If Starshipit shows only a partial API key, go to **Settings > API** and click **Generate**, then return to the Peoplevox integration to copy the full key.
:::

## Configure Peoplevox settings

The integration settings control how Peoplevox data is mapped into Starshipit and how shipments are returned.

| Setting | What it does |
| --- | --- |
| **Display name** | Names this Peoplevox connection in Starshipit. |
| **Region** | Selects the Peoplevox region for the connection. |
| **Company name**, **Building**, **Phone number**, **Currency code**, **Tags**, **Duties amount**, **Delivery instructions**, **Contact name**, **HS code**, **Manufacture country**, and **MID code** | Choose from the Peoplevox sources offered for each order or item field. Some fields offer native sources as well as custom attributes. |
| **Import Merchant Product ID from**, **Import Manufacturer Product ID from**, **Import Standardised Product ID from** | Independently map each product identifier to its Peoplevox item attribute. Leave unused fields at **Do not import**. |
| **Receiver tax numbers** | Map sales-order fields to a receiver tax type and destination. See [Map receiver tax numbers from Peoplevox](/articles/1793376000001-map-receiver-tax-numbers-from-peoplevox) for setup, subscription requirements and verification. |
| **Client ID**, **Username**, **Password** | Credentials for the Peoplevox API. |
| **Filter date** | Limits the Peoplevox records considered for import from the selected date. |
| **Subscription ID** | Identifies the Peoplevox subscription used by the connection. |
| **Do not run rules on label print** | Prevents Starshipit rules from running again when a label is printed. |
| **Re-run cheapest carrier rules before label printing** | Re-evaluates the cheapest-carrier rule before printing. |
| **Import address line 2 to building** | Places Peoplevox address line 2 in Starshipit’s Building field. |
| **Import package type** | Imports the Peoplevox package type. |
| **Import item descriptions** | Imports item descriptions with the order lines. |
| **Package weights** / **Package details** | Choose whether Starshipit uses package weights or Peoplevox despatch-package dimensions and details. When package details are selected, choose the **Dimensions unit**. |
| **Consolidate shipment** | Combines Peoplevox packages into one Starshipit shipment when the despatch is complete. |
| **Writeback service type** | Sends the Starshipit service type back to Peoplevox. |

Save the settings after changing the mappings or shipment options.

## Map order and item fields

In UI 2.0, open **Settings > Integrations > Peoplevox** for the connection you want to configure. **Field mapping** separates **Order fields mapping** from **Item fields mapping**. Choose a **Peoplevox source** for each Starshipit field, then select **Save** and reopen the connection to check your selections.

### Preview source values

Save the connection and its Peoplevox credentials before loading an example. Loading values is optional: you can configure mappings without it.

1. Enter a Peoplevox order number in **Example order number (optional)**.
2. Select **Load order values**.
3. Open a **Peoplevox source** dropdown to compare the source names and example values.
4. Under **Item fields mapping**, choose an **Example SKU** to inspect a different item from that order.
5. Select the sources you need, then select **Save**. Reopen the connection to confirm the mappings.

Loading an example does not import the order or save mapping changes. Example values are temporary source data, before shipping rules and other import settings are applied.

| Example result | What to do |
| --- | --- |
| **Empty on this order** or **Empty on this item** | The source was returned blank. Check its value in Peoplevox. |
| **Not available in this example** | The source was not returned. Check the Peoplevox export fields below; do not treat this result as proof the source is blank. |
| Some example data is unavailable | Review the available values. Missing fields remain selectable, so confirm them in Peoplevox before choosing them. |
| Order not found or lookup failed | Check the order number, saved credentials and export configuration, then retry. |

For missing native values, in Peoplevox open **Integrations > Integration templates > Configure > Export**. Keep existing mappings and check these export field names against their matching native sources:

| Template | Export field names |
| --- | --- |
| **Sales orders** | `Customer`, `ShippingAddressCompanyName`, `ShippingAddressLine2`, and `Currency` when using native currency |
| **Customers** | `Name`, `Phone`, `Mobile` |
| **Sales order items** | `SalesOrderNumber`, `ItemCode` |
| **Item types** | `ItemCode`, `HSCode`, `CountryOfOrigin` |

Custom-attribute examples also need their corresponding `Attribute1`–`Attribute5` order fields or `Attribute1`–`Attribute15` item fields. If the Customers template is not configured, configure it with CSV headers `Name,Reference,Phone,Mobile`, then check its Export mappings. You do not need to import customer records to load an example.

For **Customer record** sources, Company uses the shipping company and Building uses shipping address line 2. Phone uses the customer mobile number when populated, otherwise the customer phone number. A missing or ambiguous customer match leaves that example unavailable. **Import address line 2 to building** takes precedence over another selected Building mapping when enabled.

### Import native currency

Use the currency from the Peoplevox sales order directly, without copying it into a custom attribute.

1. Under **Order fields mapping > Currency code**, set **Import currency code from** to **SalesOrder > Currency**. Use **Load order values** to check an example if needed.
2. Select **Save**. If you use allocation updates, subscribe after saving. For an existing subscription, select **Unsubscribe**, then **Subscribe** with the same filter date.
3. Check the currency on the next order processed through allocation or despatch before relying on the mapping.

If the currency is missing or unexpected, check that Peoplevox supplies it for that workflow and that no Starshipit rule overrides it. Starshipit keeps any existing order currency when Peoplevox supplies none. This mapping does not convert order amounts.

### Import native delivery notes

Choose **SalesOrder > Delivery Notes** for **Delivery instructions** to use native Peoplevox notes without copying them into an attribute.

1. Select the native source for delivery instructions, then select **Save**.
2. Reopen the connection to confirm it remains selected.
3. On a planned despatch, check that Peoplevox includes its delivery notes and compare them with the Starshipit order's delivery instructions.

This source is applied when full despatch details arrive, including label-print requests. It does not populate instructions at stock allocation. Existing allocation subscriptions do not need to be recreated for this selection.

For an order already in Starshipit, native notes fill blank delivery instructions. Existing nonblank instructions and saved address details are preserved. Missing or blank native notes leave the instructions unchanged. If saved instructions need correcting, edit them in Starshipit before printing; a later Peoplevox despatch will not replace them.

**Customer record**, **Attribute 1**–**Attribute 5** and **Do not import** remain available for delivery instructions. The native Delivery Notes source is offered only for that field.

## Map product identifiers

Use these optional mappings when Peoplevox holds the product identifiers required for your shipments. Collect the manufacturer's product codes and recognised identifiers, such as GTINs, EANs or UPCs, before selecting the attributes. An internal warehouse barcode is not necessarily a recognised product identifier.

1. Open **Settings > Integrations > Peoplevox** in Starshipit.
2. Set **Import Merchant Product ID from**, **Import Manufacturer Product ID from** and **Import Standardised Product ID from** to the relevant **ItemType > Attribute 1** through **ItemType > Attribute 15** entries. Choose each mapping independently; they do not need to use the same attribute.
3. Leave any identifier you do not use at **Do not import**. Existing connections keep that default until you select a mapping.
4. Click **Save**, then reopen the connection and confirm the selected attributes remain.
5. Check that Peoplevox includes those attribute values in the despatch data for the products you send.

The mappings apply when Peoplevox sends despatched order items to Starshipit, including when Peoplevox requests a label. An unselected mapping, missing item data or an empty source attribute leaves that imported identifier blank. **Manufacturer Product ID** identifies a product and is separate from **MID code**, which identifies its manufacturer.

[Product Catalogue settings](/articles/1781620000002-configure-product-catalogue-settings) still apply after the Peoplevox mapping. Check SKU matching and fill-missing versus overwrite behaviour. Overwrite can replace imported identifiers, including with blanks if protection against empty values is off.

## Verify the connection and identifiers

Use a representative planned despatch in Peoplevox. Confirm the order appears in Starshipit and Peoplevox receives its label and tracking number. When the allocation subscription is enabled, check identifier values after despatch rather than relying on the initial allocated order.

In the Starshipit UI 2.0 order's **Items** section, show the three product identifier columns and compare them with the Peoplevox source attributes. If a value is missing, check the selected mapping, the despatch data and Product Catalogue settings before processing more orders. Saving a mapping does not itself update earlier orders.

For destination tax identifiers, [map receiver tax numbers from Peoplevox](/articles/1793376000001-map-receiver-tax-numbers-from-peoplevox). These are receiver details, separate from the product identifiers above.

Next, [configure Peoplevox labels, couriers and packages](/articles/90200000000501-configure-peoplevox-labels-couriers-and-packages), or review [product identifier requirements for EU shipments](/articles/1790827200001-set-up-product-identifiers-for-eu-shipments).
