UpPromote

UpPromote

UpPromote runs affiliate programs for e-commerce stores. Affiliates refer customers; referrals track conversions and commissions; programs define commission rules; payments batch approved commissions; webhooks push lifecycle events to your servers.

Data Model

• Programs — commission rules, payment methods, exclusions, and default program flags.
• Affiliates — partner accounts with program membership, status, contact fields, affiliate links, and optional MLM upline.
• Referrals — order-level conversion rows with commission, status (pending, approved, paid, denied), and nested affiliate contact.
• Payments — unpaid commission buckets per affiliate and paid payout history rows with referral ids.
• Coupons — coupon codes assigned to affiliates (not the Shopify discount definition itself).
• Connected customers — Shopify customers linked to affiliates for lifetime commission.
• Webhooks — one subscription per event type with target_url and secret_key for verification.

Operational order

1. List programs and affiliates to discover ids, emails, and program membership before writes.
2. List referrals with affiliate_email and from_date/to_date pairs when auditing commissions; read status from each row (v2 has no server-side status filter).
3. List unpaid payments before mark-as-paid runs; confirm referral ids included in each bucket.
4. Use analytics performance_summary or commission_breakdown for store-level reviews; top_affiliates for leaderboards.
5. List webhooks before changing subscriptions — UpPromote keys subscriptions by event type.
6. Run membership mutations (approve/deny affiliate, approve/deny referral, mark paid) only on explicit user intent.

Gotchas

• Store-scoped: Each API key belongs to one UpPromote-connected store; results never cross shops.
• Pagination: List endpoints use page and per_page (max 100 per call). Default to modest page sizes on large programs.
• Affiliate search: Name or email lookup uses affiliate_name or affiliate_email filters — pass q for keyword matching instead of scanning full pages.
• Profile edits: Affiliate profile updates outside approve/deny, move program, and set upline remain admin-only.
• Coupon cap: Each affiliate may hold at most 100 assigned coupon codes; assignments are create-only.
• Referral filters: API v2 accepts affiliate_email, program_id, order_id, and ISO8601 UTC from_date/to_date pairs. Status is returned on each row but is not a server-side list filter.
• Analytics scope: program_id and affiliate_email are mutually exclusive on analytics calls.
• Webhooks: Create with upsert (POST), change URL with upsert update=true (PUT), delete by event — not by numeric id.