Migrating 10,000+ Listings from CSV

📖 12 min read 🟢 Beginner

Moving a large database of listings into Sharetribe can be challenging due to strict API rate limits, complex data relations, and image hosting requirements. This SOP details the exact process for importing 10,000+ listings using the TribeOps guided import wizard.

Step 1: Preparing Your CSV File

Ensure your source CSV contains all mandatory columns. Sharetribe requires a specific schema, and any custom attributes must be mapped correctly. Here are the core fields you should verify:

  • title: The name of the listing (required).
  • description: Detailed information about the listing (required).
  • price: Numeric listing cost. (Decimals allowed; TribeOps will automatically scale this to cents/paise for Sharetribe API compliance).
  • currency: 3-letter code (e.g. USD, INR, EUR).
  • authorId: The Sharetribe UUID of the user who owns the listing.

💡 Pro Tip: If you do not have Sharetribe UUIDs in your CSV, TribeOps allows you to map by the author's email instead. The engine will query and resolve the corresponding Sharetribe UUIDs on the fly during the import process.

Step 2: Upload and Mapping Configuration

Navigate to the TribeOps panel and start a new Import. Upload your CSV file, or paste your raw data. The import engine will automatically parse headers and extract a preview table.

In the **Mapping** step, align your CSV columns with your Sharetribe target field schemas:

  1. Map core fields: title, description, price, state.
  2. Map custom fields: Select the target type (e.g. enum, multi-select, number, text) to match Sharetribe schema configurations.
  3. Choose a fallback value for any empty fields in the CSV.

Step 3: Handling Image Assets

Sharetribe listings require images to be uploaded to Sharetribe's secure S3 storage. Your CSV should contain image URLs (separated by commas if there are multiple images). TribeOps will:

  1. Download the image from the provided URL into a secure temporary storage buffer.
  2. Upload the asset to Sharetribe's media API.
  3. Map the resulting Sharetribe Image UUID to the listing payload automatically.

⚠️ Warning: Image processing is resource-intensive and WAF-limited. Ensure your image hosting provider allows hotlinking and does not block automated user-agent downloads.

Step 4: Execute with Rate-Limit Adjustments

Sharetribe applies strict rate limits (typically 30 write operations per minute for sandbox and 300/min for live plans). To avoid 429 Too Many Requests errors, set the appropriate write delay in TribeOps:

# Delays are auto-adjusted based on connection context:
- Live Account: 250ms write delay
- Sandbox/Test Account: 2,100ms write delay

TribeOps handles chunked processing with background queue workers, meaning you can close the browser and let the migration run in the background safely.

Step 5: Post-Migration Audit

Once completed, visit the **History** tab. If any listings failed due to validation issues or timeout failures:

  • Download the **Failed Rows CSV**, which includes a detailed error log column.
  • Correct the errors locally.
  • Upload the failed rows sheet to retry, avoiding duplicates of already migrated listings.