E-Commerce Integrations

UniPulse connects with three e-commerce platforms to sync products, track orders, and attribute revenue to social media posts.

---

Supported Platforms

Platform	Auth Method	Sync Method	Webhooks	Revenue Attribution
Shopify	OAuth app installation	REST + Webhooks	Yes (native)	Yes (UTM)
WooCommerce	REST API consumer key/secret	REST + polling	Limited	Yes (UTM)
EasyOrders	API key	REST + polling	No	Yes (UTM)

---

API Endpoints

All e-commerce routes are under /api/v1/ecommerce:

Endpoint	Method	Description	Min Role
/api/v1/ecommerce/shopify	POST	Connect Shopify store	ADMIN
/api/v1/ecommerce/woocommerce	POST	Connect WooCommerce store	ADMIN
/api/v1/ecommerce/easyorders	POST	Connect EasyOrders store	ADMIN
/api/v1/ecommerce/products	GET	List synced products	EDITOR
/api/v1/ecommerce/templates	CRUD	Product post templates	EDITOR
/api/v1/ecommerce/sync	POST	Trigger manual sync	EDITOR

---

Shopify Integration

Connection Flow

Synced Data

Resource	Shopify API	Local Model	Sync Frequency
Products	GET /admin/api/products.json	EcommerceProduct	Webhook + periodic
Orders	GET /admin/api/orders.json	CommerceOrder + OrderLineItem	Webhook + periodic
Customers	GET /admin/api/customers.json	CommerceCustomer	Webhook + periodic

Webhooks (Real-Time)

Webhook Topic	Trigger	Processing
orders/create	New order placed	order-sync queue -> revenue-attribution queue
orders/updated	Order status change	order-sync queue
products/update	Product modified	ecommerce-sync queue
products/delete	Product removed	ecommerce-sync queue

---

WooCommerce Integration

Connection

Authentication	Details
Method	REST API consumer key + consumer secret
Base URL	https://{store-url}/wp-json/wc/v3/
Auth Header	Basic auth or query parameter

Synced Data

Resource	WooCommerce API	Sync Frequency
Products	GET /wp-json/wc/v3/products	Periodic polling (every 30 min)
Orders	GET /wp-json/wc/v3/orders	Periodic polling (every 15 min)
Customers	GET /wp-json/wc/v3/customers	Periodic polling (every 1 hour)

---

EasyOrders Integration

Connection

Authentication	Details
Method	API key in request header
Provided by	User from EasyOrders dashboard

Synced Data

Resource	Sync Frequency
Products	Periodic polling (every 30 min)
Orders	Periodic polling (every 15 min)

---

Sync Architecture

Queue	Purpose
ecommerce-sync	Syncs products and basic store data
order-sync	Syncs orders and line items
revenue-attribution	Matches orders to social posts via UTM parameters

---

Revenue Attribution

When a post is published with links, UTM parameters are automatically appended:

https://store.example.com/product?utm_source=instagram&utm_medium=social&utm_campaign=post_{postId}

When an order arrives with matching UTM parameters, the revenue-attribution queue creates a RevenueAttribution record linking the order to the originating post.

UTM Parameter	Value	Purpose
utm_source	Platform name (facebook, instagram, tiktok)	Identify source platform
utm_medium	social	Identify channel type
utm_campaign	post_{postId}	Link to specific post

---

Product Post Templates

The ProductPostTemplate model allows creating reusable templates that auto-generate post captions from product data:

// Template example
const template = {
  productId: 'prod_123',
  templateContent: '🛍 New arrival: {{productName}} - {{price}}! Shop now: {{productUrl}}',
};

---

Database Models

Model	Purpose
EcommerceStore	Store connection (provider, credentials, sync status)
EcommerceProduct	Synced product catalog
ProductPostTemplate	Product-to-post templates
CommerceCustomer	Customer records
CommerceOrder	Order records
OrderLineItem	Order line items
RevenueAttribution	Post-to-order revenue attribution
PostRevenue	Aggregated revenue per post
CouponGenerated	AI-generated discount coupons

---

Cross-Reference

• Commerce Routes -- commerce API endpoints
• Queue System -- ecommerce-sync, order-sync, revenue-attribution queues
• Schema Overview -- e-commerce models
• Data Flow -- revenue attribution flow diagram