# How to integrate with NewStore
URL: https://support.starshipit.com/articles/90200000000113-how-to-integrate-with-newstore
Canonical: https://support.starshipit.com/articles/90200000000113-how-to-integrate-with-newstore
Markdown: https://support.starshipit.com/articles/90200000000113-how-to-integrate-with-newstore.md
Updated: 2026-05-25

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

> Connect NewStore to Starshipit so NewStore can request shipping offers and book shipments.

Connect NewStore to Starshipit so NewStore can request shipping offers and book shipments through Starshipit. This is a webhook-based integration, so NewStore sends shipping requests to Starshipit instead of Starshipit importing orders on a schedule.

## What you need before you start

To connect NewStore to Starshipit, you need:

* Admin access to your Starshipit account
* Access to configure NewStore delivery webhooks
* A Starshipit API key or token for the NewStore Authorization header
* The carrier services you want NewStore to offer, already set up in Starshipit

:::important
Do not publish or share merchant-specific API keys in support tickets or public documentation. Treat the Authorization header value like a password.
:::

## 1. Set up your carriers in Starshipit

Before connecting NewStore, set up the couriers and services you want NewStore to use.

1. In Starshipit, go to **Settings** > **Couriers**.
2. Add and enable the couriers you want to use for NewStore shipments.
3. Add any required product or service codes for those couriers.
4. Confirm you can create labels with those courier services in Starshipit.

NewStore can only return offers and book shipments for carrier services that are available in your Starshipit account.

## 2. Enable NewStore in Starshipit

1. In Starshipit, go to **Settings** > **Integrations** > **Add a new integration**.
2. Select **NewStore**.
3. Enable the NewStore integration.
4. Save your settings.

After saving, your Starshipit account is ready to receive NewStore shipping offer and shipment booking requests.

## 3. Configure NewStore webhooks

Configure NewStore to send delivery webhook requests to Starshipit.

| NewStore action | Starshipit endpoint |
| --- | --- |
| Shipping offers | `/api/integrations/newstore/v1/shipping_offers` |
| Book shipment | `/api/integrations/newstore/v1/shipments` |

Both webhook requests must include the Starshipit API key or token in the Authorization header. Starshipit uses this to find the correct Starshipit account.

NewStore can also send an optional `X-Request-ID` header to help trace requests.

## How the integration works

When NewStore asks for shipping offers, Starshipit checks the sender address, receiver address, deliverables, ready-by time, and available carrier services. Starshipit then returns the available shipping offers sorted by price.

When NewStore books a shipment, Starshipit creates or finds the matching Starshipit order, creates the shipment and label, then returns the tracking details and label information to NewStore.

## Limitations

* NewStore is webhook-based. Starshipit does not import NewStore orders on a schedule.
* Shipment cancellation through the NewStore cancel shipment webhook is not supported in this version.
* Advanced or bulk manifest workflows are not supported in this version.
* Shipping offers expire 15 minutes after Starshipit returns them.
* Booking requests need an external order ID, booking method, sender address, receiver address, and at least one item.

## Troubleshooting

**No shipping offers are returned?**

Check that:

* The Authorization header uses the correct Starshipit API key or token.
* Sender and receiver country codes are valid.
* Sender and receiver address details are complete.
* The request includes at least one deliverable.
* The ready-by time is valid.
* The required carrier services and rates are set up in Starshipit.

**Shipment booking is failing?**

Check that:

* The request includes an external order ID and booking method.
* Sender and receiver addresses include first name, last name, address line 1, city, country code, and postcode or zip code.
* Item and package details are complete.
* The selected carrier service is available in Starshipit.
* Starshipit can generate a label for the selected service.

**The same order is sent more than once?**

Starshipit checks the external order ID before creating a new order. If NewStore sends the same external order ID again, Starshipit attempts to use the existing order instead of creating a duplicate.