Skip to main content

Create Integration Instance

POST 
/api/pinnacle/instances

Connects a Pinnacle account. The credentials are tested first (same checks as Test Connection Credentials); on success the instance is saved, an inbound webhook key is generated, and an initial order sync is queued in the background (from integration_settings.sync_start_date when set, otherwise since the last sync). Only one Pinnacle 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.

Body fields:

  • name (string, required, max 255): display name for the connection.
  • is_automatic_sync_enabled (boolean, optional, default true): run the scheduled order/tracking syncs.
  • connection_settings (object, required).
  • connection_settings.environment (string, required): "production" or "sandbox".
  • connection_settings.client_id (string, required, max 50): your MWD customer number.
  • connection_settings.username (string, required, max 255): Pinnacle Order API username.
  • connection_settings.password (string, required, max 255): Pinnacle Order API password.
  • connection_settings.tracking_api_key (string, required, max 255): Pinnacle Tracking API key.
  • integration_settings (object, optional): dispatch defaults. Every key is optional; omitted keys keep their current value (or the default on create).
  • integration_settings.origin_warehouse_id (integer|null): ships-from warehouse sent as the pickup origin. Must be a US warehouse with a street address, 5-digit ZIP, 2-letter state and a 10-digit phone. null = use each fulfillment order's own warehouse.
  • integration_settings.default_pickup_type (string): Pinnacle pickup type. One of DOCKBI, NONDOCKBI, RESI, DO, DD, MW (default), OTHTRDSHW, OTHSHWRM.
  • integration_settings.inv_client_id (string|null, max 50): MWD inventory client id sent for 3PL inventory releases.
  • integration_settings.default_item_type (string): item type sent per line. One of C-AR, CG (default), LIGHTING, OTH, UP.
  • integration_settings.default_delivery_type (string|null): fallback forward delivery type for shipping methods without an explicit mapping. One of PWG-OFFICE, PWG-RESI, PWG-SHOWROOM, WG-OFFICE, WG-RESI, WG-SHOWROOM, WGN, ROC, TRHD, DS, B2B, WHSE, WC, CS. null = orders on unmapped methods are rejected before dispatch.
  • integration_settings.shipped_event_code (string): the tracking event that marks the order shipped and records the fulfillment. One of PCNE (pickup completed, default), FRBM (received at Metro hub), DCNE (delivered).
  • integration_settings.attach_pod (boolean, default true): download proof-of-delivery files for delivered orders.
  • integration_settings.recall_on_cancel (boolean, default true): cancel the Pinnacle order automatically when its fulfillment order is cancelled.
  • integration_settings.convert_units (boolean, default true): convert metric weights/dimensions to pounds/inches before sending.
  • integration_settings.declared_value_rule (string): line_value_channel_currency (default), line_value_usd or zero.
  • integration_settings.phone_fallback (string): warehouse (default — use the origin warehouse phone when the customer has none) or none (reject the order).
  • integration_settings.sync_start_date (string|null, Y-m-d, not in the future): earliest registration date the order sync imports from.

Returns 201 with the created instance. Secrets are never returned: connection_settings carries only has_password / has_tracking_api_key flags, and webhook.inbound_key_last4 shows the last 4 characters of the inbound key (use Get Webhook Endpoint for the full key). A failed connection test returns 422 with a code and field-keyed errors; a second connection returns 422 on name.

Authentication: requires a Bearer token (Personal Access Token).

Requires the integrations.create permission; without it the request is refused with 403.

Request​

Responses​

Created

Response Headers
    Content-Type