Create Integration Instance
POST/api/starshipit/integration-instances
Creates a new StarShipIt integration instance.
This endpoint currently requires session authentication; Personal Access Token scope support is in progress.
Body fields:
name(string, required) — must be unique across all integration instances.connection_settings(object, required) — credentials:apiKey(StarShipIt API key),subscriptionKey(subscription key), and optionallywebhookSecretfor verifying inbound webhook signatures.integration_settings(object, optional) — behavioural settings such assync_days_back,order_start_date, andfulfillmentwarehouse routing (enabledWarehousesIds,automatedWarehousesIds).is_automatic_sync_enabled(boolean, optional) — whether scheduled syncs run automatically.
Creating an instance immediately queues a background job that backfills orders from StarShipIt. Shipping methods are derived from carriers observed on synced orders, so the same backfill also populates shipping method data. Progress is reported through the tracked background job facilities.
Returns 422 when validation fails (missing/duplicate name, missing connection_settings).
Authentication: Requires Bearer token.
Request
Responses
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.