Skip to main content

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.

Required scope: integrations:write

Grant 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​

Created

Response Headers
    Content-Type