# Letzshop Marketplace Integration ## Introduction This guide covers the Orion platform's integration with the Letzshop marketplace, including: - **Product Export**: Generate Letzshop-compatible CSV files from your product catalog - **Order Import**: Fetch and manage orders from Letzshop - **Fulfillment Sync**: Confirm/reject orders, set tracking numbers - **GraphQL API Reference**: Direct API access for advanced use cases --- ## Product Export ### Overview The Orion platform can export your products to Letzshop-compatible CSV format (Google Shopping feed format). This allows you to: - Upload your product catalog to Letzshop marketplace - Generate feeds in multiple languages (English, French, German) - Include all required Letzshop fields automatically ### API Endpoints #### Store Export ```http GET /api/v1/store/letzshop/export?language=fr Authorization: Bearer ``` **Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `language` | string | `en` | Language for title/description (`en`, `fr`, `de`) | | `include_inactive` | bool | `false` | Include inactive products | **Response:** CSV file download (`store_code_letzshop_export.csv`) #### Admin Export ```http GET /api/v1/admin/letzshop/export?store_id=1&language=fr Authorization: Bearer ``` **Additional Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `store_id` | int | Required. Store ID to export | ### CSV Format The export generates a tab-separated CSV file with these columns: | Column | Description | Example | |--------|-------------|---------| | `id` | Product SKU | `PROD-001` | | `title` | Product title (localized) | `Wireless Headphones` | | `description` | Product description (localized) | `High-quality...` | | `link` | Product URL | `https://shop.example.com/product/123` | | `image_link` | Main product image | `https://cdn.example.com/img.jpg` | | `additional_image_link` | Additional images (comma-separated) | `img2.jpg,img3.jpg` | | `availability` | Stock status | `in stock` / `out of stock` | | `price` | Regular price with currency | `49.99 EUR` | | `sale_price` | Sale price with currency | `39.99 EUR` | | `brand` | Brand name | `TechBrand` | | `gtin` | Global Trade Item Number | `0012345678901` | | `mpn` | Manufacturer Part Number | `TB-WH-001` | | `google_product_category` | Google category ID | `Electronics > Audio` | | `condition` | Product condition | `new` / `used` / `refurbished` | | `atalanda:tax_rate` | Luxembourg VAT rate | `17` | ### Multi-Language Support Products are exported with localized content based on the `language` parameter: ```bash # French export curl -H "Authorization: Bearer $TOKEN" \ "https://api.example.com/api/v1/store/letzshop/export?language=fr" # German export curl -H "Authorization: Bearer $TOKEN" \ "https://api.example.com/api/v1/store/letzshop/export?language=de" # English export (default) curl -H "Authorization: Bearer $TOKEN" \ "https://api.example.com/api/v1/store/letzshop/export?language=en" ``` If a translation is not available for the requested language, the system falls back to English, then to any available translation. ### Using the Export 1. **Navigate to Letzshop** in your store dashboard 2. **Click the Export tab** 3. **Select your language** (French, German, or English) 4. **Click "Download CSV"** 5. **Upload to Letzshop** via their merchant portal --- ## Order Integration For details on order import and fulfillment, see [Letzshop Order Integration](order-integration.md). --- ## Letzshop GraphQL API Reference The following sections document the Letzshop GraphQL API for direct integration. --- ## GraphQL API Utilizing this API, you can retrieve and modify data on products, stores, and shipments. Letzshop uses GraphQL, allowing for precise queries. **Endpoint**: http://letzshop.lu/graphql Replace YOUR_API_ACCESS_KEY with your actual key or remove the Authorization header for public data. ## Authentication Some data is public (e.g., store description and product prices). For protected operations (e.g., orders or vouchers), an API key is required. Request one via your account manager or email: support@letzshop.lu Include the key: Authorization: Bearer YOUR_API_ACCESS_KEY --- ## Playground - Access the interactive GraphQL Playground via the Letzshop website. - It provides live docs, auto-complete (CTRL + Space), and run-time testing. - **Caution**: You're working on production—mutations like confirming orders are real. [1](https://letzshop.lu/en/dev) --- ## Deprecations The following GraphQL fields will be removed soon: | Type | Field | Replacement | |---------|---------------------|----------------------------------| | Event | latitude, longitude | `#lat`, `#lng` | | Greco | weight | `packages.weight` | | Product | ageRestriction | `_age_restriction` (int) | | Taxon | identifier | `slug` | | User | billAddress, shipAddress | on `orders` instead | | Store | facebookLink, instagramLink, twitterLink, youtubeLink | `social_media_links` | | Store | owner | `representative` | | Store | permalink | `slug` | [1](https://letzshop.lu/en/dev) --- ## Order Management via API Using the API, you can: - Fetch unconfirmed orders - Confirm or reject them - Set tracking numbers - Handle returns All of this requires at least "shop manager" API key access. Multi-store management is supported if rights allow. [1](https://letzshop.lu/en/dev) ### 1. Retrieve Unconfirmed Shipments **Query:** ```graphql query { shipments(state: unconfirmed) { nodes { id inventoryUnits { id state } } } } ``` [1](https://letzshop.lu/en/dev) --- ### 2. Confirm/Reject Inventory Units Use inventoryUnit IDs to confirm or reject: ```graphql mutation { confirmInventoryUnits(input: { inventoryUnits: [ { inventoryUnitId: "ID1", isAvailable: true }, { inventoryUnitId: "ID2", isAvailable: false }, { inventoryUnitId: "ID3", isAvailable: false } ] }) { inventoryUnits { id state } errors { id code message } } } ``` [1](https://letzshop.lu/en/dev) --- ### 3. Handle Customer Returns Use only after receiving returned items: ```graphql mutation { returnInventoryUnits(input: { inventoryUnits: [ { inventoryUnitId: "ID1" }, { inventoryUnitId: "ID2" } ] }) { inventoryUnits { id state } errors { id code } } } ``` [1](https://letzshop.lu/en/dev) --- ### 4. Set Shipment Tracking Number Include shipping provider and tracking code: ```graphql mutation { setShipmentTracking(input: { shipmentId: "SHIPMENT_ID", code: "TRACK123", provider: THE_SHIPPING_PROVIDER }) { shipment { tracking { code provider } } errors { code message } } } ``` [1](https://letzshop.lu/en/dev) --- ## Event System Subscribe by contacting support@letzshop.lu. Events are delivered via an SNS-like message structure: ```json { "Type": "Notification", "MessageId": "XXX", "TopicArn": "arn:aws:sns:eu-central-1:XXX:events", "Message": "{\"id\":\"XXX\",\"type\":\"XXX\",\"payload\":{...}}", "Timestamp": "2019-01-01T00:00:00.000Z", "SignatureVersion": "1", "Signature": "XXX", "SigningCertURL": "...", "UnsubscribeURL": "..." } ``` [1](https://letzshop.lu/en/dev) ### Message Payload Each event includes: - `id` - `type` (e.g., ShipmentConfirmed, UserCreated…) - `payload` (object-specific data) [1](https://letzshop.lu/en/dev) --- ## Event Types & Payload Structure A variety of event types are supported. Common ones include: - `ShipmentConfirmed`, `ShipmentRefundCreated` - `UserAnonymized`, `UserCreated`, `UserDestroyed`, `UserUpdated` - `VariantWithPriceCrossedCreated`, `...Updated` - `StoreCategoryCreated`, `Destroyed`, `Updated` - `StoreCreated`, `Destroyed`, `Updated` Exact payload structure varies per event type. [1](https://letzshop.lu/en/dev) --- ## Conclusion This Markdown file captures all information from the Letzshop development page, formatted for use in your documentation or GitHub.