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

```http
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:

```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](./letzshop-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.
