Embed

The embed system allows 3PLs and platforms to white-label Orderly’s bridge management, data visibility, and operational features directly into their own applications. End users can connect integrations, view orders and shipments, request actions, configure alerts, and manage webhooks — all through your UI.

There are three authentication modes used across embed endpoints:

Public — No authentication required (config lookup by slug, public tracking pages)
API Key (oh_...) — Your server-side API key with embed:manage scope, used for session management, config, end user admin, and event logs
Embed Session (est_...) — Short-lived tokens issued to end users, used for bridge CRUD, data room, action requests, alerts, webhooks, and tracking pages

Get Public Config

GET/api/v1/embed/config

Retrieve the public embed configuration by slug.

Public

Returns public-facing embed configuration for a given slug, including branding and allowed bridge types. No authentication required.

Query Parameters

Parameter	Type	Description
`slug`	string	Required. The embed config slug


curl -X GET "https://api.orderly-hub.com/api/v1/embed/config?slug=acme-fulfillment"

Response


{
  "data": {
    "slug": "acme-fulfillment",
    "branding": {
      "primary_color": "#4F46E5",
      "logo_url": "https://...",
      "company_name": "Acme Fulfillment"
    },
    "allowedBridgeTypes": [
      {
        "id": "shopify",
        "name": "Shopify",
        "icon": "shopify-icon",
        "category": "ecommerce"
      }
    ]
  }
}

Create Auto-Session

POST/api/v1/embed/sessions/auto

Create an embed session using a publishable key (no backend required).

Public (Publishable Key)

Creates a session token directly from the browser using your publishable key. This is the simplest integration path — no backend call required from your server. Origin validation is enforced when allowed origins are configured.

Request Body

Field	Type	Required	Description
`key`	string	Yes	Your publishable key (from embed config)
`externalId`	string	Yes	Your application’s user ID for this end user
`name`	string	No	End user’s display name
`email`	string	No	End user’s email address


curl -X POST "https://api.orderly-hub.com/api/v1/embed/sessions/auto" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "pk_live_abc123...",
    "externalId": "user_12345",
    "name": "Store Owner"
  }'

Response


{
  "data": {
    "token": "est_a1b2c3d4...",
    "expiresAt": "2026-01-15T11:30:00.000Z",
    "scopes": ["bridges:read", "bridges:write", "orders:read", "shipments:read", "tracking:read"],
    "enabledFeatures": ["bridges", "data_room"]
  }
}

Get Config (Authenticated)

GET/api/v1/embed/config/me

Retrieve the full embed configuration for the authenticated organization.

API Keyembed:manage

Returns the complete embed configuration for the current organization, including all settings, allowed origins, publishable key, and enabled features. Used by the dashboard.


curl -X GET "https://api.orderly-hub.com/api/v1/embed/config/me" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "id": "uuid",
    "organization_id": "uuid",
    "slug": "acme-fulfillment",
    "publishable_key": "pk_live_abc123...",
    "branding": {
      "primary_color": "#4F46E5",
      "logo_url": "https://...",
      "company_name": "Acme Fulfillment"
    },
    "allowed_origins": ["https://myapp.com"],
    "allowed_bridge_types": ["shopify", "shipstation"],
    "default_dispatcher_id": null,
    "settings": {},
    "enabled_features": ["bridges", "data_room"],
    "is_active": true,
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:00:00.000Z"
  }
}

Update Config

PATCH/api/v1/embed/config

Create or update the embed configuration.

API Keyembed:manage

Upserts the embed configuration for the current organization. If no config exists, one is created with a generated publishable key. Changes take effect immediately.

Request Body

Field	Type	Description
`slug`	string	URL-safe identifier for the embed config
`branding`	object	Branding customization (colors, logo, company name)
`allowed_origins`	string[]	Allowed origin URLs for CORS and auto-sessions
`allowed_bridge_types`	string[]	Bridge type IDs users can connect
`default_dispatcher_id`	string	Default dispatcher to assign new bridges to
`settings`	object	Additional settings (e.g., `maxBridgesPerUser`)
`enabled_features`	string[]	Feature flags: `bridges`, `data_room`, `action_requests`, `smart_alerts`, `end_user_webhooks`, `branded_tracking`
`is_active`	boolean	Enable or disable the embed system


curl -X PATCH "https://api.orderly-hub.com/api/v1/embed/config" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme-fulfillment",
    "allowed_bridge_types": ["shopify", "shipstation"],
    "allowed_origins": ["https://myapp.com"],
    "enabled_features": ["bridges", "data_room", "action_requests"],
    "branding": { "primary_color": "#059669", "company_name": "Acme" }
  }'

Response


{
  "data": {
    "id": "uuid",
    "organization_id": "uuid",
    "slug": "acme-fulfillment",
    "publishable_key": "pk_live_abc123...",
    "branding": { "primary_color": "#059669", "company_name": "Acme" },
    "allowed_origins": ["https://myapp.com"],
    "allowed_bridge_types": ["shopify", "shipstation"],
    "enabled_features": ["bridges", "data_room", "action_requests"],
    "is_active": true,
    "created_at": "2026-01-15T10:00:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z"
  }
}

Create Session

POST/api/v1/embed/sessions

Create an embed session for an end user (server-side).

API Keyembed:manage

Creates a short-lived session token for an end user. This is the server-side flow where your backend creates sessions on behalf of users. The end user is upserted by externalId.

Request Body

Field	Type	Required	Description
`externalId`	string	Yes	Your application’s user ID
`name`	string	No	End user’s display name
`email`	string	No	End user’s email address
`metadata`	object	No	Custom key-value metadata for the end user
`scopes`	string[]	No	Session scopes (default: `["bridges:read", "bridges:write"]`)
`allowedBridgeTypes`	string[]	No	Restrict which bridge types this session can manage
`ttlSeconds`	number	No	Session lifetime in seconds (min: 60, max: 86400, default: 3600)


curl -X POST "https://api.orderly-hub.com/api/v1/embed/sessions" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_12345",
    "name": "Store Owner",
    "email": "merchant@store.com",
    "scopes": ["bridges:read", "bridges:write", "orders:read"],
    "ttlSeconds": 7200
  }'

Response (201)


{
  "data": {
    "token": "est_a1b2c3d4...",
    "sessionId": "uuid",
    "expiresAt": "2026-01-15T12:30:00.000Z",
    "scopes": ["bridges:read", "bridges:write", "orders:read"],
    "enabledFeatures": ["bridges", "data_room"],
    "endUser": {
      "id": "uuid",
      "externalId": "user_12345",
      "name": "Store Owner",
      "email": "merchant@store.com"
    }
  }
}

Revoke Session

DELETE/api/v1/embed/sessions/:id

Revoke an active embed session.

API Keyembed:manage

Immediately revokes an embed session, invalidating its token. The end user will need a new session to continue.


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

Response


{
  "success": true
}

List Bridges

GET/api/v1/embed/bridges

List all bridges for the authenticated end user.

Embed Sessionbridges:read

Returns bridges belonging to the current end user, scoped by the embed session.


curl -X GET "https://api.orderly-hub.com/api/v1/embed/bridges" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "name": "My Shopify Store",
      "type": "shopify",
      "status": "active",
      "last_sync_at": "2026-01-15T10:00:00.000Z",
      "error_message": null,
      "created_at": "2026-01-10T08:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

Create Bridge

POST/api/v1/embed/bridges

Create a new bridge for the authenticated end user.

Embed Sessionbridges:write

Creates a new bridge integration for the end user. The bridge type must be allowed by both the session and the embed config. If maxBridgesPerUser is set in config settings, that limit is enforced.

Request Body

Field	Type	Required	Description
`type`	string	Yes	Bridge type ID (e.g., `shopify`, `shipstation`)
`name`	string	Yes	Display name for the bridge
`config`	object	Yes	Bridge configuration (API keys, credentials, etc.)


curl -X POST "https://api.orderly-hub.com/api/v1/embed/bridges" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "shipstation",
    "name": "My ShipStation",
    "config": {
      "apiKey": "ss_abc123",
      "apiSecret": "ss_secret456"
    }
  }'

Response (201)


{
  "data": {
    "id": "uuid",
    "organization_id": "uuid",
    "type": "shipstation",
    "name": "My ShipStation",
    "config": { "apiKey": "ss_abc123", "apiSecret": "ss_secret456" },
    "status": "active",
    "end_user_id": "uuid",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z"
  }
}

Update Bridge

PATCH/api/v1/embed/bridges/:id

Update a bridge owned by the authenticated end user.

Embed Sessionbridges:write

Updates an existing bridge. Config fields are merged with the existing config (shallow merge).

Request Body

Field	Type	Description
`name`	string	Updated display name
`status`	string	New status
`config`	object	Config fields to merge with existing config


curl -X PATCH "https://api.orderly-hub.com/api/v1/embed/bridges/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated ShipStation",
    "config": { "apiKey": "ss_new_key" }
  }'

Response


{
  "data": {
    "id": "uuid",
    "name": "Updated ShipStation",
    "type": "shipstation",
    "status": "active",
    "config": { "apiKey": "ss_new_key", "apiSecret": "ss_secret456" },
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T11:00:00.000Z"
  }
}

Delete Bridge

DELETE/api/v1/embed/bridges/:id

Delete a bridge owned by the authenticated end user.

Embed Sessionbridges:write

Permanently deletes a bridge and its associated data. This cannot be undone.


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

Response


{
  "success": true
}

Test Bridge Connection

POST/api/v1/embed/bridges/:id/test

Test the connection for a bridge.

Embed Sessionbridges:read

Tests the bridge connection by calling the bridge service’s /test endpoint with the stored config. Returns success or failure with a message.


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

Response


{
  "success": true,
  "message": "Connection successful"
}

Start Shopify OAuth

POST/api/v1/embed/bridges/shopify/oauth/start

Initiate the Shopify OAuth flow for the authenticated end user.

Embed Sessionbridges:write

Starts the Shopify OAuth authorization flow. Creates a pending bridge record and returns the authorization URL to redirect the end user to. The bridge type shopify must be allowed in the embed config and session.

Request Body

Field	Type	Required	Description
`shopDomain`	string	Yes	The Shopify store domain (e.g., `mystore` or `mystore.myshopify.com`)
`name`	string	No	Display name for the bridge (defaults to `Shopify - {shop}`)


curl -X POST "https://api.orderly-hub.com/api/v1/embed/bridges/shopify/oauth/start" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{
    "shopDomain": "mystore.myshopify.com"
  }'

Response


{
  "data": {
    "bridgeId": "uuid",
    "authUrl": "https://orderly-bridge-shopify.vercel.app/oauth/authorize?shop=mystore.myshopify.com&state=..."
  }
}

List Bridge Types

GET/api/v1/embed/bridge-types

List available bridge types for the authenticated end user.

Embed Session

Returns bridge types available to the end user, filtered by both the embed config and session-level allowed types.


curl -X GET "https://api.orderly-hub.com/api/v1/embed/bridge-types" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    {
      "id": "shopify",
      "name": "Shopify",
      "description": "Connect your Shopify store",
      "icon": "shopify-icon",
      "category": "ecommerce",
      "auth_methods": ["oauth", "api_key"],
      "config_fields": [...],
      "webhook_support": true,
      "docs_url": "https://docs.orderly-hub.com/bridges/shopify"
    }
  ]
}

List End Users

GET/api/v1/embed/users

List all end users for the organization.

API Keyembed:manage

Returns a paginated list of end users with their bridge counts.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20)


curl -X GET "https://api.orderly-hub.com/api/v1/embed/users?page=1&limit=20" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "external_id": "user_12345",
      "name": "Store Owner",
      "email": "merchant@store.com",
      "metadata": {},
      "bridge_count": 2,
      "created_at": "2026-01-10T08:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3,
    "hasMore": true
  }
}

Get End User

GET/api/v1/embed/users/:id

Retrieve a single end user with their bridges.

API Keyembed:manage

Returns an end user and their associated bridges.


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

Response


{
  "data": {
    "id": "uuid",
    "organization_id": "uuid",
    "external_id": "user_12345",
    "name": "Store Owner",
    "email": "merchant@store.com",
    "metadata": {},
    "created_at": "2026-01-10T08:00:00.000Z",
    "updated_at": "2026-01-15T10:00:00.000Z",
    "bridges": [
      {
        "id": "uuid",
        "name": "My Shopify Store",
        "type": "shopify",
        "status": "active",
        "last_sync_at": "2026-01-15T10:00:00.000Z",
        "created_at": "2026-01-10T08:00:00.000Z"
      }
    ]
  }
}

Delete End User

DELETE/api/v1/embed/users/:id

Delete an end user and revoke all their sessions.

API Keyembed:manage

Revokes all sessions for the end user, then deletes the user record. Associated bridges will have their end_user_id set to null.


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

Response


{
  "success": true
}

List Events

GET/api/v1/embed/events

List embed events for the organization.

API Keyembed:manage

Returns a paginated, filterable log of embed events (session created, bridge connected, etc.).

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 50)
`event_type`	string	Filter by event type (e.g., `session.created`, `bridge.created`)
`end_user_id`	string	Filter by end user ID
`from`	string	ISO 8601 date — events created after this time
`to`	string	ISO 8601 date — events created before this time


curl -X GET "https://api.orderly-hub.com/api/v1/embed/events?event_type=bridge.created&limit=20" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "organization_id": "uuid",
      "end_user_id": "uuid",
      "session_id": "uuid",
      "event_type": "bridge.created",
      "resource_type": "bridge",
      "resource_id": "uuid",
      "metadata": { "type": "shopify", "name": "My Shopify Store" },
      "ip_address": "203.0.113.1",
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "totalPages": 8,
    "hasMore": true
  }
}

List Orders (Data Room)

GET/api/v1/embed/orders

List orders for the authenticated end user.

Embed Sessionorders:read

Returns a paginated list of orders belonging to the end user. Requires the data_room feature to be enabled.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 50)
`status`	string	Filter by order status
`search`	string	Search by order number or external ID


curl -X GET "https://api.orderly-hub.com/api/v1/embed/orders?status=pending&limit=20" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "order_number": "1001",
      "external_id": "ext_123",
      "status": "pending",
      "fulfillment_status": "unfulfilled",
      "payment_status": "paid",
      "customer": { "name": "Jane Doe", "email": "jane@example.com" },
      "totals": { "subtotal": 45.00, "tax": 4.99, "total": 49.99 },
      "currency": "USD",
      "ordered_at": "2026-01-15T10:30:00.000Z",
      "bridge_id": "uuid",
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 85,
    "totalPages": 5,
    "hasMore": true
  }
}

Get Order (Data Room)

GET/api/v1/embed/orders/:id

Retrieve a single order with activities.

Embed Sessionorders:read

Returns the full order including line items, shipping address, and the most recent 50 activity entries. Requires the data_room feature.


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

Response


{
  "data": {
    "id": "uuid",
    "order_number": "1001",
    "external_id": "ext_123",
    "status": "pending",
    "fulfillment_status": "unfulfilled",
    "payment_status": "paid",
    "customer": { "name": "Jane Doe", "email": "jane@example.com" },
    "line_items": [
      { "title": "Widget", "quantity": 2, "price": 22.50 }
    ],
    "shipping_address": {
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "90210",
      "country": "US"
    },
    "totals": { "subtotal": 45.00, "tax": 4.99, "total": 49.99 },
    "currency": "USD",
    "tags": [],
    "notes": null,
    "ordered_at": "2026-01-15T10:30:00.000Z",
    "bridge_id": "uuid",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z",
    "activities": [
      {
        "id": "uuid",
        "activity_type": "status_change",
        "title": "Order created",
        "description": "Synced from Shopify",
        "actor_type": "system",
        "metadata": {},
        "created_at": "2026-01-15T10:30:00.000Z"
      }
    ]
  }
}

List Shipments (Data Room)

GET/api/v1/embed/shipments

List shipments for the authenticated end user.

Embed Sessionshipments:read

Returns a paginated list of shipments belonging to the end user. Requires the data_room feature.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 50)
`status`	string	Filter by shipment status


curl -X GET "https://api.orderly-hub.com/api/v1/embed/shipments?status=in_transit" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "external_id": "shp_ext_123",
      "tracking_number": "1Z999AA10123456784",
      "carrier": "ups",
      "service": "ground",
      "status": "in_transit",
      "ship_date": "2026-01-15",
      "estimated_delivery": "2026-01-20",
      "actual_delivery": null,
      "weight": { "value": 2.5, "unit": "lb" },
      "dimensions": { "length": 12, "width": 8, "height": 6, "unit": "in" },
      "bridge_id": "uuid",
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-01-16T14:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 32,
    "totalPages": 2,
    "hasMore": true
  }
}

Get Shipment (Data Room)

GET/api/v1/embed/shipments/:id

Retrieve a single shipment with tracking checkpoints.

Embed Sessionshipments:read

Returns the full shipment including origin/destination addresses and tracking checkpoints. Requires the data_room feature.


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

Response


{
  "data": {
    "id": "uuid",
    "external_id": "shp_ext_123",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups",
    "service": "ground",
    "status": "in_transit",
    "ship_date": "2026-01-15",
    "estimated_delivery": "2026-01-20",
    "actual_delivery": null,
    "weight": { "value": 2.5, "unit": "lb" },
    "dimensions": { "length": 12, "width": 8, "height": 6, "unit": "in" },
    "ship_from": { "city": "Los Angeles", "state": "CA", "country": "US" },
    "ship_to": { "city": "New York", "state": "NY", "country": "US" },
    "bridge_id": "uuid",
    "created_at": "2026-01-15T10:30:00.000Z",
    "updated_at": "2026-01-16T14:00:00.000Z",
    "checkpoints": [
      {
        "id": "uuid",
        "status": "in_transit",
        "status_detail": "Departed facility",
        "location": "Chicago, IL",
        "city": "Chicago",
        "state": "IL",
        "country": "US",
        "postal_code": "60601",
        "latitude": 41.8781,
        "longitude": -87.6298,
        "checkpoint_time": "2026-01-16T08:00:00.000Z",
        "carrier_status_code": "DP",
        "created_at": "2026-01-16T08:05:00.000Z"
      }
    ]
  }
}

Get Tracking

GET/api/v1/embed/tracking/:shipmentId

Get tracking details for a shipment.

Embed Sessiontracking:read

Returns shipment tracking info with checkpoints in chronological order (oldest first). Requires the data_room feature.


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

Response


{
  "data": {
    "id": "uuid",
    "tracking_number": "1Z999AA10123456784",
    "carrier": "ups",
    "service": "ground",
    "status": "in_transit",
    "ship_date": "2026-01-15",
    "estimated_delivery": "2026-01-20",
    "actual_delivery": null,
    "checkpoints": [
      {
        "id": "uuid",
        "status": "picked_up",
        "status_detail": "Picked up by carrier",
        "location": "Los Angeles, CA",
        "city": "Los Angeles",
        "state": "CA",
        "country": "US",
        "postal_code": "90001",
        "latitude": 34.0522,
        "longitude": -118.2437,
        "checkpoint_time": "2026-01-15T14:00:00.000Z",
        "carrier_status_code": "PU"
      },
      {
        "id": "uuid",
        "status": "in_transit",
        "status_detail": "Departed facility",
        "location": "Chicago, IL",
        "city": "Chicago",
        "state": "IL",
        "country": "US",
        "postal_code": "60601",
        "latitude": 41.8781,
        "longitude": -87.6298,
        "checkpoint_time": "2026-01-16T08:00:00.000Z",
        "carrier_status_code": "DP"
      }
    ]
  }
}

Create Action Request

POST/api/v1/embed/action-requests

Create an action request for an order.

Embed Sessionactions:write

Allows an end user to request an action on one of their orders (cancel, hold, expedite, etc.). Requires the action_requests feature. Requests expire after 7 days.

Request Body

Field	Type	Required	Description
`orderId`	string (UUID)	Yes	The order to request action on
`actionType`	string	Yes	One of: `cancel`, `hold`, `expedite`, `address_change`, `note`, `other`
`title`	string	Yes	Short title (max 200 chars)
`description`	string	No	Detailed description (max 2000 chars)
`requestedChanges`	object	No	Structured change data (e.g., new address)


curl -X POST "https://api.orderly-hub.com/api/v1/embed/action-requests" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "actionType": "cancel",
    "title": "Cancel order - customer changed mind",
    "description": "Customer called to cancel before shipment."
  }'

Response (201)


{
  "data": {
    "id": "uuid",
    "organization_id": "uuid",
    "end_user_id": "uuid",
    "order_id": "uuid",
    "action_type": "cancel",
    "title": "Cancel order - customer changed mind",
    "description": "Customer called to cancel before shipment.",
    "status": "pending",
    "requested_changes": null,
    "expires_at": "2026-01-22T10:30:00.000Z",
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

List Action Requests

GET/api/v1/embed/action-requests

List action requests for the authenticated end user.

Embed Sessionactions:read

Returns paginated action requests belonging to the end user. Requires the action_requests feature.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 50)
`status`	string	Filter by status (e.g., `pending`, `approved`, `denied`)


curl -X GET "https://api.orderly-hub.com/api/v1/embed/action-requests?status=pending" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "order_id": "uuid",
      "action_type": "cancel",
      "title": "Cancel order - customer changed mind",
      "status": "pending",
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 3,
    "totalPages": 1,
    "hasMore": false
  }
}

Get Action Request

GET/api/v1/embed/action-requests/:id

Retrieve a single action request.

Embed Sessionactions:read

Returns a single action request by ID. Requires the action_requests feature.


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

Response


{
  "data": {
    "id": "uuid",
    "organization_id": "uuid",
    "end_user_id": "uuid",
    "order_id": "uuid",
    "action_type": "cancel",
    "title": "Cancel order - customer changed mind",
    "description": "Customer called to cancel before shipment.",
    "status": "pending",
    "requested_changes": null,
    "resolution_note": null,
    "resolved_by": null,
    "resolved_at": null,
    "expires_at": "2026-01-22T10:30:00.000Z",
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Cancel Action Request

DELETE/api/v1/embed/action-requests/:id

Cancel a pending action request.

Embed Sessionactions:write

Cancels a pending action request. Only requests with pending status can be cancelled. Requires the action_requests feature.


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

Response


{
  "success": true
}

List Action Request Queue (Dashboard)

GET/api/v1/embed/action-requests/queue

List all action requests for the organization (dashboard view).

API Keyembed:manage

Returns a paginated queue of action requests across all end users, with end user details included. Used by the 3PL dashboard to review and resolve requests.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 50)
`status`	string	Filter by status (default: `pending`, use `all` for all statuses)


curl -X GET "https://api.orderly-hub.com/api/v1/embed/action-requests/queue?status=pending" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "order_id": "uuid",
      "action_type": "cancel",
      "title": "Cancel order - customer changed mind",
      "status": "pending",
      "end_users": {
        "external_id": "user_12345",
        "name": "Store Owner",
        "email": "merchant@store.com"
      },
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1,
    "hasMore": false
  }
}

Resolve Action Request (Dashboard)

PATCH/api/v1/embed/action-requests/:id/resolve

Approve or deny a pending action request.

API Keyembed:manage

Resolves a pending action request by approving or denying it. Only pending requests can be resolved.

Request Body

Field	Type	Required	Description
`status`	string	Yes	Resolution: `approved` or `denied`
`resolutionNote`	string	No	Optional note explaining the decision (max 2000 chars)


curl -X PATCH "https://api.orderly-hub.com/api/v1/embed/action-requests/550e8400-e29b-41d4-a716-446655440000/resolve" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "approved",
    "resolutionNote": "Order cancelled per customer request."
  }'

Response


{
  "data": {
    "id": "uuid",
    "order_id": "uuid",
    "action_type": "cancel",
    "title": "Cancel order - customer changed mind",
    "status": "approved",
    "resolution_note": "Order cancelled per customer request.",
    "resolved_by": "uuid",
    "resolved_at": "2026-01-15T11:00:00.000Z",
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

List Alert Rules

GET/api/v1/embed/alerts/rules

List alert rules for the authenticated end user.

Embed Sessionalerts:read

Returns all alert rules belonging to the end user. Requires the smart_alerts feature.


curl -X GET "https://api.orderly-hub.com/api/v1/embed/alerts/rules" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "name": "Shipment Exception Alert",
      "description": "Alert when a shipment has an exception",
      "event_type": "shipment.exception",
      "condition": { "carrier": "ups" },
      "delivery_method": "both",
      "webhook_url": "https://myapp.com/webhooks/alerts",
      "cooldown_minutes": 60,
      "is_active": true,
      "created_at": "2026-01-10T08:00:00.000Z"
    }
  ]
}

Create Alert Rule

POST/api/v1/embed/alerts/rules

Create a new alert rule.

Embed Sessionalerts:write

Creates a new alert rule for the end user. Maximum of 20 rules per end user. Requires the smart_alerts feature.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Rule name (max 100 chars)
`description`	string	No	Rule description (max 500 chars)
`eventType`	string	Yes	Event type to trigger on
`condition`	object	Yes	Condition object for matching
`deliveryMethod`	string	No	`in_app`, `webhook`, or `both` (default: `in_app`)
`webhookUrl`	string	No	Webhook URL for delivery (required if method is `webhook` or `both`)
`cooldownMinutes`	number	No	Minimum minutes between alerts (min: 5, max: 1440, default: 60)


curl -X POST "https://api.orderly-hub.com/api/v1/embed/alerts/rules" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Delivery Exception Alert",
    "eventType": "shipment.exception",
    "condition": { "carrier": "ups" },
    "deliveryMethod": "both",
    "webhookUrl": "https://myapp.com/webhooks/alerts",
    "cooldownMinutes": 30
  }'

Response (201)


{
  "data": {
    "id": "uuid",
    "name": "Delivery Exception Alert",
    "event_type": "shipment.exception",
    "condition": { "carrier": "ups" },
    "delivery_method": "both",
    "webhook_url": "https://myapp.com/webhooks/alerts",
    "cooldown_minutes": 30,
    "is_active": true,
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Update Alert Rule

PATCH/api/v1/embed/alerts/rules/:id

Update an existing alert rule.

Embed Sessionalerts:write

Updates an alert rule. Requires the smart_alerts feature.

Request Body

Field	Type	Description
`name`	string	Updated name
`description`	string	Updated description
`isActive`	boolean	Enable or disable the rule
`condition`	object	Updated condition
`deliveryMethod`	string	Updated delivery method
`webhookUrl`	string	Updated webhook URL
`cooldownMinutes`	number	Updated cooldown


curl -X PATCH "https://api.orderly-hub.com/api/v1/embed/alerts/rules/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Response


{
  "data": {
    "id": "uuid",
    "name": "Delivery Exception Alert",
    "is_active": false,
    "updated_at": "2026-01-15T11:00:00.000Z"
  }
}

Delete Alert Rule

DELETE/api/v1/embed/alerts/rules/:id

Delete an alert rule.

Embed Sessionalerts:write

Permanently deletes an alert rule. Requires the smart_alerts feature.


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

Response


{
  "success": true
}

List Alert Notifications

GET/api/v1/embed/alerts/notifications

List alert notifications for the authenticated end user.

Embed Sessionalerts:read

Returns paginated alert notifications (excluding dismissed). Requires the smart_alerts feature.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 50)
`unread`	string	Set to `true` to only return unread notifications


curl -X GET "https://api.orderly-hub.com/api/v1/embed/alerts/notifications?unread=true" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "rule_id": "uuid",
      "event_type": "shipment.exception",
      "title": "Shipment exception detected",
      "message": "Shipment 1Z999AA1 has an exception with UPS.",
      "is_read": false,
      "is_dismissed": false,
      "created_at": "2026-01-15T10:30:00.000Z"
    }
  ],
  "unreadCount": 3,
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12,
    "totalPages": 1,
    "hasMore": false
  }
}

Update Alert Notification

PATCH/api/v1/embed/alerts/notifications/:id

Mark a notification as read or dismissed.

Embed Sessionalerts:read

Updates the read/dismissed state of a notification. Requires the smart_alerts feature.

Request Body

Field	Type	Description
`isRead`	boolean	Mark as read/unread
`isDismissed`	boolean	Dismiss the notification


curl -X PATCH "https://api.orderly-hub.com/api/v1/embed/alerts/notifications/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{ "isRead": true }'

Response


{
  "data": {
    "id": "uuid",
    "is_read": true,
    "is_dismissed": false,
    "updated_at": "2026-01-15T11:00:00.000Z"
  }
}

List Webhook Event Types

GET/api/v1/embed/webhooks/event-types

List available webhook event types.

Embed Sessionwebhooks:read

Returns the list of event types that end user webhooks can subscribe to. Requires the end_user_webhooks feature.


curl -X GET "https://api.orderly-hub.com/api/v1/embed/webhooks/event-types" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    "order.created",
    "order.updated",
    "order.status_changed",
    "shipment.created",
    "shipment.shipped",
    "shipment.delivered",
    "shipment.exception",
    "tracking.updated",
    "bridge.connected",
    "bridge.disconnected",
    "bridge.sync_completed"
  ]
}

List Webhooks

GET/api/v1/embed/webhooks

List webhooks for the authenticated end user.

Embed Sessionwebhooks:read

Returns all webhooks belonging to the end user. Requires the end_user_webhooks feature.


curl -X GET "https://api.orderly-hub.com/api/v1/embed/webhooks" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "url": "https://myapp.com/webhooks/orderly",
      "description": "Production webhook",
      "is_active": true,
      "events": ["order.created", "shipment.shipped"],
      "last_success_at": "2026-01-15T10:00:00.000Z",
      "last_failure_at": null,
      "consecutive_failures": 0,
      "disabled_reason": null,
      "created_at": "2026-01-10T08:00:00.000Z",
      "updated_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

Create Webhook

POST/api/v1/embed/webhooks

Create a new webhook endpoint.

Embed Sessionwebhooks:write

Creates a new webhook for the end user. Maximum of 5 webhooks per end user. Requires the end_user_webhooks feature. Payloads are signed with HMAC-SHA256 using the provided secret (via the X-Orderly-Signature header).

Request Body

Field	Type	Required	Description
`url`	string	Yes	Webhook endpoint URL
`secret`	string	No	Signing secret for HMAC-SHA256 verification (min 16, max 128 chars)
`description`	string	No	Description (max 200 chars)
`events`	string[]	Yes	Event types to subscribe to (at least one)


curl -X POST "https://api.orderly-hub.com/api/v1/embed/webhooks" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://myapp.com/webhooks/orderly",
    "secret": "whsec_a1b2c3d4e5f6g7h8",
    "description": "Production webhook",
    "events": ["order.created", "shipment.shipped", "shipment.delivered"]
  }'

Response (201)


{
  "data": {
    "id": "uuid",
    "url": "https://myapp.com/webhooks/orderly",
    "description": "Production webhook",
    "is_active": true,
    "events": ["order.created", "shipment.shipped", "shipment.delivered"],
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

Update Webhook

PATCH/api/v1/embed/webhooks/:id

Update an existing webhook.

Embed Sessionwebhooks:write

Updates a webhook. Re-enabling a webhook (isActive: true) resets the failure counter. Requires the end_user_webhooks feature.

Request Body

Field	Type	Description
`url`	string	Updated endpoint URL
`description`	string	Updated description
`events`	string[]	Updated event subscriptions
`isActive`	boolean	Enable or disable the webhook


curl -X PATCH "https://api.orderly-hub.com/api/v1/embed/webhooks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["order.created", "order.updated", "shipment.shipped"],
    "isActive": true
  }'

Response


{
  "data": {
    "id": "uuid",
    "url": "https://myapp.com/webhooks/orderly",
    "description": "Production webhook",
    "is_active": true,
    "events": ["order.created", "order.updated", "shipment.shipped"],
    "last_success_at": "2026-01-15T10:00:00.000Z",
    "last_failure_at": null,
    "consecutive_failures": 0,
    "disabled_reason": null,
    "created_at": "2026-01-10T08:00:00.000Z",
    "updated_at": "2026-01-15T11:00:00.000Z"
  }
}

Delete Webhook

DELETE/api/v1/embed/webhooks/:id

Delete a webhook endpoint.

Embed Sessionwebhooks:write

Permanently deletes a webhook. Requires the end_user_webhooks feature.


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

Response


{
  "success": true
}

Test Webhook

POST/api/v1/embed/webhooks/:id/test

Send a test event to a webhook endpoint.

Embed Sessionwebhooks:write

Sends a webhook.test event to the webhook URL and records the delivery result. Requires the end_user_webhooks feature.


curl -X POST "https://api.orderly-hub.com/api/v1/embed/webhooks/550e8400-e29b-41d4-a716-446655440000/test" \
  -H "Authorization: Bearer est_..."

Response


{
  "success": true,
  "statusCode": 200
}

List Webhook Deliveries

GET/api/v1/embed/webhooks/:id/deliveries

List recent delivery attempts for a webhook.

Embed Sessionwebhooks:read

Returns the last 50 delivery attempts for a webhook, ordered by most recent first. Requires the end_user_webhooks feature.


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

Response


{
  "data": [
    {
      "id": "uuid",
      "event_type": "order.created",
      "response_status": 200,
      "success": true,
      "error": null,
      "created_at": "2026-01-15T10:30:00.000Z"
    },
    {
      "id": "uuid",
      "event_type": "webhook.test",
      "response_status": null,
      "success": false,
      "error": "Connection refused",
      "created_at": "2026-01-15T10:00:00.000Z"
    }
  ]
}

Create Tracking Page

POST/api/v1/embed/tracking-pages

Create a branded tracking page for a shipment.

Embed Sessiontracking:read

Generates a shareable tracking page token for a shipment. If a token already exists for the shipment, the existing one is returned. Requires the branded_tracking feature.

Request Body

Field	Type	Required	Description
`shipmentId`	string (UUID)	Yes	The shipment to create a tracking page for


curl -X POST "https://api.orderly-hub.com/api/v1/embed/tracking-pages" \
  -H "Authorization: Bearer est_..." \
  -H "Content-Type: application/json" \
  -d '{
    "shipmentId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response (201)


{
  "data": {
    "id": "uuid",
    "token": "aBcDeFgHiJkLmNoPqRsTuVwX",
    "created_at": "2026-01-15T10:30:00.000Z"
  }
}

List Tracking Pages

GET/api/v1/embed/tracking-pages

List all tracking pages for the authenticated end user.

Embed Sessiontracking:read

Returns all tracking page tokens for the end user. Requires the branded_tracking feature.


curl -X GET "https://api.orderly-hub.com/api/v1/embed/tracking-pages" \
  -H "Authorization: Bearer est_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "token": "aBcDeFgHiJkLmNoPqRsTuVwX",
      "shipment_id": "uuid",
      "is_active": true,
      "view_count": 14,
      "last_viewed_at": "2026-01-15T09:00:00.000Z",
      "created_at": "2026-01-10T08:00:00.000Z"
    }
  ]
}

Revoke Tracking Page

DELETE/api/v1/embed/tracking-pages/:id

Revoke a branded tracking page.

Embed Sessiontracking:read

Deactivates a tracking page token. The public URL will return a 410 Gone response. Requires the branded_tracking feature.


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

Response


{
  "success": true
}

View Tracking Page (Public)

GET/api/v1/embed/tracking-pages/view/:token

View a branded tracking page by token.

Public

Public endpoint that returns shipment tracking data and branding for a tracking page. No authentication required. Returns safe fields only (no PII). Returns 410 Gone if the page has been revoked or expired.


curl -X GET "https://api.orderly-hub.com/api/v1/embed/tracking-pages/view/aBcDeFgHiJkLmNoPqRsTuVwX"

Response


{
  "data": {
    "shipment": {
      "id": "uuid",
      "tracking_number": "1Z999AA10123456784",
      "carrier": "ups",
      "service": "ground",
      "status": "in_transit",
      "ship_date": "2026-01-15",
      "estimated_delivery": "2026-01-20",
      "actual_delivery": null
    },
    "checkpoints": [
      {
        "id": "uuid",
        "status": "picked_up",
        "status_detail": "Picked up by carrier",
        "location": "Los Angeles, CA",
        "city": "Los Angeles",
        "state": "CA",
        "country": "US",
        "latitude": 34.0522,
        "longitude": -118.2437,
        "checkpoint_time": "2026-01-15T14:00:00.000Z"
      },
      {
        "id": "uuid",
        "status": "in_transit",
        "status_detail": "Departed facility",
        "location": "Chicago, IL",
        "city": "Chicago",
        "state": "IL",
        "country": "US",
        "latitude": 41.8781,
        "longitude": -87.6298,
        "checkpoint_time": "2026-01-16T08:00:00.000Z"
      }
    ],
    "branding": {
      "primary_color": "#4F46E5",
      "logo_url": "https://...",
      "company_name": "Acme Fulfillment"
    }
  }
}