> ## 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.

# Supplier Connections & Sync Hub

> Connect Printify, Printful, Zenith, custom supplier REST APIs, webhooks, and Google Sheets to automate COGS, tracking codes, and fulfillment sync.

Sellfern Sync Hub automates the retrieval of production costs (COGS) and tracking information directly from your fulfillment partners, eliminating manual data entry and keeping your ledger, profit analytics, and order statuses accurate.

You can connect suppliers in four ways:

1. **[Template Library](#1-template-library)** — 1-click connectors for major print-on-demand providers (Printify, Printful, Gelato, FlashPOD, etc.).
2. **[Custom REST API](#2-custom-rest-api-connector)** — Connect any local printer or proprietary supplier API using JSONPath field extraction.
3. **[Inbound Webhooks](#3-real-time-inbound-webhooks)** — Push fulfillment updates in real time from Make.com, Zapier, or supplier callbacks.
4. **[Google Sheets](#4-google-sheets-supplier-tabs)** — Sync costs from shared fulfillment spreadsheets.

***

## Accessing Sync Hub

1. Navigate to **Settings → Suppliers**.
2. Select the **Sync Hub** tab (or visit `/admin/suppliers?view=sync`).
3. Click the **+ Add Supplier** button in the top-right corner to open the connection wizard.

***

## 1. Template Library

The Template Library includes pre-configured blueprints with authentication headers, endpoints, pagination rules, and response field extractors.

### Printify

Printify is a decentralized print network with 800+ products.

#### Prerequisites

* A Printify account with active stores.
* A Printify Personal Access Token (API Key).
* Your Printify **Shop ID**.

#### Step-by-Step Setup

1. Log in to [Printify](https://printify.com) and go to **Settings → Developer → API Tokens**.
2. Click **Generate New Token**, name it `Sellfern Sync`, and grant read permissions to Orders.
3. Copy the generated token string.
4. To find your **Shop ID**, check your browser URL when viewing your store dashboard (e.g., `https://printify.com/app/store/{shopId}`) or fetch your shops list via Printify API.
5. In Sellfern, open **+ Add Supplier → Template Library → Printify**.
6. Enter your **Shop ID** and paste your **API Token**.
7. Click **Save & Connect**.

<Tip>
  Printify returns order amounts in cents (e.g. `1250` for `$12.50`). Sellfern automatically applies a `0.01` cost multiplier so figures appear correctly in your ledger.
</Tip>

***

### Printful

Printful operates owned manufacturing facilities across North America, Europe, and Asia.

#### Prerequisites

* A Printful account with access to your store.
* A Printful API Token.

#### Step-by-Step Setup

1. Log in to the [Printful Developer Portal](https://developers.printful.com).
2. Go to **API Keys / Personal Access Tokens** and create a new token with `orders_read` permissions.
3. In Sellfern, open **+ Add Supplier → Template Library → Printful**.
4. Enter a display name and paste your API token.
5. Click **Save & Connect**.

***

### Zenith Fulfillment

Zenith provides fast, direct-from-factory fulfillment with JWT-authenticated REST APIs.

#### Step-by-Step Setup

1. Obtain your Zenith API credentials or authentication response from your Zenith account manager.
2. In Sellfern, open **+ Add Supplier → Template Library → Zenith** (or select Zenith from the provider list).
3. Paste either your **Access Token**, **Refresh Token**, or the **full JSON authentication response**:
   ```json theme={null}
   {
     "code": 200,
     "message": "success",
     "data": {
       "access": { "token": "ey...", "expires": "..." },
       "refresh": { "token": "ey...", "expires": "..." }
     }
   }
   ```
4. Sellfern parses the tokens and securely encrypts them. Zenith tokens are refreshed automatically before expiry.

***

### Other Pre-Configured Providers

| Provider      | Category       | Auth Method              | Notes                                   |
| :------------ | :------------- | :----------------------- | :-------------------------------------- |
| **Gelato**    | Global         | Header (`X-API-KEY`)     | Local production across 32 countries    |
| **FlashPOD**  | Vietnam & Asia | Header (`api-key`)       | High-capacity apparel & drinkware       |
| **Merchize**  | Vietnam & Asia | Header (`x-api-key`)     | Direct factory production               |
| **Yoycol**    | Vietnam & Asia | Header (`Authorization`) | All-over-print specialists              |
| **ShineOn**   | Specialized    | Bearer Token             | Viral personalized jewelry              |
| **CustomCat** | Specialized    | Header (`X-Api-Key`)     | Fast embroidery and DIGISOFT™           |
| **Dreamship** | Specialized    | Bearer Token             | High-quality home goods and drinkware   |
| **Prodigi**   | Europe & UK    | Header (`X-API-Key`)     | Fine art prints and museum framing      |
| **Teelaunch** | Europe & UK    | Header (`X-Api-Key`)     | Novelty products & laser engraved items |
| **Gooten**    | Global         | Query Param (`recipeid`) | Dynamic production routing              |

***

## 2. Custom REST API Connector

If you work with an independent print shop, overseas agent, or specialized manufacturer that offers a custom API, you can connect it without writing custom code.

1. In Sellfern, open **+ Add Supplier → Custom REST API**.
2. Configure **Endpoint & Authentication**:
   * **Display Name**: The name shown on orders and financial reports (e.g. `Hanoi Screenprint Hub`).
   * **Endpoint URL**: The full HTTP/HTTPS endpoint returning orders (e.g. `https://api.supplier.com/v1/orders`).
   * **Auth Type**:
     * `Bearer Token` (`Authorization: Bearer <token>`)
     * `Custom Header` (specify header name such as `X-API-KEY` or `PW-Access-Token`)
     * `URL Query Parameter` (specify parameter such as `apiKey` or `token`)
     * `Basic Auth`
   * **API Token / Secret Key**: Your credentials.
3. Configure **Response Field Extractors (JSONPath)**:
   * **Items Array Path**: Path to the list of orders (e.g. `data`, `orders`, or `result`). Leave empty if the response root is an array `[...]`.
   * **Order ID Path**: Field containing the customer or platform order number (e.g. `order_id`, `external_id`, or `reference`).
   * **Cost Path**: Field containing the total fulfillment cost (e.g. `total_cost`, `price`, or `costs.total`).
   * **Cost Multiplier**: Set to `1` for dollar values, or `0.01` if your supplier returns cents.
   * **Tracking Code Path** *(Optional)*: Field containing the shipment tracking number (e.g. `tracking_code` or `shipments[0].tracking_number`).
   * **Carrier Path** *(Optional)*: Field containing the carrier name (e.g. `carrier` or `shipments[0].carrier`).
4. Click **Save Custom Connector**. Sellfern tests the endpoint immediately and reports connection health.

***

## 3. Real-Time Inbound Webhooks

For suppliers that support webhook notifications, or when integrating via **Zapier**, **Make.com**, or **n8n**, you can create a passive webhook endpoint that receives fulfillment updates instantly.

1. Open **+ Add Supplier → Inbound Webhook**.
2. Enter a **Display Name** (e.g. `Zapier Fulfillment Webhook`).
3. Click **Create Webhook Endpoint**.
4. Sellfern generates:
   * A dedicated **Webhook URL**: `https://api.sellfern.com/api/v2/supplier-connections/{id}/webhook`
   * A unique **Secret Token**: e.g. `whsec_9a8b7c6d...`

### Webhook Authentication

All incoming requests must include the secret token in one of two ways:

* **HTTP Header (Recommended)**: `X-Webhook-Token: <your-token>`
* **URL Query Parameter**: `?token=<your-token>`

### Expected Payload Schema

Send an HTTP `POST` request with `Content-Type: application/json`:

```json theme={null}
{
  "orders": [
    {
      "orderId": "1001",
      "cost": 14.50,
      "trackingCode": "9400111899223192000000",
      "carrier": "USPS"
    }
  ]
}
```

#### Field Specifications:

* `orderId` *(string, required)*: The order number or external store order ID (leading `#` is automatically stripped).
* `cost` *(number, optional)*: Base fulfillment cost in USD.
* `trackingCode` *(string, optional)*: Shipment tracking number. When provided, order item status updates to `Shipped`.
* `carrier` *(string, optional)*: Carrier name (e.g. `USPS`, `FedEx`, `DHL`, `VNPost`).

<Note>
  You can pass an array directly `[...]` or wrap items under `orders`, `data`, or `items`. Sellfern automatically detects the array structure.
</Note>

***

## 4. Google Sheets (Supplier Tabs)

If your supplier provides daily or weekly updates in a Google Sheet:

1. Click **Connect Google** in the Google Sheets card.
2. Authorize your Google account with read-only permissions to Google Drive/Sheets.
3. Click **Browse Drive to select sheet** to select your workbook using the secure Google Picker.
4. Define your supplier tabs:
   * **Tab Name**: The exact name of the sheet tab (e.g. `Fairy Mai (3D)` or `Orders`).
   * **Supplier**: The supplier entity this tab should be credited to.
   * **Advanced Column Overrides**: Customize which columns contain `Order ID`, `Total Cost`, `SKU`, and `Tracking Code`.
5. Click **Save** to activate.

***

## Automated Background Sync

Once connections are enabled, Sellfern runs automatic background sync jobs:

* **Hourly Cron**: Every hour, the background worker polls all active API connections and Google Sheets tabs.
* **120-Day Safety Window**: The sync engine inspects unfulfilled orders and orders placed within the last 120 days, automatically updating base costs and attaching tracking numbers.
* **On-Demand Sync**: Click **Run Full Sync** in the Sync Hub header at any time, or click the **Play** button next to any specific provider to sync only that partner.
* **Live Audit Log**: All sync executions and webhook pushes are logged in the **Sync History** table with exact item counts and error traces.