# Plan a Starshipit API integration
URL: https://support.starshipit.com/articles/14700000001004-plan-a-starshipit-api-integration
Canonical: https://support.starshipit.com/articles/14700000001004-plan-a-starshipit-api-integration
Markdown: https://support.starshipit.com/articles/14700000001004-plan-a-starshipit-api-integration.md
Updated: 2026-06-18

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

> Plan the data flow, ownership, and error handling for a Starshipit API integration before you build.

Plan your Starshipit API integration by deciding which system owns each part of the fulfilment workflow, how data moves between systems, and how failures are retried or surfaced to your team.

## Understand what the API uses from Starshipit

The API works with the setup in your Starshipit account. Before you build, confirm which parts of the shipping workflow should already be configured in Starshipit and which parts your integration will send by API.

For example, live rates need enabled couriers, sender addresses, supported destinations, package data, and any service filters or rules that affect which rates are returned. Label generation also depends on courier setup, package details, service selection, customs data for international shipments, and account-level courier requirements.

Use the API to create, update, rate, label, manifest, and sync data against that setup. Do not treat the API as a shortcut around configuring the Starshipit account first.

## Choose the integration pattern

| Pattern | Use when | Typical flow |
| --- | --- | --- |
| Import, print in Starshipit, write back | Starshipit is the shipping workspace and another system owns orders | External system creates orders in Starshipit, staff print labels in Starshipit, then tracking returns by webhook or polling. |
| Print outside Starshipit | Another system owns fulfilment and printing | External system creates or updates the order, calls the label endpoint, stores the label and tracking number, then manifests when ready. |
| Checkout and live rates | Another system needs shipping options before an order is shipped | External system sends destination and package details, displays returned rates, then stores the selected shipping method. |
| Print Starshipit-imported orders externally | Starshipit imports orders through a native integration, but another system prints labels | External system finds the Starshipit order, updates it if required, calls the label endpoint, and stores tracking. |
| Update before printing | Another system needs to correct or enrich an order already in Starshipit | External system finds the order, updates allowed fields, verifies the data, then prints in the UI or through the API. |
| Product data sync | Another system owns product master data | External system syncs SKU, weight, dimensions, customs, and fulfilment fields into Product Catalogue for rates, orders, and customs. |

### Import orders and print in Starshipit

Use this pattern when another system creates orders, but your team works in Starshipit to print labels and manifest shipments.

![Shipping with the Starshipit API and Starshipit interface](/uploads/articles/developer-center/starshipit-api/plan-a-starshipit-api-integration/starshipit-api-with-starshipit-interface.png)

### Print through another system

Use this pattern when a WMS, ERP, middleware tool, or custom fulfilment system owns the printing workflow and calls Starshipit to generate labels.

![Shipping with the Starshipit API and a third-party interface](/uploads/articles/developer-center/starshipit-api/plan-a-starshipit-api-integration/starshipit-api-with-third-party-interface.png)

## Map the source of truth

Before you build requests, decide which system owns each field.

| Data | Common source of truth | Notes |
| --- | --- | --- |
| Order number | Ecommerce platform, ERP, WMS, or middleware | Keep this stable so updates and tracking can be matched later. |
| Customer and destination address | Source order system | Validate required address fields before creating labels. |
| Shipping method | Source system or Starshipit rules | You can map shipping methods to carrier services through Starshipit rules. |
| Product dimensions and customs data | Product Catalogue, ERP, PIM, or ecommerce platform | Use Product Catalogue when Starshipit should enrich missing product data. |
| Carrier and service | Starshipit rules or API update flow | Do not hard-code carrier logic unless your operation requires it. |
| Tracking number | Starshipit after label creation | Use webhooks where possible, or poll tracking and order endpoints when webhooks are unavailable or missed. |

## Build in stages

1. Confirm authentication and rate limits.
2. Create one test order with the smallest realistic payload.
3. Confirm the order appears in Starshipit with the expected address, items, and shipping method.
4. Add product data, packages, customs fields, and metadata.
5. Generate a label in a controlled test flow.
6. Add webhook handling or polling for tracking writeback.
7. Add retry handling and operational logging.

## Design around rate limits and background work

Batch order imports where possible instead of sending one request for every order in a tight loop. Batching keeps request volume lower, makes retries easier to reason about, and reduces the chance that a busy integration exceeds its rate limit.

Create orders before the warehouse needs to print them. Starshipit can run background work after an order is created, including rules, address checks, courier rating, and service selection. If your integration creates an order and immediately tries to print it, the print flow may wait on work that could have already happened earlier in the fulfilment process.

## Design for support

Log enough detail to investigate failures without exposing secrets:

- Source-system order ID.
- Starshipit order ID, when available.
- Endpoint and HTTP method.
- Response status and response body.
- Retry count.
- Timestamp.
- Whether the request created, updated, labelled, manifested, or synced data.

## Verify before production

Test with domestic and international orders, at least one multi-item order, and at least one failure case. Confirm your team knows where failed requests appear and how to replay or correct them.