orion/app/modules/marketplace/docs/api.md

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

GET /api/v1/store/letzshop/export?language=fr
Authorization: Bearer <store_token>

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

GET /api/v1/admin/letzshop/export?store_id=1&language=fr
Authorization: Bearer <admin_token>

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:

# 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.

---

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

---

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

---

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

1. Retrieve Unconfirmed Shipments

Query:

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.