Etsy Integration

The Etsy API is the primary data source. Setup and credentials live entirely in the app (Settings → Etsy Integration) and are stored in the database per user — no env vars or redeploy needed.

One-time setup

Create an Etsy app at etsy.com/developers (personal-use key is sufficient — it only touches your own shop).
Register the callback URL in the Etsy app settings, exactly: https://etsy.plexultra.com/api/etsy/callback
In the tracker: Settings → Etsy Integration → API Configuration
- Paste the keystring (OAuth client id)
- Paste the shared secret
- Confirm the callback URL (pre-filled)
- Save Configuration
Connect Etsy Shop → approve on Etsy's consent screen → you land back on Settings showing the shop name.

Credential quirks (learned the hard way)

The x-api-key header for API calls must be keystring:sharedsecret (both, colon-separated) — not the keystring alone.
OAuth token requests are form-encoded, not JSON.
Scopes requested: transactions_r listings_r shops_r (read-only). Listing creation would need listings_w and a reconnect (not implemented).

Syncing

Settings → Sync Orders Now pulls, idempotently:

Orders — upserted by receipt id (= the packing-slip "Order #"), so they merge with anything already present. Items get costs snapshotted from the catalogue.
Fees — from the payment-account ledger (chunked in 30-day windows; Etsy caps the query at 31 days). Amounts are integer minor units (÷100). Classified into Marketing & Advertising (prolist/offsite ads), Transaction Fees, Payment Processing Fees, Listing Fees, Taxes & GST. Credits, disbursements, and refunds are skipped. Unrecognised debits are reported back, not guessed.
Refunds — summed from each receipt and stored as refundTotal; revenue is reported net.
Customers — accumulated per buyer.

Settings → Sync Catalog pulls active listings into Products — one product per size variation (colour collapsed). Updates title/price/tags/sku/quantity/listing-id but preserves your costs.

Resolving unmatched items

After a sync, any item title that didn't match a product appears under a yellow banner with Resolve Items — map each to an existing product (saved as an alias) or create it with a cost. You can do a few at a time; the rest stay listed.

Idempotency / safety

Re-syncing never duplicates: orders upsert by number, fees by etsy-ledger-<entry_id>, and the sync auto-dedupes any historical duplicate fees.
The Remove Old Fees button clears legacy CSV-imported Etsy fees so they don't double-count with ledger fees.