orion/app/modules/marketplace/docs/admin-guide.md

Letzshop Admin Management Guide

Complete guide for managing Letzshop integration from the Admin Portal at /admin/marketplace/letzshop.

Table of Contents

• Overview
• Store Selection
• Products Tab
• Orders Tab
• Exceptions Tab
• Jobs Tab
• Settings Tab

---

Overview

The Letzshop Management page provides a unified interface for managing Letzshop marketplace integration for all stores. Key features:

• Multi-Store Support: Select any store to manage their Letzshop integration
• Product Management: View, import, and export products
• Order Processing: View orders, confirm inventory, set tracking
• Exception Handling: Resolve product matching exceptions
• Job Monitoring: Track import, export, and sync operations
• Configuration: Manage CSV URLs, credentials, and sync settings

---

Store Selection

At the top of the page, use the store autocomplete to select which store to manage:

1. Type to search for a store by name or code
2. Select from the dropdown
3. The page loads store-specific data for all tabs
4. Your selection is saved and restored on next visit

Cross-Store View: When no store is selected, the Orders and Exceptions tabs show data across all stores.

---

Products Tab

The Products tab displays Letzshop marketplace products imported for the selected store.

Product Listing

• Search: Filter by title, GTIN, SKU, or brand
• Status Filter: Show all, active only, or inactive only
• Pagination: Navigate through product pages

Product Table Columns

Column	Description
Product	Image, title, and brand
Identifiers	GTIN and SKU codes
Price	Product price with currency
Status	Active/Inactive badge
Actions	View product details

Import Products

Click the Import button to open the import modal:

1. Import Single Language: Select a language and enter the CSV URL
2. Import All Languages: Imports from all configured CSV URLs (FR, DE, EN)

Import settings (batch size) are configured in the Settings tab.

Export Products

Click the Export button to export products to the Letzshop pickup folder:

• Exports all three languages (FR, DE, EN) automatically
• Files are placed in exports/letzshop/{store_code}/
• Filename format: {store_code}_products_{language}.csv
• The export is logged and appears in the Jobs tab

Export settings (include inactive products) are configured in the Settings tab.

---

Orders Tab

The Orders tab displays orders from Letzshop for the selected store (or all stores if none selected).

Order Listing

• Search: Filter by order number, customer name, or email
• Status Filter: All, Pending, Confirmed, Shipped, Declined
• Date Range: Filter by order date

Order Actions

Action	Description
View	Open order details modal
Confirm	Confirm all items in order
Decline	Decline all items in order
Set Tracking	Add tracking number and carrier

Order Details Modal

Shows complete order information including:

• Order number and date
• Customer name and email
• Shipping address
• Order items with confirmation status
• Tracking information (if set)

---

Exceptions Tab

The Exceptions tab shows product matching exceptions that need resolution. See the Order Item Exceptions documentation for details.

Exception Types

When an order is imported and a product cannot be matched by GTIN:

1. The order is imported with a placeholder product
2. An exception is created for resolution
3. The order cannot be confirmed until exceptions are resolved

Resolution Actions

Action	Description
Resolve	Assign the correct product to the order item
Bulk Resolve	Resolve all exceptions for the same GTIN
Ignore	Mark as ignored (still blocks confirmation)

---

Jobs Tab

The Jobs tab provides a unified view of all Letzshop-related operations for the selected store.

Job Types

Type	Icon	Color	Description
Product Import	Cloud Download	Purple	Importing products from Letzshop CSV
Product Export	Cloud Upload	Blue	Exporting products to pickup folder
Historical Import	Clock	Orange	Importing historical orders
Order Sync	Refresh	Indigo	Syncing orders from Letzshop API

Job Information

Each job displays:

• ID: Unique job identifier
• Type: Import, Export, Historical Import, or Order Sync
• Status: Pending, Processing, Completed, Failed, or Partial
• Records: Success count / Total processed (failed count if any)
• Started: When the job began
• Duration: How long the job took

Records Column Meaning

Job Type	Records Shows
Product Import	Products imported / Total products
Product Export	Files exported / Total files (3 languages)
Historical Import	Orders imported / Total orders
Order Sync	Orders synced / Total orders

Filtering

• Type Filter: Show specific job types
• Status Filter: Show jobs with specific status

Job Actions

Action	Description
View Errors	Show error details (for failed jobs)
View Details	Show complete job information

---

Settings Tab

The Settings tab manages Letzshop integration configuration for the selected store.

CSV Feed URLs

Configure the URLs for Letzshop product CSV feeds:

• French (FR): URL for French product data
• German (DE): URL for German product data
• English (EN): URL for English product data

Import Settings

• Batch Size: Number of products to process per batch (100-5000)

Export Settings

• Include Inactive: Whether to include inactive products in exports

API Credentials

Configure Letzshop API access:

• API Key: Your Letzshop API key (encrypted at rest)
• Test Connection: Verify API connectivity

Sync Settings

• Auto-Sync Enabled: Enable automatic order synchronization
• Sync Interval: How often to sync orders (in minutes)

---

API Endpoints

Products

Endpoint	Method	Description
/admin/products	GET	List marketplace products with filters
/admin/products/stats	GET	Get product statistics
/admin/letzshop/stores/{id}/export	GET	Download CSV export
/admin/letzshop/stores/{id}/export	POST	Export to pickup folder

Jobs

Endpoint	Method	Description
/admin/letzshop/stores/{id}/jobs	GET	List jobs for store
/admin/marketplace-import-jobs	POST	Create import job

Orders

See Letzshop Order Integration for complete order API documentation.

---

Best Practices

Product Management

1. Regular Imports: Schedule regular imports to keep product data current
2. Export Before Sync: Export products before Letzshop's pickup schedule
3. Monitor Jobs: Check the Jobs tab for failed imports/exports

Order Processing

1. Check Exceptions First: Resolve exceptions before confirming orders
2. Verify Tracking: Ensure tracking numbers are valid before submission
3. Monitor Sync Status: Check for failed order syncs in Jobs tab

Troubleshooting

1. Products Not Appearing: Verify CSV URL is accessible and valid
2. Export Failed: Check write permissions on exports directory
3. Orders Not Syncing: Verify API credentials and test connection