Tw Ecom Dtc Shopline

Shopline Integration Methodology

When to use this skill

• Syncing orders, products, members, or inventory between Shopline and an internal ERP / data warehouse
• Building a multi-step automation across mcp-shopline tools (e.g., order → invoice → logistics)
• Reconciling Shopline state against an external system (accounting, WMS, 電子發票 平台)
• Designing a promotion / coupon / flash-sale workflow that spans read + write tools
• Debugging unexpected behavior: missing orders, stale reads after writes, 403 on channel lookups

Do NOT use when

• You need the exact API schema for one endpoint — read the tool description or Shopline Open API docs directly
• The merchant is on Shopify, 91APP, Cyberbiz, or a non-Shopline platform — use tw-ecom-channel-strategy first
• The Shopline store is non-Taiwan (HK/SG/MY) — currency, invoice, and logistics assumptions in this skill are TWD + Taiwan-specific

Core concepts

Shopline is a SaaS commerce platform popular with Taiwan DTC and omnichannel brands. A single merchant account can own multiple shops (storefronts); each shop can sell through multiple channels (online + POS retail stores). mcp-shopline wraps Shopline Open API v1 into 143 tools (75 read, 68 write), all scoped to one API token = one merchant context.

Two axes matter when picking a tool:

• Read vs write. Write tools are prefixed [WRITE] in their descriptions and require an API token scope that permits mutation. Read tools are safe; write tools modify production data.
• Domain. Orders, Products & Inventory, Analytics, Customers, Categories & Promotions, Order Extended (returns/delivery/conversations/reviews), Store Settings. Analytics tools are pre-aggregated — prefer them over hand-rolling aggregations on top of query_orders.

Money is always TWD float. Dates are YYYY-MM-DD strings. Online orders use status confirmed; POS orders use completed — mixing them up silently drops half the data.

Decision tree

What is the user asking for?
│
├─ Aggregate metric (revenue, AOV, top products, trend)?
│    → Analytics / Orders summary tools
│      get_sales_summary · get_top_products · get_sales_trend
│      get_channel_comparison · get_rfm_analysis · get_promotion_roi
│
├─ Specific order / customer / product lookup?
│    → Read-detail tools
│      get_order_detail · get_customer_profile · get_product_variants
│
├─ Inventory question (stock, low-stock, warehouse)?
│    → Products & Inventory read tools
│      get_inventory_overview · get_low_stock_alerts ·
│      get_stock_by_warehouse · get_locked_inventory
│
├─ Promotion / coupon / flash sale?
│    ├─ Read  → list_promotions · get_promotion_detail ·
│    │          list_flash_price_campaigns · list_affiliate_campaigns
│    └─ Write → promotion write tools (12) — split into three sub-families:
│              flat promo · flash price · gift/add-on. See
│              references/tool-catalog.md for exact tool per family.
│
├─ Modify an order (status, tag, fulfill, cancel)?
│    → Order write tools (8) — require write scope
│
├─ Create/update customer, adjust store credits, group membership?
│    → Customer write tools (6)
│
└─ Configuration / debug (token scope, channels, payments, delivery)?
     → Store Settings read tools
       get_token_info (always start here when debugging permissions)
       list_channels · list_payments · list_delivery_options

Implementation guidance

Common multi-tool flows. For each, use the tool names below; see examples/sample_scenario.md for an end-to-end walkthrough.

Order sync (Shopline → internal ERP)

• Poll with query_orders on a date window; include BOTH confirmed (online) and completed (POS) statuses
• For each order, call get_order_detail for line items and get_order_transactions for payment records
• If delivery matters, call get_order_delivery — note: delivery has its own ID, only available after shipment executes
• Persist the order.channel.created_by_channel_name value, not just created_from, or you lose the physical store identity
• Checkpoint the high-water-mark date to avoid re-fetching; re-scan the last 24-48h each run to catch late status changes

Promotion setup and measurement

• Pre-check: list_promotions + search_promotions to avoid duplicate campaign names
• Create via the promotion write tool appropriate to type (flat promotion vs flash price vs gift-with-purchase vs add-on)
• After go-live, measure with get_promotion_analysis (effectiveness) + get_promotion_roi (lift vs baseline)
• For affiliate campaigns, use get_affiliate_campaign_usage — requires at least one order that used the campaign

Member / RFM sync

• Full membership sync: list_customers (paginated) → for each, get_customer_profile on demand (not in bulk — expensive)
• Segmentation: call get_rfm_analysis instead of computing from raw orders — it's pre-aggregated and respects Shopline's definition of a member
• For tier / points state: list_membership_tiers, list_member_point_rules, list_store_credits
• get_customer_lifecycle compares two periods' RFM to surface upgrades and churn

Inventory sync and replenishment

• Snapshot: get_inventory_overview (totals) + get_stock_by_warehouse (per-warehouse matrix)
• Operational signals: get_low_stock_alerts, get_locked_inventory (reserved by pending orders), get_slow_movers (excess stock)
• Transfer planning: get_stock_transfer_suggestions — server-side heuristic; treat output as suggestions not commands
• Replenishment: list_purchase_orders → get_purchase_order_detail; create via purchase-order write tools