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:

  1. Extracts `uid` from the state parameter
  2. Retrieves stored OAuth credentials (from `shopify_oauth_sessions` or env vars)
  3. Exchanges authorization code for a permanent access token
  4. Registers 5 Shopify webhooks
  5. Saves store to Firestore `stores` collection
  6. 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

Register a store for native Shopify webhooks (user configures webhooks manually in Shopify Admin).

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"
}