openfrontio / openfrontio/OpenFrontIO

[Feature] Printful POD integration — merch shop fulfilment

Open
#4,050 0 comments 0 reactions 1 assignee Claimed by @evanpelle View on GitHub
approved Backend Feature Monetization
Dominant language
TypeScript
Stars
2.7k
Forks
1.4k
Avg merge
17h 43m
Merged PRs (30d)
310

Description

## Overview
Integrate Printful as the print-on-demand fulfilment backend for the OpenFront merch shop. Stripe checkout triggers Printful order creation automatically.

## Architecture
```
Customer completes checkout

Stripe fires checkout.session.completed webhook

/api/webhooks/stripe maps line items → Printful sync_variant_ids

POST /orders to Printful with idempotency key (Stripe session ID)

Printful fulfils and fires package_shipped webhook

Customer receives tracking email
```

## Key implementation points
- Idempotency via `X-PF-Idempotency-Key: ` — non-negotiable
- Shipping rates fetched from Printful `/shipping/rates` **before** Stripe Checkout is initiated
- SKU → `sync_variant_id` mapping in DB (NOT catalog `variant_id` — different number)
- Stripe Tax enabled for UK (20% VAT), EU (OSS), US (economic nexus)
- Printful wallet must be funded with auto-recharge enabled
- `confirm: true` in order payload to skip draft window

## Acceptance criteria
- [ ] Full flow tested in Printful sandbox
- [ ] Idempotency verified (webhook fires twice → only one order created)
- [ ] Shipping rate correct for UK, EU, and US addresses
- [ ] VAT calculated correctly at checkout for UK customer (20%)
- [ ] Tracking email sent on `package_shipped` webhook
- [ ] `order_failed` alert fires to ops team

## Dependencies
- **Depends on:** Stripe checkout, OAuth
- Stripe Tax must be enabled before launch
- Printful wallet funded with auto-recharge

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.