Skip to main content

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.

Order Ingestion is how orders enter Sellfern. Every order that flows through costing, fulfillment, and financial reporting begins here. You can bring orders in from Gmail, BigQuery, a CSV file, or by entering them by hand—whichever approach fits how you run your business.

​
Import methods

Gmail Live Sync

Connect a Google account and let Sellfern scan your inbox for Etsy order confirmation emails on a schedule you control.

BigQuery Sync

Pull order data from BigQuery using a date range and sync mode. Best for high-volume or reporting-oriented imports.

CSV Bulk Import

Upload a spreadsheet of historical or external orders. Sellfern previews the data before committing anything.

Manual Entry

Create or edit a single order directly. Useful for custom orders, phone orders, corrections, and resolving import failures.

​
Gmail Live Sync

Gmail Live Sync is available to admins only. It connects a Google account and scans matching messages for Etsy order data.
1

Open Live Sync

Go to Orders → Ingestion and select Live Sync.
2

Connect your Google account

Click Connect in the Google Connection card. Complete the authorization popup. If the popup does not open, allow popups for Sellfern and try again. Once connected, the email address appears in the connection list.
3

Set the sync configuration

Configure the following before starting:
  • Lookback Start and End Date — the email date range to search.
  • Batch Limit — process 10, 50, 100, or 500 emails per run.
  • Fetch All — process every matching email in the date range instead of stopping at the batch limit.
  • Custom Query — optional Gmail search syntax to narrow results, such as a specific subject line or sender.
4

Start the sync

Click Start Sync. Watch the Live Terminal for progress, warnings, and errors. After the sync finishes, Sellfern refreshes sync history, failed-ingestion records, and application data.
5

Debug a specific order (optional)

If a particular Etsy order is not importing as expected, use Debug Extraction:
  1. Stay on Live Sync.
  2. Enter the exact Etsy order number in Enter Etsy Order #….
  3. Click Test.
  4. Review the Extraction Details and terminal output.
When the order is found, the debug panel shows the parsed order ID, total, currency, and item count. If parsing fails, the logs identify whether the email was not found or extraction failed after the email was located.
If a connected Gmail token expires, Sellfern flags the account as invalid. Reconnect the account before running another sync.

​
BigQuery Sync

BigQuery Sync is available to admins only and is designed for high-volume or reporting-oriented order imports.
1

Open BigQuery

Go to Orders → Ingestion → BigQuery.
2

Set the date range

Choose a required start date and end date. The Run Sync button stays disabled until both dates are entered.
3

Select a sync mode

  • Full Sync — imports both sales and refunds.
  • Sales Only — imports sales data only.
  • Refunds Only — imports refund data only.
4

Choose target stores

Leave the store selector empty to sync all stores, or select one or more stores to limit the scope. Use Select All to explicitly include every configured store.
5

Run the sync

Click Run Sync. Review the process log and result card, which shows counts for processed, updated, and errored records.

​
CSV bulk import

The CSV bulk import path (called Legacy Bulk in the app) lets you upload historical or spreadsheet-based orders.
1

Open Legacy Bulk

Go to Orders → Ingestion → Legacy Bulk.
2

Select your file

Click Select CSV and choose a .csv file from your computer.
3

Review the preview

Sellfern analyzes the file and displays a preview before committing anything. Check the detected format, order count, first 50 preview rows, and financial fields such as subtotal, discount, total, and net values.
4

Finalize or cancel

Click Finalize Import to commit the parsed orders, or Cancel to discard the upload without saving anything. The completion card shows how many orders were successfully imported.

​
Manual entry

Manual Entry lets you create or update a single order directly in Sellfern. Use it for custom orders, phone orders, wholesale work, corrections, and resolving failed ingestions or out-of-balance records. Key behaviors to know before you start:
  • Order ID is required. Sellfern will not save without one.
  • At least one line item is required.
  • Refund amount cannot be negative. Enter the deduction amount as a positive value.
  • If you leave the store field blank, Sellfern uses Manual Entry as the store name.
  • If you leave the customer name blank, Sellfern uses Walk-in.
  • Currency defaults to USD.
  • Subtotal, shipping, tax, and discount changes automatically recalculate the total.
  • New line items default to quantity 1, price 0, and empty SKU/style/type/size/color fields.
  • An item’s status becomes Complete when a base cost is provided; otherwise it stays Pending Cost.
To load and edit an existing order, enter the order ID and click the load action. Sellfern populates the form with the existing values so you can make targeted corrections.

​
Reviewing imports

After any import method, two tabs in the Review group help you catch and fix problems.

​
Failed ingestions

The Failed Ingestions tab (admin only) lists source records that could not be parsed into orders. From here you can:
  • Review the raw record and its error context.
  • Open a failed record in Manual Entry to resolve it by hand.
  • Delete individual failures or select multiple records for bulk deletion.
When you resolve a failed ingestion through Manual Entry and save successfully, Sellfern deletes the failed-ingestion record automatically.

​
Out of balance

The Out of Balance tab lists orders whose recorded totals do not match the detailed order math. This catches parser issues, discount discrepancies, shipping differences, and unusual customer data. Use the store filter, date range, and pagination controls to narrow the list, then click the edit action to open the order in Manual Entry and correct the totals or line items.

​
Troubleshooting

Connect a Gmail account first, or wait for the current sync to finish before starting a new one.
Enable popups for Sellfern in your browser settings, then click Connect again.
Reconnect the affected Google account from the Live Sync connection list.
Verify the Etsy order number is exact. If you are using a custom Gmail query, check that the syntax is valid and matches the email you expect.
Review the Extraction Details panel for clues. If the email cannot be parsed automatically, create the order using Manual Entry.
Enter both a start date and an end date. Also check that no other sync is currently running.
Cancel the upload without finalizing. Correct the CSV file and re-upload.
Confirm the order has an Order ID, at least one line item, and that any refund amount is entered as a positive number.
Check the user’s role and ingest access permission. Non-admin users start on Legacy Bulk and do not see Live Sync, BigQuery, or admin-only Review tabs.