PaperRun API Documentation¶
PaperRun is a postcard marketing automation platform for e-commerce. Merchants create campaigns targeting customer segments, and the platform handles recipient syncing, address enrichment, image personalization, printing, mailing, delivery tracking, and order attribution.
New Here? Use Claude Code¶
If you have Claude Code set up, the fastest way to get oriented is with slash commands:
/onboard-learn # Guided walkthrough of the full system, stage by stage
/explain-domain # Quick explainer on any domain (attribution, campaigns, printing, etc.)
For example, /onboard-learn will walk you through the architecture, trace a request through the code, explain the recipient pipeline, and cover attribution — pausing for questions at each stage.
See Claude Code Usage for all available commands.
Start Here¶
If you're new to the codebase, read these in order:
- Architecture Overview — System flow diagram, background workers, integration map
- Campaign — Campaign lifecycle and state machine
- Campaign Recipients — Recipient pipeline from sync to delivery
- Proofing & Mailing — How images are personalized and postcards are printed
- Order Syncing — How orders are synced and attributed to campaigns
- Attribution Methodology — Deep dive on attribution logic
Data Flows¶
- How Routes Work — Campaign creation trace, layer architecture pattern
- Recipient Pipeline — Sync -> proof -> send automation chain
- Proofing & Mailing — Image generation, printer routing, delivery
- Order Syncing — Klaviyo/Shopify order sync pipeline
- Address Enrichment — Faraday batch enrichment process
- Attribution Methodology — Email, address, discount code matching
Models¶
Core entities: Campaign | Recipients | Mailpiece | Organization | Orders | Attribution
Supporting: Integration | Templates | Discounts | Campaign Associations | Blocklist | Users
Guides¶
- Deploying — Docker builds, GHCR, Railway deployment
- Emergency Cancellation — Cancellation recovery procedures
- Testing — pytest patterns, factories, monkeypatch
- API Conventions — REST response shapes, pagination
- Celery Infrastructure — Queues, workers, broker, scheduler, observability, troubleshooting
- Slack Integration — Slash commands, app setup, rate limiting, caching
- Background Automations — Postage downgrade, CSM cadence update
- UK Address Notes — UK-specific address handling
External Integrations¶
| Service | Purpose |
|---|---|
| Klaviyo | Customer data platform — segments, profiles, order events |
| Shopify | E-commerce — store data, orders, webhooks |
| Stripe | Billing — usage meters, subscriptions |
| LOB | Postcard printing and mailing — via PrinterGateway |
| IntelliPrint | Postcard printing and mailing — via PrinterGateway |
| Stannp | Postcard printing and mailing — via PrinterGateway |
| Personalization Layer | Image personalization — Figma Plugin (current), Backup Generator (fallback), Pixelixe (deprecated). Rendering repo |
| Cloudflare Images | Image hosting and resizing |
| Faraday | Address enrichment |
Slack Commands¶
/pr-hello— Simple greeting/pr-orgs— List all organizations/pr-org <id|name>— Organization details and audit data