Swag Pending Approvals

Swag Pending Approvals

Check your Referral Program campaigns on Swag.com for orders in "received" status — the recipient has redeemed their giveaway link and submitted shipping info, but the order hasn't been approved yet.

Prerequisites

• SWAG_API_KEY — Swag.com API key (HTTP Basic Auth username).
• BUZZ_SLACK_TOKEN — Slack bot token (only for sending).
• APPROVALS_CHANNEL_ID — Slack channel to post the summary to.

API reference

https://api-docs.swag.com/ — Swag Pro API v2. Auth is HTTP Basic with the API key as username, no password. Base URL: https://api.swag.com/v2/.

Configuring campaigns

List your Referral Program campaign IDs and their tier labels in a local config or environment variable (do not commit real campaign IDs). Example shape:

REFERRAL_CAMPAIGNS = {
    # campaign_id: "tier label"
    111111: "5 Tier",
    222222: "10 Tier",
    # ...
}

Dashboard URL pattern: https://pro.swag.com/account/campaign/overview.php?storeid=<campaign_id>

Workflow

Step 1: Fetch pending orders

Query each campaign for orders with status received, using the campaign_id filter to avoid paging through all orders.

import json, os, urllib.request, ssl, base64

SWAG_API_KEY = os.environ["SWAG_API_KEY"]
auth = base64.b64encode(f"{SWAG_API_KEY}:".encode()).decode()
ctx = ssl.create_default_context()

# Load REFERRAL_CAMPAIGNS from your local/private config.

received = []
for cid, tier in REFERRAL_CAMPAIGNS.items():
    offset = 0
    while True:
        url = f"https://api.swag.com/v2/orders?campaign_id={cid}&offset={offset}&limit=100"
        req = urllib.request.Request(url, headers={"Authorization": f"Basic {auth}"})
        resp = urllib.request.urlopen(req, context=ctx)
        data = json.loads(resp.read())
        orders = data.get("data", data) if isinstance(data, dict) else data
        if not orders:
            break
        for o in orders:
            if o.get("status") == "received":
                ship = o.get("ship_to", {}) or {}
                received.append({
                    "id": o["id"],
                    "tier": tier,
                    "campaign_id": cid,
                    "name": ship.get("name", "?"),
                    "email": ship.get("email", "?"),
                    "city": ship.get("city", "?"),
                    "state": ship.get("state", ""),
                    "country": ship.get("country", "?"),
                    "redeemed": o.get("updated_at", "?"),
                })
        if len(orders) < 100:
            break
        offset += 100

received.sort(key=lambda r: r["redeemed"], reverse=True)

Step 1.5: Run referral fraud checks

Run the referral-fraud-check skill for every unique email in the pending list. Read that skill for the workflow — it spawns a cloud agent, queries your warehouse, and returns verdicts. Pass all emails in a single batch, then map each verdict (APPROVE / DENY / INVESTIGATE) back to the corresponding order(s).

Also run these quick local heuristics and surface them as additional context:

• Internal/team member: email domain matches $MAINTAINER_DOMAIN — likely legitimate.
• Name/email mismatch: no overlap between the shipping name and the email local part.
• Shared corporate domain: multiple orders sharing the same non-common email domain (exclude gmail/yahoo/outlook/hotmail/icloud/proton).
• Same email, multiple tiers: the same email across multiple campaign tiers — a strong fraud signal.
• High-tier scrutiny: flag the highest tiers for extra review.

The fraud-check verdict takes precedence over local heuristics, but show both.

Step 2: Format Slack message

Build a Slack mrkdwn message. Use updated_at as the redeemed date. Include a dashboard link for each tier that has pending orders. If you maintain a referral inspector dashboard, add its link via $REFERRAL_INSPECTOR_URL with the email as a query parameter.

🎁 *Swag Pending Approvals — <date>*
<count> orders awaiting approval across Referral Program campaigns

*<tier> Tier* — <https://pro.swag.com/account/campaign/overview.php?storeid=<id>|Approve in dashboard>
• [APPROVE | DENY | INVESTIGATE] <name> · <email> · <city>, <country> · Redeemed <date>
  <1-2 sentence explanation of the recommendation>
  <local heuristic flags>

If zero orders are pending:

🎁 *Swag Pending Approvals — <date>*
✅ No orders pending approval — all clear!

Step 3: Send to Slack (optional)

Only proceed if the user explicitly asks to send (or when running scheduled).

1. Check $BUZZ_SLACK_TOKEN exists.
2. Post to the user-provided channel, else $APPROVALS_CHANNEL_ID.

import json, os, urllib.request

TOKEN = os.environ["BUZZ_SLACK_TOKEN"]
channel = channel_id or os.environ["APPROVALS_CHANNEL_ID"]

payload = json.dumps({
    "channel": channel,
    "text": formatted_summary,
    "unfurl_links": False,
    "unfurl_media": False,
}).encode()
req = urllib.request.Request(
    "https://slack.com/api/chat.postMessage",
    data=payload,
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req) as resp:
    result = json.loads(resp.read())
assert result["ok"], f"chat.postMessage failed: {result}"

Scheduled Mode

When running on a schedule:

1. Always send the Slack message — no confirmation needed.
2. Post to $APPROVALS_CHANNEL_ID unless a different channel is configured.
3. SWAG_API_KEY and BUZZ_SLACK_TOKEN must be set.

Scheduled prompt: "Check for pending swag approvals and send the report."

Edge Cases

• SWAG_API_KEY not set: stop and tell the user to set it.
• API rate limit: the Swag API is limited (~1,000 requests/hour).
• Duplicate recipients: flag the same email across multiple orders/tiers — a strong fraud signal.
• Zero pending orders: still send the message — a clean queue is good news.

Constraints

• Do NOT hardcode or log the Swag API key, Slack token, campaign IDs, or PII.
• Use updated_at as the redeemed date, not created_at.