Product Tag Sync

Overview

Refresh product tags, vendor, and status from Shopify into product.tags — updating product attributes (tags, vendor, status) to power tag analytics and UI filters, without requiring a full data acquisition workflow (ProcedureExecution).

Goal: Ensure product attribute accuracy independently of the daily bulk sync.

API endpoints

Method	Path	Spec	Description
POST	/api/products/tags/sync	product.yaml	Enqueue tag sync job (p99 < 200ms)
GET	/api/products/tags/sync/status	product.yaml	Check sync job status (?job_id=...)
GET	/tags	product.yaml	List all product tags
GET	/tags/{tag_id}	product.yaml	Get single tag detail
GET	/products	product.yaml	List products (verify synced data)

Schema tables

Table	Module	Role
product	Product	Write: tags, vendor, status, last_seen upserted from Shopify
product_tag	Product	Write: tag records synced from Shopify

Infrastructure

Resource	Type	Purpose
internal	Worker	API validation, job enqueue
ingest	Worker	Fetches tags from Shopify, upserts to DB
CF Queue	Queue	ARTIFACT_TAG_SYNC job delivery

Participants

Actor	Role
Staff user (Ops/Creative)	Triggers sync via UI
Dashboard API Worker	Validates, enqueues job
Ingest Worker	Fetches tags, upserts products
Shopify Admin API	Product data source

Main success scenario

1. Staff clicks “Sync Tags” → POST /api/products/tags/sync
2. API writes optional workflow execution record and enqueues ARTIFACT_TAG_SYNC
3. Ingest Worker queries Shopify (prefer GraphQL) with rate-limit backoff
4. Worker upserts product(tags, vendor, status, last_seen) in chunks — updating attributes on each product
5. Worker optionally enqueues measurement dataset refresh if classification thresholds depend on tags

Exception flows

Error condition	Recovery
Shopify rate limit	Delay retry using queue delaySeconds (up to 12 hours)
PlanetScale limits	Use smaller batches

Queue contract

{
  "job_type": "ARTIFACT_TAG_SYNC",
  "job_id": "uuid",
  "mode": "full",
  "requested_at": "ISO8601"
}

Acceptance criteria

• PASS: Sample product’s tags in Shopify match product.tags after completion
• FAIL: Orphaned products, malformed JSON in tags, or job unable to complete