Shopify Integration Endpoints

Endpoints for connecting Shopify stores via OAuth, manual tokens, or native webhooks.

OAuth Init

Start the Shopify OAuth flow. Stores credentials and returns the Shopify authorization URL.

POST /api/shopify/oauth-init

Auth: Firebase ID Token

Request Body:

ParameterTypeRequiredDescription

shopstringYesShopify store domain

clientIdstringYesShopify App Client ID

clientSecretstringYesShopify App Client Secret

Response:

{
  "success": true,
  "authUrl": "https://mystore.myshopify.com/admin/oauth/authorize?client_id=...&redirect_uri=...&scope=...&state=...",
  "shop": "mystore.myshopify.com"
}

OAuth Callback

Handles the OAuth redirect from Shopify. Exchanges the authorization code for an access token and registers webhooks.

GET /api/shopify/callback?code=<code>&shop=<shop>&state=<state>

Auth: Public (called by Shopify)

Query Parameters:

ParameterTypeRequiredDescription

codestringYesAuthorization code from Shopify

shopstringYesShopify store domain

statestringYesOAuth state (`{uid}___{nonce}`)

Behavior:

Extracts `uid` from the state parameter
Retrieves stored OAuth credentials (from `shopify_oauth_sessions` or env vars)
Exchanges authorization code for a permanent access token
Registers 5 Shopify webhooks
Saves store to Firestore `stores` collection
Redirects to `/dashboard/connect-store/success?shop={shop}`

Webhooks registered: `orders/create`, `orders/paid`, `fulfillments/create`, `orders/cancelled`, `refunds/create`

Manual Connect

Connect a Shopify store using a pre-generated Admin API access token (without OAuth).

POST /api/shopify/manual-connect

Auth: Firebase ID Token

Request Body:

ParameterTypeRequiredDescription

shopstringYesShopify store domain

accessTokenstringYesShopify Admin API access token (starts with `shpat_`)

Response:

{
  "success": true,
  "message": "Store connected successfully!",
  "shop": "mystore.myshopify.com",
  "webhooksRegistered": 5,
  "shopifyVerified": true,
  "webhooksSkipped": false
}

Native Connect

POST /api/shopify/native-connect

Auth: Firebase ID Token

Request Body:

ParameterTypeRequiredDescription

shopstringYesShopify store domain

Response:

{
  "success": true,
  "message": "Store registered for Native Webhooks setup!",
  "shop": "mystore.myshopify.com"
}

Webhook Receiver

Receives Shopify webhook events and sends WhatsApp notifications based on user-configured templates.

POST /api/shopify/webhook?uid=<uid>&shop=<shop>

Auth: Public (called by Shopify)

Headers:

x-shopify-topic: The event type (e.g. `orders/create`)
x-shopify-shop-domain: The Shopify store domain

Query Parameters:

ParameterTypeRequiredDescription

uidstringNoUser ID (resolved from store if omitted)

shopstringNoShop domain (used for lookup if uid missing)

Request Body: Raw Shopify webhook JSON payload (varies by topic)

Supported Topics & Template Mapping:

TopicDefault Message

orders/create"Hello {customerName}! Thank you for your order #{orderId}..."

orders/paid"Your order #{orderId} has been paid successfully..."

fulfillments/create"Your order #{orderId} has been shipped! Tracking: ..."

orders/cancelled"Your order #{orderId} has been cancelled..."

refunds/create"A refund has been processed for your order #{orderId}..."

Template placeholders: `{customerName}`, `{orderId}`, `{totalPrice}`, `{currency}`, `{items_list}`, `{trackingNumber}`, `{store_name}` and more.

Health Check

Verify the Shopify integration is configured and operational.

GET /api/shopify/test

Auth: None (public)

Response:

{
  "status": "ok",
  "message": "API route is working",
  "timestamp": "2026-07-02T12:00:00.000Z"
}