Etsy Integration Guide

​

Features & Benefits for Etsy Sellers

• Automated Order Receipt Ingestion: Ingests active Etsy order receipts and transaction details in real-time.
• Supplier & POD Routing: Automatically routes print-on-demand items (plaques, tumblers, apparel, ornaments) to fulfillment suppliers.
• Instant Carrier Tracking Push-Back: Automatically posts carrier tracking numbers (USPS, FedEx, DHL, etc.) back to Etsy receipts, marking orders as completed on Etsy instantly.
• Listing COGS & Profit Margin Analytics: Calculates unit costs, shipping fees, marketplace transaction fees, and net profit margins per Etsy listing.

​

How to Connect Your Etsy Shop in 3 Simple Steps

​

Step 1: Open Your Sellfern Workspace

​

Step 2: Authorize Your Etsy Shop via OAuth 2.0

1. Top Reconnection Prompt Banner: Click the Connect / Reconnect Etsy API button on the banner at the top of the Stores tab (appears automatically whenever a store is missing an active OAuth token).
2. Add / Edit Store Form: Select Etsy as the platform in the Add / Edit Store form, and click Connect via Etsy OAuth 2.0 (or Reconnect via Etsy OAuth 2.0 when editing an existing store).
3. Store Table Row Action: Click the Reconnect link directly under the API Status column next to any disconnected Etsy store in the stores list.

https://www.etsy.com/oauth/connect?response_type=code&client_id=YOUR_ETSY_API_KEY&redirect_uri=YOUR_REDIRECT_URI&scope=transactions_r%20transactions_w%20shops_r%20email_r&state=YOUR_STATE&code_challenge=YOUR_CHALLENGE&code_challenge_method=S256

​

Step 3: Enable Automated Fulfillment & Tracking Push-Back

1. Automated Pattern Mapping (SKU Prefix Rules):
   • Navigate to Settings → Catalog → SKU Prefix Rules.
   • Define SKU prefix rules (e.g., map listing SKU prefix EMB-TSHIRT to target SPU TSHIRT-GILDAN-5000).
   • Supports rule prioritization, store-specific filtering, and CSV bulk import (SKU Prefix, Target SPU, Rule Type, Priority, Store ID).
2. Direct Catalog SPU Mapping:
   • Navigate to System Products / Catalog.
   • Map listing SKUs directly to specific System Product SPUs and variant configurations (Size/Color).
3. SPU Supplier Routing Definitions:
   • Navigate to Settings → Catalog → SPU Definitions.
   • Link each SPU Code to its assigned fulfillment supplier and base cost structure.

​

End-to-End Automated Workflow

​

Store Connection Management & OAuth Status Monitoring

• Active Connection Status: Shows a green Connected badge with the connected Etsy Shop ID.
• Disconnected Warning: Shows an amber Disconnected warning if token refresh fails or access is revoked.
• Reconnection Alert Banner: Displays a persistent alert banner with a 1-click Connect / Reconnect Etsy API action.
• Etsy Shop ID Resolution: Automatically resolves numeric Etsy shop IDs from Etsy’s API during authorization or store creation.
• Disconnect & Reconnect Controls: Easily trigger OAuth 2.0 re-authorization or safely disconnect API access without losing historical order records.

​

Multi-Channel Ingestion Versatility

1. Direct Etsy OpenAPI v3 Sync (OAuth 2.0): Real-time receipt ingestion (GET /v3/application/shops/{shop_id}/receipts) and automatic tracking push-back (POST /v3/application/shops/{shop_id}/receipts/{receipt_id}/tracking).
2. Gmail Live Receipt Sync: Automatic email parsing of receipt notifications and supplier fulfillment invoices directly from connected seller email inboxes.
3. Order PDF & CSV Batch Ingestion: Drag-and-drop batch upload for custom personalization notes, historical order backfills, and supplier reconciliation.

​

Data Processing Architecture

​

Etsy OpenAPI v3 Granular Endpoint Contracts

​

1. Fetch Unfulfilled Orders (Shop Receipts)

• Endpoint: GET /v3/application/shops/{shop_id}/receipts
• Scope: transactions_r
• Query Parameters: was_paid=true, was_shipped=false, limit=100, offset=0 (automatically paginated with offset += limit loop until all receipts are ingested)
• Headers: Authorization: Bearer <access_token>, x-api-key: <apiKey>:<sharedSecret>

​

2. Retrieve Transaction Line Items & Personalization

• Endpoint: GET /v3/application/shops/{shop_id}/receipts/{receipt_id}/transactions
• Scope: transactions_r
• Purpose: Reads item variations, personalization notes, and customer shipping address.

​

3. Submit Fulfillment Tracking Push-Back

• Endpoint: POST /v3/application/shops/{shop_id}/receipts/{receipt_id}/tracking
• Scope: transactions_w
• Sample Request Payload:

{
  "tracking_code": "9400111899562123456789",
  "carrier_name": "usps",
  "send_bcc": false,
  "note_to_buyer": "Your custom item has been crafted and shipped via Sellfern fulfillment provider."
}

​

4. Verify Shop Details

• Endpoint: GET /v3/application/shops/{shop_id}
• Scope: shops_r

​

Data Privacy, Rate Limiting & Security Commitments

• OAuth 2.0 PKCE: Sellers authorize access directly with Etsy. Raw passwords or API keys are never requested or stored.
• Least Privilege Scopes: Only scopes required for fulfillment (transactions_r, transactions_w, shops_r, email_r) are requested.
• Rate Limiting Compliance: Sellfern implements token-bucket rate limiting compliant with Etsy’s 10 QPS / 10,000 daily limit, applying exponential backoff with jitter on HTTP 429.
• Data Isolation: Store tokens and order data are encrypted in transit (TLS 1.3) and at rest (AES-256). Etsy data is strictly isolated and never shared with third-party marketplaces.