@oronts/vendure-data-hub-plugin 0.1.3 → 0.1.5

package/docs/reference/README.md

@@ -13,9 +13,10 @@ Complete reference documentation for all Data Hub adapters.
 1. [Step Types](./step-types.md) - All pipeline step types
 2. [Extractors](./extractors.md) - All data extractors
 3. [Loaders](./loaders.md) - All entity loaders
-4. [Operators](./operators.md) - All transform operators
-5. [Feed Generators](./feeds.md) - Product feed generators
-6. [Search Sinks](./sinks.md) - Search engine integrations
+4. [Operators](./operators.md) - All transform operators (curated guide)
+5. [**Operators Complete**](./operators-complete.md) - **Auto-generated complete operator reference (all 61 operators)**
+6. [Feed Generators](./feeds.md) - Product feed generators
+7. [Search Sinks](./sinks.md) - Search engine integrations
 
 ## Quick Reference
 
@@ -33,7 +34,7 @@ Complete reference documentation for all Data Hub adapters.
 | `cdc` | Change Data Capture - poll database tables for changes |
 | `webhook` | Incoming webhook payloads |
 
-### Loaders (22 - 20 Entity + 2 External API)
+### Loaders (24 - 16 Entity + 4 Order Operations + 1 Deletion + 1 Inventory + 2 External API)
 
 | Code | Description |
 |------|-------------|
@@ -45,6 +46,7 @@ Complete reference documentation for all Data Hub adapters.
 | `facetUpsert` | Create/update facets for categorization |
 | `facetValueUpsert` | Create/update facet values within facets |
 | `promotionUpsert` | Create/update promotions with conditions and actions |
+| `orderUpsert` | Order create/update for migrations with state transitions and line management |
 | `orderNote` | Add notes to existing orders |
 | `orderTransition` | Transition order states |
 | `applyCoupon` | Apply coupon codes to orders |
@@ -57,6 +59,7 @@ Complete reference documentation for all Data Hub adapters.
 | `taxRateUpsert` | Create/update tax rates with category and zone |
 | `paymentMethodUpsert` | Create/update payment methods with handlers |
 | `channelUpsert` | Create/update channels with currencies and languages |
+| `entityDeletion` | Delete any of 13 entity types by slug, SKU, ID, code, email, or name |
 | `restPost` | POST data to custom REST endpoints |
 | `graphqlMutation` | Send records as GraphQL mutations to external APIs |
 
@@ -96,3 +99,7 @@ Complete reference documentation for all Data Hub adapters.
 | `typesense` | Typesense |
 | `queueProducer` | RabbitMQ Queue |
 | `webhook` | HTTP Webhook (POST/PUT/PATCH) |
+
+### API Notes
+
+- **`startDataHubPipelineRun`:** This mutation does not accept seed records. To provide seed data to a pipeline, use the webhook trigger (records passed in the request body) or the `dataHubTestWithSeedData` mutation for dry-run testing.

package/docs/reference/extractors.md

@@ -13,6 +13,7 @@ Complete reference for all data extractors.
 - [Database Extractor](#database-extractor) - Query SQL databases with pagination
 - [Webhook Extractor](#webhook-extractor) - Receive data from webhook payloads
 - [CDC (Change Data Capture) Extractor](#cdc-change-data-capture-extractor) - Poll database tables for changes
+- [In-Memory Extractor](#in-memory-extractor) - Inline data for testing and seed data
 - [Quick Reference](#quick-reference) - Summary table of all extractors
 
 ---
@@ -545,6 +546,34 @@ Poll a database table for changes using a timestamp or version column. Tracks IN
 
 ---
 
+## In-Memory Extractor
+
+Code: `inMemory`
+
+Reads records directly from inline data provided in the step configuration. Useful for testing, seed data, and webhook-triggered pipelines where data is passed at runtime.
+
+**Note:** The inMemory extractor reads records from the `data` field (not `records`). The `data` field accepts an array of objects or a single object (which will be wrapped in an array).
+
+### Configuration
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `data` | array/object | Yes | Inline records to extract. An array of objects, or a single object. |
+
+### Example
+
+```typescript
+.extract('inline-data', {
+    adapterCode: 'inMemory',
+    data: [
+        { sku: 'ABC-001', name: 'Widget A', price: 1999 },
+        { sku: 'ABC-002', name: 'Widget B', price: 2999 },
+    ],
+})
+```
+
+---
+
 ## Quick Reference
 
 | Code | Source Type | Use Case |
@@ -558,6 +587,7 @@ Poll a database table for changes using a timestamp or version column. Tracks IN
 | `database` | SQL Database | Query PostgreSQL, MySQL, SQLite, MSSQL, Oracle databases |
 | `cdc` | CDC | Poll database tables for changes using timestamp or version tracking |
 | `webhook` | Webhook | Receive data from webhook payloads |
+| `inMemory` | In-Memory | Inline data for testing, seed data, and webhook payloads |
 
 ### Authentication Options
 

package/docs/reference/loaders.md

@@ -1,11 +1,13 @@
 # Loaders Reference
 
-Complete reference for all built-in loaders: 16 entity loaders and 6 operation loaders.
+Complete reference for all 24 built-in loaders: 16 entity loaders, 4 order operation loaders, 1 entity deletion loader, 1 inventory adjust loader, and 2 external system loaders. Supports multi-language translations, multi-channel assignment, multi-currency pricing, custom fields, and entity deletion for 13 entity types.
+
+> **New**: [Enhanced validation error messages](../examples/validation-error-messages.md) with record identifiers and line numbers for better debugging.
 
 ## Table of Contents
 
 ### [Common Configuration](#common-configuration)
-- [Loader Adapter Codes](#loader-adapter-codes) - Complete list of all 22 loaders
+- [Loader Adapter Codes](#loader-adapter-codes) - Complete list of all 24 loaders
 - [Load Strategies](#load-strategies) - CREATE, UPDATE, UPSERT, MERGE, SOFT_DELETE, HARD_DELETE
 - [Conflict Strategies](#conflict-strategies) - SOURCE_WINS, VENDURE_WINS, MERGE, MANUAL_QUEUE
 
@@ -15,6 +17,7 @@ Complete reference for all built-in loaders: 16 entity loaders and 6 operation l
 - [Customer Loader](#customer-loader) - Create/update customers with addresses and groups
 - [Collection Loader](#collection-loader) - Create/update collections with parent relationships
 - [Inventory Loader](#inventory-loader) - Update stock levels by SKU
+- [Entity Deletion Loader](#entity-deletion-loader) - Delete products, variants, collections, promotions, shipping methods, customers, payment methods, facets, facet values, customer groups, tax rates, assets, stock locations
 - [Additional Loaders](#additional-loaders) - Order, Customer Group, Facet, Facet Value, Asset, Promotion, Shipping Method, Stock Location, Tax Rate, Payment Method, Channel
 
 ### External System Loaders
@@ -22,7 +25,7 @@ Complete reference for all built-in loaders: 16 entity loaders and 6 operation l
 - [Using Sinks for External Systems](#using-sinks-for-external-systems) - Alternative for search engines and message queues
 
 ### [Quick Reference](#quick-reference-1)
-- Summary table of all 22 loaders with descriptions
+- Summary table of all 24 loaders with descriptions
 - Required permissions for each loader
 
 ---
@@ -54,16 +57,18 @@ All loaders are configured using the `.load()` step in the pipeline DSL:
 | `assetAttach` | Asset | Attach existing assets to entities |
 | `promotionUpsert` | Promotion | Promotions with conditions and actions |
 | `stockAdjust` | Inventory | Adjust stock levels by SKU and location |
+| `orderUpsert` | Order | Create/update orders with lines and addresses (migration use only) |
 | `orderNote` | Order | Add notes to orders |
 | `orderTransition` | Order | Transition order states |
 | `applyCoupon` | Order | Apply coupon codes to orders |
 | `taxRateUpsert` | Tax Rate | Tax rates with zone and category mappings |
 | `paymentMethodUpsert` | Payment Method | Payment methods with handler configuration |
 | `channelUpsert` | Channel | Channels with currency and language settings |
-| `shippingMethodUpsert` | Shipping Method | Create/update shipping methods with calculators |
+| `shippingMethodUpsert` | Shipping Method | Create/update shipping methods with calculators, translations, channels |
 | `customerGroupUpsert` | Customer Group | Create/update customer groups with member assignments |
 | `stockLocationUpsert` | Stock Location | Create/update stock locations for inventory |
 | `inventoryAdjust` | Inventory | Adjust inventory levels by SKU and location |
+| `entityDeletion` | Multiple | Delete products, variants, collections, promotions, shipping methods, customers, payment methods, facets, facet values, customer groups, tax rates, assets, or stock locations |
 | `restPost` | Custom | POST data to REST endpoints |
 | `graphqlMutation` | GraphQL | Send records as GraphQL mutations to external APIs |
 
@@ -108,14 +113,69 @@ Create or update products with slug-based lookup, facets, and assets.
 | `featuredAssetUrl` | string | No | URL of the featured/main image |
 | `customFields` | object | No | Custom field values |
 
+### Config Fields
+
+| Config Field | Type | Required | Description |
+|-------------|------|----------|-------------|
+| `channel` | string | No | Target channel code |
+| `strategy` | string | No | Load strategy: `UPSERT` (default), `CREATE`, or `UPDATE` |
+| `conflictStrategy` | string | No | Conflict strategy: `SOURCE_WINS` (default), `VENDURE_WINS`, or `MERGE` |
+| `nameField` | string | No | Record field for product name (default: `"name"`) |
+| `slugField` | string | No | Record field for slug (default: `"slug"`) |
+| `descriptionField` | string | No | Record field for description (default: `"description"`) |
+| `enabledField` | string | No | Record field for enabled/published flag (default: `"enabled"`) |
+| `channelsField` | string | No | Record field containing channel codes (array or comma-separated) for dynamic per-record channel assignment |
+| `translationsField` | string | No | Record field containing multi-language translations. Overrides name/slug/description fields. Supports array format `[{ languageCode, name, slug?, description? }]` or object map `{ en: { name, slug?, description? } }` |
+| `skuField` | string | No | Record field for default variant SKU |
+| `priceField` | string | No | Record field for default variant price |
+| `customFieldsField` | string | No | Record field containing custom fields object (default: `"customFields"`) |
+| `createVariants` | boolean | No | Create/update a default variant alongside the product (default: `true`). Set to `false` when variants are handled by a separate `variantUpsert` step |
+| `facetValuesMode` | string | No | How to handle facet value assignments: `REPLACE_ALL` (default - replace all facets), `MERGE` (add new, keep existing), `REMOVE` (remove specified facets), `SKIP` (don't touch facets) |
+
+### Nested Entity Modes
+
+**facetValuesMode** - Controls how facet values are assigned to products:
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `REPLACE_ALL` | Replace all existing facet values with new list (default) | Source system is single source of truth for facet assignments |
+| `MERGE` | Add new facet values, keep existing ones | Multiple data sources contribute facets (e.g., PIM + manual admin) |
+| `REMOVE` | Remove specified facet values from product | Cleaning up discontinued or incorrect facet assignments |
+| `SKIP` | Don't modify facet values at all | Partial updates - only updating product name/description/price |
+
+**Example - Merge facets from multiple sources:**
+```typescript
+.load('enrich-products-from-pim', {
+    adapterCode: 'productUpsert',
+    strategy: 'UPDATE',
+    facetValuesMode: 'MERGE',  // Add new facets, keep existing
+})
+
+// Run 1 assigns: [color-red, size-large]
+// Run 2 adds: [material-cotton]
+// Result: [color-red, size-large, material-cotton] ✅
+```
+
+**Example - Skip facets for partial updates:**
+```typescript
+.load('update-product-descriptions', {
+    adapterCode: 'productUpsert',
+    strategy: 'UPDATE',
+    descriptionField: 'newDescription',
+    facetValuesMode: 'SKIP',  // Don't touch facets
+})
+```
+
 ### Example
 
 ```typescript
 .load('import-products', {
     adapterCode: 'productUpsert',
     strategy: 'UPSERT',
-    matchField: 'slug',
     conflictStrategy: 'SOURCE_WINS',
+    channelsField: 'channels',
+    translationsField: 'translations',
+    createVariants: false,
 })
 ```
 
@@ -149,14 +209,43 @@ Update product variants by SKU with multi-currency prices and auto-create option
 | Config Field | Type | Required | Description |
 |-------------|------|----------|-------------|
 | `skuField` | string | Yes | Record field containing the SKU |
-| `priceField` | string | No | Record field for price in minor units |
-| `priceByCurrencyField` | string | No | Record field for multi-currency prices object |
 | `nameField` | string | No | Record field for variant name |
+| `priceField` | string | No | Record field for price (major units, auto-converted to minor) |
+| `priceByCurrencyField` | string | No | Record field for multi-currency prices object (e.g. `{ USD: 19.99, EUR: 17.50 }`) |
+| `enabledField` | string | No | Record field for variant enabled/published flag (default: `"enabled"`) |
+| `channelsField` | string | No | Record field containing channel codes (array or comma-separated) for dynamic per-record channel assignment |
+| `translationsField` | string | No | Record field containing multi-language translations. Overrides name field. Supports array `[{ languageCode, name }]` or object map `{ en: { name }, de: { name } }` |
 | `customFieldsField` | string | No | Record field containing custom fields object |
 | `optionGroupsField` | string | No | Record field containing option group key-value pairs (auto-creates groups) |
 | `optionIdsField` | string | No | Record field containing pre-existing Vendure option IDs array |
 | `optionCodesField` | string | No | Record field containing option codes array for lookup |
+| `taxCategoryName` | string | No | Tax category name to assign |
+| `stockField` | string | No | Record field for stock on hand |
+| `stockByLocationField` | string | No | Record field for stock by location map |
 | `strategy` | string | No | Load strategy: `UPSERT` (default), `CREATE`, or `UPDATE` |
+| `facetValuesMode` | string | No | How to handle facet value assignments: `REPLACE_ALL` (default - replace all facets), `MERGE` (add new, keep existing), `REMOVE` (remove specified facets), `SKIP` (don't touch facets) |
+
+### Nested Entity Modes
+
+**facetValuesMode** - Controls how facet values are assigned to variants (same modes as Product):
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `REPLACE_ALL` | Replace all existing facet values with new list (default) | Source system controls all facet assignments |
+| `MERGE` | Add new facet values, keep existing ones | Incremental facet additions from multiple sources |
+| `REMOVE` | Remove specified facet values from variant | Removing discontinued attributes |
+| `SKIP` | Don't modify facet values at all | Partial updates - only updating price/stock |
+
+**Example - Update prices without touching facets:**
+```typescript
+.load('update-variant-prices', {
+    adapterCode: 'variantUpsert',
+    strategy: 'UPDATE',
+    skuField: 'sku',
+    priceField: 'newPrice',
+    facetValuesMode: 'SKIP',  // Don't modify facets
+})
+```
 
 ### Option Group Assignment
 
@@ -213,13 +302,64 @@ Create or update customers with addresses and group memberships.
 | `addresses` | array | No | Array of address objects |
 | `groupCodes` | string[] | No | Array of customer group codes |
 
-### Example
+### Config Fields
+
+| Config Field | Type | Required | Description |
+|-------------|------|----------|-------------|
+| `strategy` | string | No | Load strategy: `UPSERT` (default), `CREATE`, or `UPDATE` |
+| `matchField` | string | No | Field to match existing customers (default: `emailAddress`) |
+| `addressesMode` | string | No | How to handle addresses: `UPSERT_BY_MATCH` (default), `REPLACE_ALL`, `APPEND_ONLY`, `UPDATE_BY_ID`, `SKIP` |
+| `addressMatchFields` | string | No | Comma-separated fields for address matching (default: `streetLine1,city,countryCode`) |
+| `groupsMode` | string | No | How to handle customer groups: `REPLACE_ALL` (default), `MERGE`, `REMOVE`, `SKIP` |
+
+### Nested Entity Modes
+
+**addressesMode** - Controls how customer addresses are managed:
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `UPSERT_BY_MATCH` | Match by fields, update if exists, create if not (default, **recommended**) | **Prevents duplicate addresses** - most common use case |
+| `REPLACE_ALL` | Delete all existing addresses, create new from source | Source system is single source of truth for addresses |
+| `APPEND_ONLY` | Always create new addresses (allows duplicates) | Address history tracking (rare - usually want UPSERT) |
+| `UPDATE_BY_ID` | Update by Vendure address ID if provided, create if not | Source system tracks Vendure address IDs |
+| `SKIP` | Don't modify addresses at all | Partial updates - only updating customer name/email |
+
+**Address Matching** (`UPSERT_BY_MATCH` mode):
+- Default match fields: `streetLine1`, `city`, `countryCode`
+- Customizable via `addressMatchFields` config
+- Case-insensitive matching
+- Prevents duplicate addresses across repeated pipeline runs
+
+**groupsMode** - Controls customer group assignments:
+
+| Mode | Behavior |
+|------|----------|
+| `REPLACE_ALL` | Remove all groups, assign new list (default) |
+| `MERGE` | Add new groups, keep existing |
+| `REMOVE` | Remove specified groups |
+| `SKIP` | Don't modify groups |
+
+### Example - Prevent Duplicate Addresses
 
 ```typescript
 .load('import-customers', {
     adapterCode: 'customerUpsert',
     strategy: 'UPSERT',
     matchField: 'emailAddress',
+    addressesMode: 'UPSERT_BY_MATCH',  // ← Prevents duplicates
+    addressMatchFields: 'streetLine1,city,postalCode,countryCode'
+})
+
+// Run 1: Customer has 2 addresses
+// Run 2: Customer still has 2 addresses (no duplicates!) ✅
+```
+
+### Example - Custom Address Matching
+
+```typescript
+.load('import-customers', {
+    addressesMode: 'UPSERT_BY_MATCH',
+    addressMatchFields: 'streetLine1,city,countryCode'  // Match by street+city+country only
 })
 ```
 
@@ -233,7 +373,7 @@ Customers can be matched by: `emailAddress`
 
 Adapter Code: `collectionUpsert`
 
-Create or update collections with parent relationships.
+Create or update collections with parent relationships. Supports multi-language translations, multi-channel assignment, and isPrivate flag.
 
 ### Input Fields
 
@@ -245,13 +385,30 @@ Create or update collections with parent relationships.
 | `parentSlug` | string | No | Parent collection slug |
 | `enabled` | boolean | No | Whether collection is visible |
 
+### Config Fields
+
+| Config Field | Type | Required | Description |
+|-------------|------|----------|-------------|
+| `channel` | string | No | Target channel code |
+| `strategy` | string | No | Load strategy: `UPSERT` (default), `CREATE`, or `UPDATE` |
+| `slugField` | string | No | Record field for slug (default: `"slug"`) |
+| `nameField` | string | No | Record field for name (default: `"name"`) |
+| `descriptionField` | string | No | Record field for description (default: `"description"`) |
+| `parentSlugField` | string | No | Record field for parent collection slug |
+| `customFieldsField` | string | No | Record field containing custom fields object |
+| `translationsField` | string | No | Record field containing multi-language translations. Overrides name/slug/description fields. Supports array `[{ languageCode, name, slug?, description? }]` or object map `{ en: { name, slug?, description? } }` |
+| `channelsField` | string | No | Record field containing channel codes (array or comma-separated) for per-record channel assignment |
+| `isPrivateField` | string | No | Record field containing isPrivate boolean flag |
+| `applyFilters` | boolean | No | Trigger filter application job after upsert |
+
 ### Example
 
 ```typescript
 .load('import-collections', {
     adapterCode: 'collectionUpsert',
     strategy: 'UPSERT',
-    matchField: 'slug',
+    translationsField: 'translations',
+    channelsField: 'channels',
 })
 ```
 
@@ -285,30 +442,210 @@ Update stock levels for product variants by SKU.
 
 ---
 
+## Entity Deletion Loader
+
+Adapter Code: `entityDeletion`
+
+Delete entities by slug, SKU, code, email, name, or ID. Supports 13 entity types: Products, Variants, Collections, Promotions, Shipping Methods, Customers, Payment Methods, Facets, Facet Values, Customer Groups, Tax Rates, Assets, and Stock Locations.
+
+### Config Fields
+
+| Config Field | Type | Required | Description |
+|-------------|------|----------|-------------|
+| `entityType` | string | No | Entity type: `'product'`, `'variant'`, `'collection'`, `'promotion'`, `'shipping-method'`, `'customer'`, `'payment-method'`, `'facet'`, `'facet-value'`, `'customer-group'`, `'tax-rate'`, `'asset'`, or `'stock-location'` (default: `'product'`) |
+| `identifierField` | string | No | Record field containing the identifier (default depends on entity type) |
+| `matchBy` | string | No | How to find the entity: `'slug'`, `'sku'`, `'id'`, `'code'`, `'email'`, or `'name'` (default depends on entity type) |
+| `cascadeVariants` | boolean | No | Delete all variants before deleting a product (default: `true`) |
+| `channel` | string | No | Channel code for context |
+
+### Default matchBy per Entity Type
+
+| Entity Type | Default matchBy | Default identifierField |
+|-------------|----------------|------------------------|
+| `product` | `slug` | `slug` |
+| `variant` | `sku` | `sku` |
+| `collection` | `slug` | `slug` |
+| `promotion` | `code` | `code` |
+| `shipping-method` | `code` | `code` |
+| `customer` | `email` | `email` |
+| `payment-method` | `code` | `code` |
+| `facet` | `code` | `code` |
+| `facet-value` | `code` | `code` |
+| `customer-group` | `name` | `name` |
+| `tax-rate` | `name` | `name` |
+| `asset` | `name` | `name` |
+| `stock-location` | `name` | `name` |
+
+### Example - Delete Products by Slug
+
+```typescript
+.load('delete-products', {
+    adapterCode: 'entityDeletion',
+    entityType: 'product',
+    matchBy: 'slug',
+    cascadeVariants: true,
+})
+```
+
+### Example - Delete Promotions by Code
+
+```typescript
+.load('delete-promotions', {
+    adapterCode: 'entityDeletion',
+    entityType: 'promotion',
+    identifierField: 'couponCode',
+})
+```
+
+### Example - Delete Customers by Email
+
+```typescript
+.load('delete-customers', {
+    adapterCode: 'entityDeletion',
+    entityType: 'customer',
+    identifierField: 'email',
+})
+```
+
+### Example - Delete Collections by Slug
+
+```typescript
+.load('delete-collections', {
+    adapterCode: 'entityDeletion',
+    entityType: 'collection',
+    identifierField: 'slug',
+})
+```
+
+### Example - Delete Facet Values by Code
+
+```typescript
+.load('delete-facet-values', {
+    adapterCode: 'entityDeletion',
+    entityType: 'facet-value',
+    identifierField: 'facetValueCode',
+})
+```
+
+### Behavior
+
+- **Product deletion with cascade**: All variants are soft-deleted first, then the product
+- **Product deletion without cascade**: Only the product is soft-deleted (variants remain)
+- **Collection deletion**: Deletes the collection found by slug or ID
+- **Promotion deletion**: Soft-deletes the promotion found by coupon code or ID
+- **Shipping method deletion**: Soft-deletes the shipping method found by code or ID
+- **Customer deletion**: Soft-deletes the customer found by email or ID
+- **Payment method deletion**: Hard-deletes the payment method found by code or ID
+- **Facet deletion**: Hard-deletes the facet found by code or ID (includes all facet values)
+- **Facet value deletion**: Hard-deletes the facet value found by code or ID
+- **Customer group deletion**: Deletes the customer group found by name or ID
+- **Tax rate deletion**: Deletes the tax rate found by name or ID
+- **Asset deletion**: Deletes the asset found by name or ID
+- **Stock location deletion**: Deletes the stock location found by name or ID
+- **Not found**: Logs a warning and skips (does not fail the record)
+- **Errors**: Reported via `onRecordError` callback per standard loader error handling
+
+---
+
+---
+
+## Order Loader
+
+Adapter Code: `orderUpsert`
+
+Create or update orders with line items and addresses. **Intended for system migrations** - normal orders should go through the standard checkout flow.
+
+### Input Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `code` | string | Yes | Order code / reference number |
+| `customerEmail` | string | Yes | Customer email address (must exist) |
+| `lines` | array | Yes | Order line items with SKU and quantity |
+| `shippingAddress` | object | No | Shipping address details |
+| `billingAddress` | object | No | Billing address details |
+| `shippingMethodCode` | string | No | Shipping method code |
+| `state` | string | No | Target order state (e.g., 'PaymentSettled', 'Shipped') |
+| `orderPlacedAt` | string | No | Order placement date (ISO 8601 format) for backdating |
+
+### Config Fields
+
+| Config Field | Type | Required | Description |
+|-------------|------|----------|-------------|
+| `strategy` | string | No | Load strategy: `CREATE` (default), `UPDATE`, or `UPSERT` |
+| `codeField` | string | No | Record field for order code (default: `"code"`) |
+| `customerEmailField` | string | No | Record field for customer email (default: `"customerEmail"`) |
+| `linesField` | string | No | Record field for order lines array (default: `"lines"`) |
+| `shippingAddressField` | string | No | Record field for shipping address (default: `"shippingAddress"`) |
+| `billingAddressField` | string | No | Record field for billing address (default: `"billingAddress"`) |
+| `stateField` | string | No | Record field for target state (default: `"state"`) |
+| `orderPlacedAtField` | string | No | Record field for order placement date (default: `"orderPlacedAt"`) |
+| `linesMode` | string | No | How to handle order lines: `REPLACE_ALL` (default), `MERGE_BY_SKU`, `APPEND_ONLY`, `SKIP` |
+
+### Nested Entity Modes
+
+**linesMode** - Controls how order line items are managed:
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `REPLACE_ALL` | Remove all existing lines, add new ones (default) | Full order replacement during migration |
+| `MERGE_BY_SKU` | Update quantities for existing SKUs, add new SKUs | Incremental order updates - adding more items or adjusting quantities |
+| `APPEND_ONLY` | Always add new lines (allows duplicate SKUs) | Order modification history tracking (rare) |
+| `SKIP` | Don't modify order lines | Update order state or addresses only, leave lines unchanged |
+
+**Example - Merge order lines by SKU:**
+```typescript
+.load('update-orders', {
+    adapterCode: 'orderUpsert',
+    strategy: 'UPDATE',
+    codeField: 'orderCode',
+    linesField: 'additionalItems',
+    linesMode: 'MERGE_BY_SKU',  // Smart merging
+})
+
+// Existing order: PROD-A qty:2
+// Update adds: PROD-A qty:5, PROD-B qty:1
+// Result: PROD-A qty:5 (updated), PROD-B qty:1 (added) ✅
+```
+
+**Example - Replace all lines:**
+```typescript
+.load('migrate-orders', {
+    adapterCode: 'orderUpsert',
+    strategy: 'CREATE',
+    linesMode: 'REPLACE_ALL',  // Complete replacement
+    stateField: 'finalState',
+    orderPlacedAtField: 'originalOrderDate',
+})
+```
+
+### Match Fields
+
+Orders can be matched by: `code`
+
+---
+
 ## Additional Loaders
 
 The following loaders are available but have similar patterns:
 
-### Order Loader (`ORDER`)
-Create/update orders with line items and addresses.
-
 ### Customer Group Loader (`CUSTOMER_GROUP`)
 Create/update customer groups with member assignments.
 
 ### Facet Loader (`FACET`)
-Create/update facets for product categorization.
+Create/update facets for product categorization. Supports `translationsField` for multi-language names and `channelsField` for per-record channel assignment.
 
 ### Facet Value Loader (`FACET_VALUE`)
-Create/update facet values within facets.
+Create/update facet values within facets. Supports `translationsField` for multi-language names and `channelsField` for per-record channel assignment.
 
 ### Asset Loader (`ASSET`)
 Create/update assets and attach to entities.
 
 ### Promotion Loader (`PROMOTION`)
-Create/update promotions with conditions and actions.
+Create/update promotions with conditions and actions. Supports `translationsField` for multi-language name/description, `channelsField` for per-record channel assignment, `descriptionField` for single-language description, and `perCustomerUsageLimitField` for per-customer usage limits. When the `enabled` field is not provided in the record, promotions default to `enabled: true`.
 
 ### Shipping Method Loader (`SHIPPING_METHOD`)
-Create/update shipping methods with calculators.
+Create/update shipping methods with calculators and fulfillment handlers. Supports `translationsField` for multi-language name/description, `channelsField` for per-record channel assignment, and `customFieldsField` for custom field values.
 
 ### Stock Location Loader (`STOCK_LOCATION`)
 Create/update stock locations for inventory.
@@ -317,10 +654,10 @@ Create/update stock locations for inventory.
 Create/update tax rates with category and zone.
 
 ### Payment Method Loader (`PAYMENT_METHOD`)
-Create/update payment methods with handlers.
+Create/update payment methods with handlers. Supports `translationsField` for multi-language name/description, `channelsField` for per-record channel assignment, and `customFieldsField` for custom field values.
 
 ### Channel Loader (`CHANNEL`)
-Create/update channels with currencies and languages.
+Create/update channels with currencies and languages. Supports `customFieldsField` for custom field values.
 
 ---
 
@@ -434,10 +771,11 @@ For sending data to external systems (REST APIs, search engines, message queues)
 | `taxRateUpsert` | Tax Rate | Create/update tax rates with category and zone |
 | `paymentMethodUpsert` | Payment Method | Create/update payment methods with handlers |
 | `channelUpsert` | Channel | Create/update channels with currencies and languages |
-| `shippingMethodUpsert` | Shipping Method | Create/update shipping methods with calculators |
+| `shippingMethodUpsert` | Shipping Method | Create/update shipping methods with calculators, translations, channels |
 | `customerGroupUpsert` | Customer Group | Create/update customer groups with member assignments |
 | `stockLocationUpsert` | Stock Location | Create/update stock locations for inventory |
 | `inventoryAdjust` | Inventory | Adjust inventory levels by SKU and location |
+| `entityDeletion` | Multiple | Delete products, variants, collections, promotions, shipping methods, customers, payment methods, facets, facet values, customer groups, tax rates, assets, or stock locations |
 | `restPost` | Custom | POST data to REST endpoints |
 | `graphqlMutation` | GraphQL | Send records as GraphQL mutations to external APIs |
 
@@ -447,7 +785,7 @@ Each loader requires specific Vendure permissions:
 
 | Adapter Code | Required Permission |
 |--------------|---------------------|
-| `productUpsert`, `variantUpsert`, `collectionUpsert`, `facetUpsert`, `facetValueUpsert`, `assetImport`, `assetAttach`, `stockAdjust` | `UpdateCatalog` |
+| `productUpsert`, `variantUpsert`, `collectionUpsert`, `facetUpsert`, `facetValueUpsert`, `assetImport`, `assetAttach`, `stockAdjust`, `entityDeletion` | `UpdateCatalog` |
 | `customerUpsert` | `UpdateCustomer` |
 | `orderNote`, `orderTransition`, `applyCoupon` | `UpdateOrder` |
 | `promotionUpsert` | `UpdatePromotion` |