> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sellfern.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Etsy Integration Guide

> Connect your Etsy shop directly to Sellfern using native OAuth 2.0 for automated order ingestion, supplier routing, tracking push-back, and profit tracking.

Sellfern provides a native, standalone integration for Etsy shop owners. Connecting your Etsy shop enables real-time order receipt sync, automated routing to print-on-demand & custom fulfillment suppliers, instant carrier tracking push-back, and accurate COGS & net profit margin analytics.

<Note>
  The Sellfern Etsy integration is 100% independent. Shop owners connect directly to Etsy via secure OAuth 2.0 authorization. No third-party platform or intermediary application subscription is required.
</Note>

## 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 vetted fulfillment partners.
* **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

Sign up or log in to your Sellfern dashboard at `https://sellfern.com`. Your workspace is provisioned with isolated tenant security for your shop.

### Step 2: Authorize Your Etsy Shop via OAuth 2.0

Navigate to **Settings > Store Connections** and click **Connect Etsy Shop**.

You will be redirected directly to Etsy's official authorization page (`etsy.com/oauth/connect`) to grant read/write permissions for your shop:

```text theme={null}
https://www.etsy.com/oauth/connect?response_type=code&client_id=YOUR_ETSY_API_KEY&scope=transactions_r%20transactions_w%20shops_r%20listings_r
```

### Step 3: Enable Automated Fulfillment & Tracking Push-Back

Once authorized, Sellfern automatically ingests active orders. Map your Etsy listing SKUs to Sellfern System Product SPUs to activate automated supplier routing and tracking sync.

***

## Multi-Channel Ingestion Versatility

To minimize operational effort for Etsy sellers, Sellfern supports three flexible order ingestion pipelines:

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.

***

## Etsy OpenAPI v3 Granular Endpoint Contracts

Sellfern communicates directly with official Etsy OpenAPI v3 endpoints:

### 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=50`
* **Headers**: `Authorization: Bearer <access_token>`, `x-api-key: <etsy_keystring>`

### 2. Submit Fulfillment Tracking Push-Back

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

```json theme={null}
{
  "tracking_code": "9400111899562123456789",
  "carrier_name": "usps",
  "send_bcc": false,
  "note_to_buyer": "Your custom item has been crafted and shipped via Sellfern fulfillment partner."
}
```

### 3. Retrieve Shop Listings for SKU & Inventory Mapping

* **Endpoint**: `GET /v3/application/shops/{shop_id}/listings`
* **Scope**: `listings_r`
* **Query Parameters**: `state=active`, `limit=100`

### 4. Verify Shop Details

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

***

## Data Privacy & Least-Privilege Security

Sellfern adheres strictly to Etsy API Terms of Use and Security Guidelines:

* **OAuth 2.0 PKCE**: Sellers authorize access directly with Etsy. Raw passwords or API keys are never requested or stored.
* **Least Privilege**: Only scopes required for fulfillment (`transactions_r`, `transactions_w`, `shops_r`, `listings_r`) are requested.
* **Data Isolation**: Store data is encrypted in transit (TLS 1.3) and at rest (AES-256). Etsy data is never shared with third-party marketplaces.