@spree/docs 0.1.181 → 0.1.183

package/dist/developer/core-concepts/imports-exports.md

@@ -1,741 +1,167 @@
 ---
 title: Imports & Exports
+description: Moving data in and out of Spree as CSV — bulk catalog updates, customer lists, and order extracts.
 ---
 
 ## Overview
 
-Spree provides a comprehensive bulk data import and export system for managing large datasets. The system supports CSV file processing with configurable field mapping, asynchronous processing via background jobs, and real-time progress tracking in the admin interface.
+Spreadsheets remain how most merchants think about bulk work. A supplier sends a price list as CSV; the finance team wants last quarter's orders in Excel; a migration from another platform arrives as one enormous product export.
 
-### Import/Export System Diagram
+Spree handles both directions as background work, so a hundred-thousand-row file doesn't tie up a browser tab or time out.
 
 ```mermaid
-erDiagram
-    Import {
-        string number
-        string type
-        string status
-        bigint owner_id
-        string owner_type
-        bigint user_id
-    }
-
-    ImportMapping {
-        string schema_field
-        string file_column
-    }
-
-    ImportRow {
-        integer row_number
-        text data
-        string status
-        text validation_errors
-    }
-
-    ImportSchema {
-        array fields
-    }
-
-    RowProcessor {
-        hash attributes
-    }
-
-    Export {
-        string number
-        string type
-        integer format
-        jsonb search_params
-    }
-
-    Store {
-        string name
-    }
-
-    Import ||--|| Store : "belongs to (owner)"
-    Import ||--o{ ImportMapping : "has many"
-    Import ||--o{ ImportRow : "has many"
-    Import ||--|| ImportSchema : "uses"
-    ImportRow ||--|| RowProcessor : "processed by"
-    Export ||--|| Store : "belongs to"
+flowchart LR
+    File["CSV file"] --> Upload["Upload"]
+    Upload --> Map["Match columns<br/>to fields"]
+    Map --> Process["Process rows"]
+    Process --> Good["Imported"]
+    Process --> Bad["Failed rows<br/>with reasons"]
+    Bad --> Retry["Fix and retry"]
 ```
 
-## Architecture
+## What can be imported and exported
 
-The import/export system uses several design patterns:
+| Data | Import | Export |
+|---|:---:|:---:|
+| Products | Yes | Yes |
+| Product translations | Yes | Yes |
+| Customers | Yes | Yes |
+| Orders | — | Yes |
+| Gift cards | — | Yes |
+| Coupon codes | — | Yes |
+| Newsletter subscribers | — | Yes |
 
-1. **Single Table Inheritance (STI)**: Import and Export types inherit from base classes
-2. **State Machine**: Imports progress through states (pending → mapping → processing → completed)
-3. **Schema Definition**: ImportSchema classes define expected fields and validation
-4. **Row Processors**: Transform CSV rows into database records
-5. **Event-Driven Processing**: Background jobs handle heavy lifting asynchronously
-6. **Registry Pattern**: Types registered in `Spree.import_types` and `Spree.export_types`
+Orders are export-only on purpose. An order is a financial record of something that happened; inventing them from a spreadsheet would let the books say something that never occurred.
 
----
-
-## Exports
-
-Exports generate CSV files from filtered database records.
-
-### Built-in Export Types
-
-| Type | Description | Multi-line |
-|------|-------------|------------|
-| `Spree::Exports::Products` | Products with all variants | Yes |
-| `Spree::Exports::ProductTranslations` | Product translations for non-default store locales | Yes |
-| `Spree::Exports::Orders` | Orders with line items | Yes |
-| `Spree::Exports::Customers` | Customer accounts | No |
-| `Spree::Exports::GiftCards` | Gift cards | No |
-| `Spree::Exports::NewsletterSubscribers` | Newsletter subscribers | No |
-| `Spree::Exports::CouponCodes` | Promotion coupon codes | No |
-
-### Export Model
-
-The base `Spree::Export` class provides:
-
-```ruby
-module Spree
-  class Export < Spree.base_class
-    # Associations
-    belongs_to :store
-    belongs_to :user  # Admin who created export
-
-    # Attachments
-    has_one_attached :attachment  # Generated CSV file
-
-    # Key methods
-    def csv_headers           # Define column headers
-    def scope                 # Base query with store/vendor filtering
-    def scope_includes        # Eager loading associations
-    def records_to_export     # Apply ransack filters
-    def multi_line_csv?       # True if records produce multiple rows
-    def generate              # Create CSV and attach file
-  end
-end
-```
-
-### Creating a Custom Exporter
-
-**Step 1: Create the Export Class**
-
-```ruby app/models/spree/exports/subscriptions.rb
-module Spree
-  module Exports
-    class Subscriptions < Spree::Export
-      # Define CSV column headers
-      def csv_headers
-        %w[id email plan_name status created_at] + metafields_headers
-      end
-
-      # Eager load associations to avoid N+1 queries
-      def scope_includes
-        [:user, :plan, { metafields: :metafield_definition }]
-      end
-
-      # Override scope if needed (e.g., exclude cancelled)
-      def scope
-        super.where.not(status: 'cancelled')
-      end
-
-      # Set to true if each record produces multiple CSV rows
-      def multi_line_csv?
-        false
-      end
-    end
-  end
-end
-```
-
-**Step 2: Add `to_csv` Method to Your Model**
-
-```ruby app/models/spree/subscription.rb
-module Spree
-  class Subscription < Spree.base_class
-    def to_csv(store)
-      [
-        id,
-        user&.email,
-        plan&.name,
-        status,
-        created_at.iso8601
-      ] + metafields_csv_values(store)
-    end
-
-    private
-
-    def metafields_csv_values(store)
-      Spree::MetafieldDefinition.for_resource_type(self.class.name).order(:namespace, :key).map do |definition|
-        metafields.find { |m| m.metafield_definition_id == definition.id }&.value
-      end
-    end
-  end
-end
-```
-
-**Step 3: Register the Export Type**
-
-```ruby config/initializers/spree.rb
-Rails.application.config.after_initialize do
-  Spree.export_types << Spree::Exports::Subscriptions
-end
-```
-
-**Step 4: Add Translations**
-
-```yaml config/locales/en.yml
-en:
-  spree:
-    subscriptions: Subscriptions
-```
-
-### Multi-line Exports
-
-For exports where each record produces multiple rows (like products with variants):
-
-```ruby app/models/spree/exports/orders_with_items.rb
-module Spree
-  module Exports
-    class OrdersWithItems < Spree::Export
-      def multi_line_csv?
-        true
-      end
-
-      def csv_headers
-        %w[order_number line_item_sku quantity price]
-      end
-
-      def scope_includes
-        [line_items: :variant]
-      end
-    end
-  end
-end
-```
-
-```ruby app/models/spree/order.rb
-# In the Order model
-def to_csv(store)
-  line_items.map do |item|
-    [number, item.variant.sku, item.quantity, item.price]
-  end
-end
-```
-
-### Export Filtering
-
-Exports support [Ransack filtering via `search_params`](../../api-reference/admin-api/querying.md):
-
-```ruby
-# In admin, users can filter before exporting
-export = Spree::Exports::Products.new(
-  store: current_store,
-  user: current_user,
-  search_params: { name_cont: 'shirt', status_eq: 'active' }.to_json,
-  record_selection: 'filtered'  # or 'all' to ignore filters
-)
-```
-
----
-
-## Imports
-
-Imports process CSV files to create or update database records.
-
-### Built-in Import Types
-
-| Type | Description |
-|------|-------------|
-| `Spree::Imports::Products` | Products and variants |
-| `Spree::Imports::ProductTranslations` | Product translations (matched by slug) |
-| `Spree::Imports::Customers` | Customers |
-
-### Import Workflow
-
-```
-1. Upload CSV → pending
-2. Auto-map columns → mapping
-3. User confirms mapping → completed_mapping
-4. Parse rows (CreateRowsJob) → processing
-5. Process rows (ProcessRowsJob) → completed/failed
-```
-
-### Import Components
-
-#### Import Model
-
-```ruby
-module Spree
-  class Import < Spree.base_class
-    # Associations
-    belongs_to :owner, polymorphic: true  # Store or Vendor
-    belongs_to :user
-    has_many :mappings    # Field mappings
-    has_many :rows        # CSV rows to process
-
-    # Statuses. Each move between them is a workflow — Spree::Imports::
-    # StartMapping, CompleteMapping, StartProcessing, Complete and
-    # RetryFailedRows — so every step of the pipeline can be hooked.
-    include Spree::HasStatus
-    has_status :pending, :mapping, :completed_mapping, :processing, :completed, :failed,
-               default: :pending
-
-    # Key methods
-    def import_schema        # Returns schema class instance
-    def row_processor_class  # Returns processor class
-    def schema_fields        # Fields from schema + metafields
-    def mapping_done?        # All required fields mapped?
-  end
-end
-```
+## Exporting
 
-#### Import Schema
+An export is created, runs in the background, and produces a file to download.
 
-Defines expected CSV fields:
 
-```ruby
-module Spree
-  class ImportSchema
-    FIELDS = []
+```typescript Admin SDK
+const exportJob = await adminClient.exports.create({
+  type: 'Spree::Exports::Products',
+})
 
-    def fields
-      self.class::FIELDS
-    end
-
-    def required_fields
-      FIELDS.select { |f| f[:required] }.map { |f| f[:name] }
-    end
-
-    def optional_fields
-      FIELDS.reject { |f| f[:required] }.map { |f| f[:name] }
-    end
-  end
-end
-```
-
-#### Import Mapping
-
-Maps CSV columns to schema fields:
-
-```ruby
-module Spree
-  class ImportMapping < Spree.base_class
-    belongs_to :import
-
-    # Attributes
-    # schema_field - target field name from schema
-    # file_column  - CSV column header
-
-    def try_to_auto_assign_file_column(csv_headers)
-      # Matches by parameterized name comparison
-      self.file_column = csv_headers.find do |header|
-        header.parameterize.underscore == schema_field.parameterize.underscore
-      end
-    end
-  end
-end
+// Poll until it's done
+const status = await adminClient.exports.get(exportJob.id)
+status.status       // "pending" → "processing" → "completed"
+status.download_url // available once completed
 ```
 
-#### Import Row
-
-Represents a single CSV row:
-
-```ruby
-module Spree
-  class ImportRow < Spree.base_class
-    belongs_to :import, counter_cache: :rows_count
-    belongs_to :item, polymorphic: true, optional: true  # Created record
-
-    # Attributes
-    # row_number       - position in CSV
-    # data             - JSON-serialized row data
-    # status           - pending/processing/completed/failed
-    # validation_errors - error message if failed
-
-    def process!
-      start_processing!
-      self.item = import.row_processor_class.new(self).process!
-      complete!
-    rescue StandardError => e
-      self.validation_errors = e.message
-      fail!
-    end
-
-    def to_schema_hash
-      # Maps CSV data using import.mappings
-    end
-  end
-end
+```bash CLI
+spree api post /exports -d '{"type": "Spree::Exports::Products"}'
+spree api get /exports
 ```
 
-#### Row Processor
-
-Transforms row data into database records:
-
-```ruby
-module Spree
-  module Imports
-    module RowProcessors
-      class Base
-        def initialize(row)
-          @row = row
-          @import = row.import
-          @attributes = row.to_schema_hash
-        end
-
-        attr_reader :row, :import, :attributes
-
-        def process!
-          raise NotImplementedError
-        end
-      end
-    end
-  end
-end
-```
 
-### Creating a Custom Importer
+### Exporting a filtered set
 
-**Step 1: Create the Import Class**
+An export can carry the same filters as the listing it came from, so "export what I'm looking at" does what a merchant expects — this quarter's orders, this brand's products, not the entire table.
 
-```ruby app/models/spree/imports/subscriptions.rb
-module Spree
-  module Imports
-    class Subscriptions < Spree::Import
-      def row_processor_class
-        Spree::Imports::RowProcessors::Subscription
-      end
-    end
-  end
-end
+```typescript Admin SDK
+await adminClient.exports.create({
+  type: 'Spree::Exports::Orders',
+  filters: { completed_at_gteq: '2026-01-01' },
+})
 ```
 
-**Step 2: Define the Schema**
-
-```ruby app/models/spree/import_schemas/subscriptions.rb
-module Spree
-  module ImportSchemas
-    class Subscriptions < Spree::ImportSchema
-      FIELDS = [
-        { name: 'email', label: 'Customer Email', required: true },
-        { name: 'plan_name', label: 'Plan Name', required: true },
-        { name: 'status', label: 'Status', required: true },
-        { name: 'start_date', label: 'Start Date' },
-        { name: 'billing_interval', label: 'Billing Interval' },
-        { name: 'amount', label: 'Amount' },
-        { name: 'currency', label: 'Currency' }
-      ].freeze
-    end
-  end
-end
-```
+In the dashboard this is the Export button on any list — whatever filters are applied come along.
 
-**Step 3: Create the Row Processor**
-
-```ruby app/services/spree/imports/row_processors/subscription.rb
-module Spree
-  module Imports
-    module RowProcessors
-      class Subscription < Base
-        def process!
-          user = find_or_create_user
-          plan = find_plan
-
-          subscription = Spree::Subscription.find_or_initialize_by(
-            user: user,
-            plan: plan
-          )
-
-          subscription.status = attributes['status'] if attributes['status'].present?
-          subscription.start_date = parse_date(attributes['start_date']) if attributes['start_date'].present?
-          subscription.billing_interval = attributes['billing_interval'] if attributes['billing_interval'].present?
-
-          if attributes['amount'].present?
-            currency = attributes['currency'].presence || import.store.default_currency
-            subscription.set_price(currency, attributes['amount'])
-          end
-
-          subscription.save!
-          subscription
-        end
-
-        private
-
-        def find_or_create_user
-          email = attributes['email'].strip.downcase
-          Spree.user_class.find_or_create_by!(email: email)
-        end
-
-        def find_plan
-          Spree::Plan.find_by!(name: attributes['plan_name'].strip)
-        end
-
-        def parse_date(date_string)
-          Date.parse(date_string)
-        rescue ArgumentError
-          nil
-        end
-      end
-    end
-  end
-end
-```
+## Importing
 
-**Step 4: Register the Import Type**
+Importing has an extra step, because a file from somewhere else won't have Spree's column names. You upload it, say which of your columns means what, and then it runs.
 
-```ruby config/initializers/spree.rb
-Rails.application.config.after_initialize do
-  Spree.import_types << Spree::Imports::Subscriptions
-end
-```
+**Step 1: Upload the file**
 
-**Step 5: Add Translations**
+```typescript Admin SDK
+    const importJob = await adminClient.imports.create({
+      type: 'Spree::Imports::Products',
+      file: uploadedFileId,
+    })
+    ```
 
-```yaml config/locales/en.yml
-en:
-  spree:
-    subscriptions: Subscriptions
-```
+    Spree reads the header row and tells you which columns it found.
 
-### Products Import Schema
-
-The built-in products import supports these fields:
-
-**Required Fields:**
-- `slug` - Product URL slug
-- `sku` - Variant SKU
-- `name` - Product name
-- `price` - Variant price
-
-**Optional Fields:**
-- `status` - Product status (active/draft/archived)
-- `description` - Product description
-- `meta_title`, `meta_description`, `meta_keywords` - SEO metadata
-- `tags` - Product tags
-- `compare_at_price` - Original price for sale display
-- `currency` - Price currency
-- `width`, `height`, `depth`, `dimensions_unit` - Dimensions
-- `weight`, `weight_unit` - Weight
-- `available_on`, `discontinue_on` - Availability dates
-- `track_inventory` - Enable inventory tracking
-- `inventory_count`, `inventory_backorderable` - Stock settings
-- `tax_category`, `shipping_category` - Category assignments
-- `image1_src`, `image2_src`, `image3_src` - Image URLs
-- `option1_name`, `option1_value` through `option3_name`, `option3_value` - Variant options
-- `category1`, `category2`, `category3` - Taxon assignments (format: "Taxonomy -> Taxon -> Child Taxon")
-
-### Handling Multi-Variant Products
-
-The products import handles variants intelligently:
-
-1. **Master variant rows** (no option values): Create/update the product and its master variant
-2. **Non-master variant rows** (with option values): Create additional variants for an existing product
-
-```csv
-slug,sku,name,price,option1_name,option1_value,option2_name,option2_value
-my-tshirt,TSHIRT-001,My T-Shirt,29.99,,,,
-my-tshirt,TSHIRT-S-RED,My T-Shirt,29.99,Size,Small,Color,Red
-my-tshirt,TSHIRT-M-RED,My T-Shirt,29.99,Size,Medium,Color,Red
-my-tshirt,TSHIRT-L-RED,My T-Shirt,29.99,Size,Large,Color,Red
-```
+  **Step 2: Match columns to fields**
 
-### Metafield Support
+```typescript Admin SDK
+    await adminClient.imports.completeMapping(importJob.id, {
+      mappings: [
+        { schema_field: 'name', file_column: 'Product Title' },
+        { schema_field: 'sku', file_column: 'Item Code' },
+        { schema_field: 'price', file_column: 'RRP' },
+      ],
+    })
+    ```
 
-Both imports and exports support metafields dynamically:
+    Obvious matches are suggested for you; you only correct the ones that differ.
 
-**Export:** Metafield definitions are automatically added as CSV columns using the format `metafield.{namespace}.{key}`.
+  **Step 3: Watch it run**
 
-**Import:** Map CSV columns to metafield definitions. The system automatically detects columns matching the metafield pattern and updates the corresponding metafield values.
+```typescript Admin SDK
+    const status = await adminClient.imports.get(importJob.id)
 
----
+    status.status         // "processing" → "completed"
+    status.rows_count     // total
+    status.processed_count
+    status.failed_count
+    ```
 
-## Background Jobs
 
-### CreateRowsJob
+> **INFO:** Download a template for any import type to see the expected columns — the quickest way to prepare a file that maps cleanly.
 
-Parses CSV and creates ImportRow records:
+## When rows fail
 
-All import jobs inherit from `Spree::Imports::BaseJob`, which sets `queue_as Spree.queues.imports` once and is shared across the pipeline.
+Some rows will fail. A price with a currency symbol in it, a required field left blank, a duplicate SKU.
 
-```ruby
-module Spree
-  module Imports
-    class CreateRowsJob < Spree::Imports::BaseJob
-      def perform(import_id)
-        import = Spree::Import.find(import_id)
-        # Stream CSV, batch insert rows
-        # Then enqueue ProcessRowsJob via import.process_rows_async
-      end
-    end
-  end
-end
-```
-
-### ProcessRowsJob
-
-Fans the pending rows out into groups, each processed by a separate `ProcessGroupJob`:
-
-```ruby
-module Spree
-  module Imports
-    class ProcessRowsJob < Spree::Imports::BaseJob
-      BATCH_SIZE = 100
-
-      def perform(import_id)
-        import = Spree::Import.find(import_id)
-        dispatch_groups(import)
-      end
-
-      private
-
-      def dispatch_groups(import)
-        # When the import defines a group_column (e.g. ProductTranslations groups
-        # by slug) and that field is mapped, group rows by the column value.
-        # Otherwise, fall back to slicing pending_and_failed rows into batches of
-        # BATCH_SIZE. Either way: pluck the row IDs, set processing_groups_count /
-        # completed_groups_count up front so workers can't complete prematurely,
-        # then enqueue one ProcessGroupJob per group.
-        import.rows.pending_and_failed.in_batches(of: BATCH_SIZE) do |batch|
-          ProcessGroupJob.perform_later(import.id, batch.ids)
-        end
-      end
-    end
-  end
-end
-```
+**A failed row doesn't stop the import.** The good rows are imported; the bad ones are set aside with the reason.
 
-### ProcessGroupJob
-
-Processes one group of rows and reports completion:
-
-```ruby
-module Spree
-  module Imports
-    class ProcessGroupJob < Spree::Imports::BaseJob
-      def perform(import_id, row_ids)
-        import = Spree::Import.find(import_id)
-        rows = import.rows.where(id: row_ids).pending_and_failed
-
-        # Large imports process with events disabled and use bulk_process!;
-        # otherwise each row is processed individually via row.process!.
-        rows.each { |row| row.process! }
-
-        check_import_completion(import)
-      end
-
-      private
-
-      # Increments completed_groups_count, then completes the import only once the
-      # last group has finished and no rows are still in flight.
-      def check_import_completion(import)
-        # completed_groups_count += 1
-        import.complete! if import.completed_groups_count >= import.processing_groups_count &&
-                            import.rows.in_flight.none?
-      end
-    end
-  end
-end
-```
+```typescript Admin SDK
+const { data: failures } = await adminClient.imports.rows.list(importJob.id, {
+  filter: { status_eq: 'failed' },
+})
 
-### GenerateJob (Exports)
+failures.forEach((row) => {
+  row.row_number        // 47
+  row.validation_errors // "Price is not a number"
+})
 
-Generates CSV files for exports:
-
-```ruby
-module Spree
-  module Exports
-    class GenerateJob < Spree::BaseJob
-      queue_as Spree.queues.exports
-
-      def perform(export_id)
-        export = Spree::Export.find_by_prefix_id!(export_id)
-        export.generate
-      end
-    end
-  end
-end
+// After fixing the source data
+await adminClient.imports.retryFailedRows(importJob.id)
 ```
 
----
-
-## Events
-
-Import and export lifecycle events such as [`import.completed` and `export.created`](../../api-reference/webhooks-events.md) can be delivered as webhooks to react when an asynchronous import or export finishes.
-
-### Import Events
-
-| Event | Trigger |
-|-------|---------|
-| `import.created` | Import record created |
-| `import.completed` | All rows processed |
-
-### Export Events
-
-| Event | Trigger |
-|-------|---------|
-| `export.created` | Export record created (triggers generation) |
+Retrying re-runs only the failures, so a file where three rows out of ten thousand were wrong doesn't need re-importing whole.
 
-### Import Row Events
+> **WARNING:** A value that isn't a number is rejected, never guessed at. A price written as `"12,50"` fails rather than being read as `1250` — which would be a hundredfold overcharge. Fix the file rather than hoping the import is lenient.
 
-| Event | Trigger |
-|-------|---------|
-| `import_row.completed` | Row processed successfully |
-| `import_row.failed` | Row processing failed |
+## Interrupted work resumes
 
----
+Imports remember which row they reached. If the server restarts halfway through a large file, processing picks up where it stopped rather than starting again or skipping the remainder.
 
-## Configuration
+## Products with several variants
 
-### Queue Configuration
+A product with variants spans several rows — one per variant, repeating the product columns. Rows are grouped by the product identifier, so a t-shirt in three sizes is three rows and becomes one product.
 
-```ruby config/initializers/spree.rb
-# Configure job queues
-Spree.queues.imports = :imports
-Spree.queues.exports = :exports
-```
+Custom fields can be imported too: a column matching a [custom field](metafields.md) you've defined maps to it like any built-in field.
 
-### Preferences
+## Knowing when it's finished
 
-Imports support configurable delimiter:
+Imports and exports emit [events](events.md) as they progress, which also reach [webhooks](webhooks.md). That's how you trigger the next step of a pipeline — notify a channel, kick off a reindex — without polling.
 
-```ruby
-import.preferred_delimiter = ';'  # Default: ','
-```
-
----
-
-## Key Files Reference
-
-| File | Purpose |
-|------|---------|
-| `core/app/models/spree/import.rb` | Base import model |
-| `core/app/models/spree/export.rb` | Base export model |
-| `core/app/models/spree/import_schema.rb` | Base schema class |
-| `core/app/models/spree/import_mapping.rb` | Field mapping model |
-| `core/app/models/spree/import_row.rb` | Row model with processing |
-| `core/app/models/spree/imports/products.rb` | Products import type |
-| `core/app/models/spree/import_schemas/products.rb` | Products schema |
-| `core/app/services/spree/imports/row_processors/base.rb` | Base processor |
-| `core/app/services/spree/imports/row_processors/product_variant.rb` | Products processor |
-| `core/app/models/spree/exports/products.rb` | Products export |
-| `core/app/models/spree/exports/orders.rb` | Orders export |
-| `core/app/models/spree/exports/customers.rb` | Customers export |
-| `core/app/jobs/spree/imports/create_rows_job.rb` | Row creation job |
-| `core/app/jobs/spree/imports/process_rows_job.rb` | Row processing job |
-| `core/app/jobs/spree/exports/generate_job.rb` | Export generation job |
-| `admin/app/controllers/spree/admin/imports_controller.rb` | Admin imports controller |
-| `admin/app/controllers/spree/admin/exports_controller.rb` | Admin exports controller |
+| Event | When |
+|---|---|
+| `import.completed` | Every row has been attempted |
+| `import.failed` | The import could not run |
+| `export.completed` | The file is ready to download |
 
 ## Permissions
 
-Access is controlled via CanCanCan:
-
-```ruby
-# Allow admin to manage imports/exports
-can :manage, Spree::Import
-can :manage, Spree::Export
-```
-
-Records are filtered by `current_ability` ensuring users only export data they have access to.
+Import and export are gated by the same [permissions](staff-roles.md) as the data they touch. Someone who can't see customers can't export them — otherwise export would be a way around the whole permission system.
 
-## Related Documentation
+## Related
 
-- [Admin imports/exports endpoints](../../api-reference/admin-api/endpoints.md) — REST routes and required scopes to trigger imports and exports programmatically.
-- [Admin SDK resources](../sdk/admin/resources.md) — typed TypeScript client for driving these back-office operations.
+- [Products](products.md) — the most-imported data
+- [Custom Fields](metafields.md) — importing your own fields
+- [Events](events.md) — reacting to completion
+- [Staff & Roles](staff-roles.md) — who may import and export