Create Shiptheory Instance
POST/api/shiptheory
Creates and connects a new Shiptheory integration instance for the current account, then returns it together with a live dashboard summary. The initial delivery-services, orders and shipments syncs are started in the background, plus the package-sizes download unless sync_package_sizes is false.
integrations:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body fields:
- name (string, required): a label for this connection. Max 255 characters.
- connection_settings (object, required): the Shiptheory account credentials.
- connection_settings.email (string, required): Shiptheory account email. Max 255 characters.
- connection_settings.password (string, required): Shiptheory account password. Max 255 characters.
- sync_package_sizes (boolean, optional): download the account's package sizes from Shiptheory right after connecting. Default true; send false to skip it (it can be run later).
- settings (object, optional): behaviour settings; anything omitted uses the module defaults (rules engine on, record costs on).
- settings.use_rules_engine (boolean, optional): leave unmapped shipping methods to Shiptheory's rules engine. Default true.
- settings.mark_for_approval (boolean, optional): submit shipments held for manual release (they land in status "Waiting"). Default false.
- settings.default_package_size_id (integer, optional, nullable): Shiptheory package size id applied when no packaging is supplied.
- settings.record_shipping_costs (boolean, optional): write the booked shipment cost back onto the order. Default true.
- settings.sync_start_date (date, optional, nullable): earliest order date to sync (YYYY-MM-DD). Defaults to the account's inventory start date when omitted or null.
Returns 201 with the created instance and its dashboard summary. Returns 422 with field errors when validation fails.
Authentication: requires a Bearer token.
Instance names are unique across all of your integrations; reusing an existing name returns 422 with a name error.
Request
Responses
- 201
- 401
- 403
- 422
- 429
Created
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.