Skip to main content

Create Integration Instance

POST 
/api/shippo/instances

Connects a Shippo account. The token is verified live with Shippo first — an invalid token creates nothing. Only one Shippo connection is allowed per account.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

On success the instance is created with default settings (auto_push_orders true, record_shipping_costs true, label_file_type PDF_4x6, sync_start_date as given or today), the Shippo webhooks are registered in the background, and initial carrier, order and label syncs are queued.

Body fields:

  • name (string, required): a label for this connection. Max 255 characters.
  • api_token (string, required): the Shippo API token. 20–255 characters, must start with shippo_test_ or shippo_live_. Surrounding whitespace is trimmed.
  • sync_start_date (string, optional, nullable): earliest date the initial order and label import covers, as Y-m-d (a calendar day in the account timezone). Cannot be in the future. Defaults to today.

Returns 201 with the created instance. The API token is never returned — only a masked form (api_token_masked). Returns 422 with code already_connected when Shippo is already connected, 422 with field errors on validation failure, and 422 with a Shippo error code when the token is rejected. Shippo failures return 422 with a stable code: invalid_token (Shippo rejected the API token), rate_limited (Shippo is throttling — retry in a minute), api_error (Shippo refused the request; message carries its reason) or unreachable (Shippo could not be reached).

Authentication: Requires a Bearer token.

Request​

Responses​

Created

Response Headers
    Content-Type