# Import orders, print in Starshipit, and update the source system
URL: https://support.starshipit.com/articles/14700000001005-import-orders-print-in-starshipit-and-update-the-source-system
Canonical: https://support.starshipit.com/articles/14700000001005-import-orders-print-in-starshipit-and-update-the-source-system
Markdown: https://support.starshipit.com/articles/14700000001005-import-orders-print-in-starshipit-and-update-the-source-system.md
Updated: 2026-06-18

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

> Import orders into Starshipit, print labels in the Starshipit UI, and update the source system with tracking.

Import orders into Starshipit when another system receives or manages orders, but your team prints labels in the Starshipit UI. After printing, send tracking and shipment status back to the source system.

## Before you begin

- Confirm your API key and subscription key.
- Confirm your team will print labels in the Starshipit UI.
- Map required order, destination, item, and package fields.
- Confirm how your source system marks an order as ready to ship.

## Recommended workflow

1. Retrieve ready-to-ship orders from your ecommerce, ERP, WMS, marketplace, middleware, or custom platform.
2. Create the order in Starshipit with [POST /api/orders](/developers/api-reference/starshipit#endpoint-orders-post-api-orders-create-order), or batch multiple orders with [POST /api/orders/import](/developers/api-reference/starshipit#endpoint-orders-post-api-orders-import-create-orders).
3. Confirm the order appears in Starshipit with [GET /api/orders/unshipped](/developers/api-reference/starshipit#endpoint-orders-get-api-orders-unshipped-list-orders-unshipped), [GET /api/orders/search](/developers/api-reference/starshipit#endpoint-orders-get-api-orders-search-phrase-john-20smith-search-orders), or the Starshipit UI.
4. Your team prints labels in the Starshipit UI.
5. Your team manifests shipments in the Starshipit UI when the operational process is ready.
6. Starshipit creates tracking details for the shipment.
7. Update the source system by receiving webhooks or polling [GET /api/track](/developers/api-reference/starshipit#endpoint-tracking-get-api-track-tracking).

## Endpoint map

| Step | Endpoint | Use it to |
| --- | --- | --- |
| Create one order | [POST /api/orders](/developers/api-reference/starshipit#endpoint-orders-post-api-orders-create-order) | Import a single source order into Starshipit. |
| Create many orders | [POST /api/orders/import](/developers/api-reference/starshipit#endpoint-orders-post-api-orders-import-create-orders) | Batch ready-to-ship orders where batching fits your workflow. |
| Check imported orders | [GET /api/orders/unshipped](/developers/api-reference/starshipit#endpoint-orders-get-api-orders-unshipped-list-orders-unshipped) or [GET /api/orders/search](/developers/api-reference/starshipit#endpoint-orders-get-api-orders-search-phrase-john-20smith-search-orders) | Confirm the order exists before staff print labels. |
| Receive tracking updates | `POST /callback/` | Let Starshipit notify your system after tracking changes. |
| Poll tracking if needed | [GET /api/track](/developers/api-reference/starshipit#endpoint-tracking-get-api-track-tracking) | Reconcile tracking when webhooks are unavailable or missed. |

Use the [Starshipit API reference](/developers/api-reference/starshipit) for the latest request examples and the [Models section](/developers/api-reference/starshipit/models) for order, item, package, label, and error fields.

## Create one order

Use `POST /api/orders` when your integration creates one order at a time.

```bash
curl --request POST \
  --url https://api.starshipit.com/api/orders \
  --header "StarShipIT-Api-Key: YOUR_API_KEY" \
  --header "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "order": {
      "order_number": "10001",
      "reference": "Online order",
      "shipping_method": "Standard",
      "destination": {
        "name": "Jane Smith",
        "phone": "0200000000",
        "street": "20 George Street",
        "suburb": "Sydney",
        "state": "NSW",
        "post_code": "2000",
        "country": "Australia"
      },
      "items": [
        {
          "description": "T-shirt",
          "quantity": 1,
          "sku": "TSHIRT-BLACK-M",
          "weight": 0.3,
          "value": 25
        }
      ]
    }
  }'
```

## Batch orders where possible

Use `POST /api/orders/import` when your integration imports multiple ready-to-ship orders. Batching reduces request volume and helps avoid rate limit issues.

```bash
curl --request POST \
  --url https://api.starshipit.com/api/orders/import \
  --header "StarShipIT-Api-Key: YOUR_API_KEY" \
  --header "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "orders": [
      {
        "order_number": "10001",
        "reference": "Online order",
        "shipping_method": "Standard",
        "destination": {
          "name": "Jane Smith",
          "street": "20 George Street",
          "suburb": "Sydney",
          "state": "NSW",
          "post_code": "2000",
          "country": "Australia"
        },
        "items": [
          {
            "description": "T-shirt",
            "quantity": 1,
            "sku": "TSHIRT-BLACK-M"
          }
        ]
      },
      {
        "order_number": "10002",
        "reference": "Online order",
        "shipping_method": "Express",
        "destination": {
          "name": "Alex Lee",
          "street": "1 Queen Street",
          "suburb": "Auckland",
          "post_code": "1010",
          "country": "New Zealand"
        },
        "items": [
          {
            "description": "Socks",
            "quantity": 2,
            "sku": "SOCKS-BLUE"
          }
        ]
      }
    ]
  }'
```

Create orders before the warehouse needs to print labels. Starshipit runs background work such as rules, courier rating, validation, and service selection after orders are created, so creating orders early can keep the print step faster.

## When to use this pattern

Use this pattern when Starshipit is the shipping workspace and the external system is the order source. It is a good fit when warehouse staff already use Starshipit to review orders, choose services, print labels, manifest shipments, and troubleshoot carrier errors.

## Map order data

At minimum, your integration usually needs to map:

| Data | Why it matters |
| --- | --- |
| Order number | Lets Starshipit and your source system refer to the same order. |
| Destination address | Required for rates and labels. |
| Customer contact details | Used for courier data, notifications, and support. |
| Items | Required for packing, customs, and downstream fulfilment workflows. |
| Shipping method | Can be used by Starshipit rules to choose carrier and service. |
| Packages | Useful when the source system already knows parcel weights and dimensions. |
| Optional order enrichment | Include supported order, item, package, customs, billing, sender, and destination fields when your source system owns that data. Examples include `shipping_freight_value`, `dangerous_goods`, `tax_numbers`, `customs`, `brand`, `material`, `bin_location`, package `name`, and `packaging_type`. |

The API reference examples intentionally show a fuller payload than the minimum required fields. You can include supported optional attributes from the [Models section](/developers/api-reference/starshipit/models) when they apply to your workflow.

:::note
Order tags are managed through the Tags endpoints after the order exists. Use `POST /api/tags/order` to add tags and `DELETE /api/tags/order` to remove tags.
:::

:::important
For international shipments, include item descriptions, values, weights, tariff or HS codes, and country of origin where possible. Missing customs data can stop label creation or delay clearance.
:::

## Verify the import

After creating test orders, confirm:

- The order appears in Starshipit.
- The destination address is complete.
- Items and quantities match the source order.
- Shipping method and any metadata are present.
- Starshipit rules behave as expected.

## Common issues

| Issue | What to check |
| --- | --- |
| Duplicate order error | Confirm whether the order was already imported and whether you should update it instead. |
| Missing customs fields | Check item value, description, country of origin, tariff code, and weight. |
| Wrong carrier selection | Check the shipping method sent to Starshipit and the matching rules in Starshipit. |
| Slow order availability | Create orders before the warehouse needs to print labels so rules and validation have time to run. |

## Related guides

- [Print outside Starshipit and return tracking](/articles/developer-center/starshipit-api/print-outside-starshipit-and-return-tracking)
- [Update orders before printing](/articles/developer-center/starshipit-api/update-orders-before-printing)
- [Use webhooks and tracking updates](/articles/developer-center/starshipit-api/use-webhooks-and-tracking-updates)
- [Starshipit API reference](/developers/api-reference/starshipit)