Bridges

Manage bridge integrations that connect Orderly to external platforms. Each bridge is an instance of a bridge type (e.g., Shopify, ShipStation) configured with credentials and settings specific to your organization.

Sensitive configuration values such as API keys and access tokens are automatically redacted in all responses.

List Bridges

GET/api/v1/bridges

List all configured bridges for the organization.

Requiredbridges:read

Returns a paginated list of bridges with their status, type, and last sync time.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`type`	string	Filter by bridge type: `shopify`, `shipstation`, `woocommerce`, `bigcommerce`, `amazon`
`status`	string	Filter by status: `active`, `paused`, `error`, `disconnected`


curl -X GET "https://api.orderly-hub.com/api/v1/bridges?type=shopify&status=active" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "660e8400-e29b-41d4-a716-446655440000",
      "type": "shopify",
      "name": "My Shopify Store",
      "config": {
        "shopDomain": "my-store.myshopify.com",
        "accessToken": "--------",
        "enabledWebhooks": ["orders/create"]
      },
      "status": "active",
      "lastSyncAt": "2026-01-15T10:00:00.000Z",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1,
    "hasMore": false
  }
}

Get Bridge

GET/api/v1/bridges/:id

Retrieve a single bridge by ID.

Requiredbridges:read

Returns the full bridge object including type, status, and sanitized configuration. Credential values are redacted with --------.


curl -X GET "https://api.orderly-hub.com/api/v1/bridges/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "660e8400-e29b-41d4-a716-446655440000",
    "type": "shopify",
    "name": "My Shopify Store",
    "config": {
      "shopDomain": "my-store.myshopify.com",
      "accessToken": "--------",
      "enabledWebhooks": ["orders/create", "orders/updated"],
      "registeredWebhooks": { "orders/create": 123456, "orders/updated": 123457 }
    },
    "status": "active",
    "lastSyncAt": "2026-01-15T10:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-15T10:00:00.000Z"
  }
}

Create Bridge

POST/api/v1/bridges

Create and configure a new bridge integration.

Requiredbridges:write

Creates a new bridge. The config object must include all required fields for the specified bridge type. The bridge is created with an active status by default.

Both camelCase and snake_case keys are accepted in the request body.

Request Body

Field	Type	Required	Description
`type`	string	Yes	Bridge type: `shopify`, `shipstation`, `woocommerce`, `bigcommerce`, `amazon`
`name`	string	Yes	Display name for this bridge (1-100 characters)
`config`	object	Yes	Credentials and settings per the bridge type

Config fields by type

Type	Required Fields
`shopify`	`shopDomain`, `accessToken`
`shipstation`	`apiKey`, `apiSecret`
`woocommerce`	`storeUrl`, `consumerKey`, `consumerSecret`
`bigcommerce`	`storeHash`, `accessToken`
`amazon`	`sellerId`, `refreshToken`, `clientId`, `clientSecret`, `marketplaceId`


curl -X POST "https://api.orderly-hub.com/api/v1/bridges" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "shopify",
    "name": "Production Shopify",
    "config": {
      "shopDomain": "my-store.myshopify.com",
      "accessToken": "shpat_..."
    }
  }'

Response (201 Created)


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "660e8400-e29b-41d4-a716-446655440000",
    "type": "shopify",
    "name": "Production Shopify",
    "config": {
      "shopDomain": "my-store.myshopify.com",
      "accessToken": "--------"
    },
    "status": "active",
    "lastSyncAt": null,
    "createdAt": "2026-01-20T14:00:00.000Z",
    "updatedAt": "2026-01-20T14:00:00.000Z"
  }
}

Update Bridge

PATCH/api/v1/bridges/:id

Update bridge name, config, or status.

Requiredbridges:write

Updates a bridge’s configuration. You can change the name, update credentials, or toggle the bridge status. Config updates are merged with the existing config rather than replacing it. Masked values (--------) sent in config updates are automatically ignored to prevent overwriting real credentials.

Request Body

Field	Type	Description
`name`	string	New display name (1-100 characters)
`config`	object	Updated configuration values (merged with existing)
`status`	string	Set to `active`, `paused`, `error`, or `disconnected`


curl -X PATCH "https://api.orderly-hub.com/api/v1/bridges/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Staging Shopify", "status": "paused"}'

Response


{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organizationId": "660e8400-e29b-41d4-a716-446655440000",
    "type": "shopify",
    "name": "Staging Shopify",
    "config": {
      "shopDomain": "my-store.myshopify.com",
      "accessToken": "--------"
    },
    "status": "paused",
    "lastSyncAt": "2026-01-15T10:00:00.000Z",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-20T15:00:00.000Z"
  }
}

Delete Bridge

DELETE/api/v1/bridges/:id

Delete a bridge and remove its configuration.

Requiredbridges:write

Permanently deletes a bridge. This does not delete orders or shipments that were previously synced through this bridge.


curl -X DELETE "https://api.orderly-hub.com/api/v1/bridges/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

List Bridge Tasks

GET/api/v1/bridges/:id/tasks

List available task definitions for a bridge based on its type.

Requiredbridges:read

Returns the task definitions available for a specific bridge, determined by the bridge’s type. Task definitions describe the sync, push, and webhook operations that the bridge supports.


curl -X GET "https://api.orderly-hub.com/api/v1/bridges/550e8400-e29b-41d4-a716-446655440000/tasks" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "bridge_type": "shopify",
      "name": "grab-orders",
      "display_name": "Grab Orders",
      "description": "Sync orders from Shopify",
      "category": "sync",
      "supports_schedule": true,
      "created_at": "2026-01-01T00:00:00.000Z"
    },
    {
      "id": "uuid",
      "bridge_type": "shopify",
      "name": "push-fulfillment",
      "display_name": "Push Fulfillment",
      "description": "Push fulfillment updates back to Shopify",
      "category": "push",
      "supports_schedule": false,
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Get Webhook Configuration

GET/api/v1/bridges/:id/webhooks

Get the webhook configuration and available topics for a bridge.

Requiredbridges:read

Returns whether the bridge type supports webhooks, the available topics, currently enabled topics, and registered webhook IDs. If the bridge type does not support webhooks, returns supported: false.


curl -X GET "https://api.orderly-hub.com/api/v1/bridges/550e8400-e29b-41d4-a716-446655440000/webhooks" \
  -H "Authorization: Bearer oh_..."

Response (webhook-supported bridge)


{
  "data": {
    "supported": true,
    "bridgeId": "550e8400-e29b-41d4-a716-446655440000",
    "bridgeType": "shopify",
    "availableTopics": [
      { "topic": "orders/create", "description": "Triggered when a new order is created" },
      { "topic": "orders/updated", "description": "Triggered when an order is updated" },
      { "topic": "orders/fulfilled", "description": "Triggered when an order is fulfilled" }
    ],
    "enabledTopics": ["orders/create"],
    "registeredWebhooks": { "orders/create": 123456 },
    "webhookUrl": "https://shopify-bridge.orderly-hub.com/webhooks/550e8400-..."
  }
}

Response (unsupported bridge)


{
  "data": {
    "supported": false,
    "message": "This bridge type does not support webhooks"
  }
}

Available topics by bridge type

Bridge Type	Topic	Description
`shopify`	`orders/create`	Triggered when a new order is created
`shopify`	`orders/updated`	Triggered when an order is updated
`shopify`	`orders/fulfilled`	Triggered when an order is fulfilled
`shipstation`	`SHIP_NOTIFY`	Triggered when a shipment is created in ShipStation
`shipstation`	`ORDER_NOTIFY`	Triggered when an order is created or updated in ShipStation
`shipstation`	`ITEM_SHIP_NOTIFY`	Triggered for each item when a shipment is created

Enable Webhooks

POST/api/v1/bridges/:id/webhooks

Requiredbridges:write

Registers webhooks with the external platform (e.g., Shopify, ShipStation) for the specified topics. The topics must be valid for the bridge’s type. Already-registered topics are skipped. The endpoint returns the list of enabled topics and any registration errors.

Request Body

Field	Type	Required	Description
`topics`	string[]	Yes	List of webhook topics to enable (at least one required)


curl -X POST "https://api.orderly-hub.com/api/v1/bridges/550e8400-e29b-41d4-a716-446655440000/webhooks" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "topics": ["orders/create", "orders/updated"]
  }'

Response


{
  "data": {
    "enabled": ["orders/create", "orders/updated"],
    "registered": {
      "orders/create": 123456,
      "orders/updated": 123457
    },
    "webhookUrl": "https://shopify-bridge.orderly-hub.com/webhooks/550e8400-..."
  }
}

Error Response (partial failure)

If some topics fail to register but at least one succeeds, the response includes an errors array:


{
  "data": {
    "enabled": ["orders/create"],
    "registered": { "orders/create": 123456 },
    "webhookUrl": "https://shopify-bridge.orderly-hub.com/webhooks/550e8400-...",
    "errors": [
      { "topic": "orders/updated", "error": "Shopify API error: rate limited" }
    ]
  }
}

Disable Webhook

DELETE/api/v1/bridges/:id/webhooks/:topic

Unregister and disable a specific webhook topic for a bridge.

Requiredbridges:write

Removes a webhook registration from the external platform and disables the topic on the bridge. The :topic parameter is the webhook topic string (URL-encoded if it contains special characters, e.g., orders%2Fcreate for orders/create).


curl -X DELETE "https://api.orderly-hub.com/api/v1/bridges/550e8400-e29b-41d4-a716-446655440000/webhooks/orders%2Fcreate" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "disabled": "orders/create",
    "enabled": ["orders/updated"]
  }
}