Integrations API: Connect Commerce Platforms

The Integrations API lets you connect Synq to third-party commerce platforms — such as Shopify, WooCommerce, or Amazon — using an OAuth flow. Once connected, you can push product data to those platforms and receive inbound webhook events from them. Synq handles the credential storage and connection lifecycle; you only need to store the resulting connection_id.

All requests except POST /unified/webhook require three headers: Authorization: Bearer YOUR_TOKEN, X-Tenant-ID: YOUR_TENANT_ID, and X-Org-ID: YOUR_ORG_ID. The webhook endpoint is public and uses HMAC signature verification instead.

Get OAuth authorization URL

Generate the OAuth URL your users should visit to authorize a new integration. Redirect them to the returned auth_url; Synq handles the OAuth callback automatically and generates a connection_id you can save with the callback endpoint below. POST /api/v1/integrations/auth-url

Headers

Authorization

string

required

Bearer token from your authentication provider.

X-Tenant-ID

string

required

UUID of your tenant. This is embedded in the OAuth state parameter to tie the callback back to your account.

X-Org-ID

string

required

UUID of your organization.

Response

auth_url

string

The full OAuth authorization URL. Redirect your user’s browser to this URL to start the connection flow.

curl -X POST https://api.synq.app/api/v1/integrations/auth-url \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

Save a connection

After a user completes the OAuth flow, the provider returns a connection_id. Call this endpoint to persist that connection in Synq and activate background sync for the platform. POST /api/v1/integrations/callback

Headers

Authorization

string

required

Bearer token from your authentication provider.

X-Tenant-ID

string

required

UUID of your tenant.

X-Org-ID

string

required

UUID of your organization.

Body

connection_id

string

required

The connection_id returned by the OAuth provider after authorization completion.

Response

Returns 201 Created on success.

curl -X POST https://api.synq.app/api/v1/integrations/callback \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "conn_3Xabc...",
    "category": "commerce",
    "provider": "shopify"
  }'

List connections

Retrieve all active integrations for your tenant and organization. GET /api/v1/integrations/connections

Headers

Authorization

string

required

Bearer token from your authentication provider.

X-Tenant-ID

string

required

UUID of your tenant.

X-Org-ID

string

required

UUID of your organization.

Response

connections

array

Array of active connection objects.

Show Connection fields

string

Synq-internal UUID for this connection.

unified_connection_id

string

The provider connection_id issued during OAuth.

provider

string

Integration provider, e.g. shopify.

status

string

Connection status, e.g. ACTIVE.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-updated timestamp.

curl https://api.synq.app/api/v1/integrations/connections \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

Push a product to integrations

Enqueue an asynchronous job to push a product record to all active integrations for your tenant. The platform fans the job out to every connected provider in the background. POST /unified/sync/push/product

Headers

Authorization

string

required

Bearer token from your authentication provider.

X-Tenant-ID

string

required

UUID of your tenant.

X-Org-ID

string

required

UUID of your organization.

Body

productId

string

required

UUID of the Synq product to push.

action

string

required

The sync action to perform. Use UPSERT to create or update the product on the remote platform, or DELETE to remove it.

Response

Returns 202 Accepted immediately. The push job runs asynchronously.

status

string

Always queued on a successful 202 response.

curl -X POST https://api.synq.app/unified/sync/push/product \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "action": "UPSERT"
  }'

Inbound webhook

Receive real-time events from connected platforms (e.g. new Shopify orders, inventory updates). Synq verifies every inbound payload using an HMAC-SHA256 signature before processing it. POST /unified/webhook

This endpoint is public — it does not require Authorization, X-Tenant-ID, or X-Org-ID headers. Security is enforced entirely through the X-Unified-Signature HMAC header. Requests with an invalid or missing signature are rejected with 401 Unauthorized.

Headers

X-Unified-Signature

string

required

HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret. Synq rejects the request if this does not match.

Body

connection_id

string

required

The provider connection_id that originated this event. Must match an active connection in Synq.

event

string

required

Event type from the upstream platform, e.g. order.created or product.updated.

data

object

required

Raw event payload from the upstream platform.

Synq looks up the internal connection record matching connection_id, validates it is ACTIVE, and persists the event to the outbox for downstream processing. Returns 200 OK on success.

# In practice your platform sends this; shown here for testing
curl -X POST https://api.synq.app/unified/webhook \
  -H "Content-Type: application/json" \
  -H "X-Unified-Signature: <hmac-sha256-hex>" \
  -d '{
    "connection_id": "conn_3Xabc...",
    "event": "order.created",
    "data": {
      "external_order_id": "shopify-order-9001",
      "total": 205.27,
      "currency": "USD"
    }
  }'

UCP catalog feed

Retrieve a redirect to your tenant’s Unified Commerce Profile (UCP) catalog feed. This endpoint issues a 302 Found redirect to a static JSON-LD file that describes your full product catalog in a machine-readable format. It is designed for AI shopping agents and Merchant Center integrations that require a stable, authenticated URL to crawl your catalog without placing load on the primary API. GET /api/v1/ucp/catalog.json

Headers

Authorization

string

required

Bearer token from your authentication provider. The token must be linked to a valid tenant.

X-Tenant-ID

string

required

UUID of your tenant.

X-Org-ID

string

required

UUID of your organization.

Response

Returns 302 Found with a Location header pointing to your tenant’s catalog JSON-LD file. The redirect URL is dynamic and should not be cached — always call this endpoint to get the current feed URL.

curl -v https://api.synq.app/api/v1/ucp/catalog.json \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "X-Org-ID: YOUR_ORG_ID"

​Get OAuth authorization URL

​Headers

​Response

​Save a connection

​Headers

​Body

​Response

​List connections

​Headers

​Response

​Push a product to integrations

​Headers

​Body

​Response

​Inbound webhook

​Headers

​Body

​UCP catalog feed

​Headers

​Response

Get OAuth authorization URL

Headers

Response

Save a connection

Headers

Body

Response

List connections

Headers

Response

Push a product to integrations

Headers

Body

Response

Inbound webhook

Headers

Body

UCP catalog feed

Headers

Response