swag-pending-approvals

name

swag-pending-approvals

description

Check Swag.com referral-program campaigns for orders pending approval. Runs referral fraud checks on each pending order and includes approve/deny recommendations. Shows redeemed orders awaiting shipment approval with name, email, tier, and location, and posts a Slack summary to a configured channel. Use when the user asks for "pending swag approvals", "swag orders to approve", "referral program approvals", or "check swag".

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.