# Letzshop Development Documentation

## Introduction

Welcome to the Letzshop Development page. Here you’ll find details on:

- GraphQL API
- Authentication
- Playground
- Deprecations
- Order management
- Event system
- Data structures [1](https://letzshop.lu/en/dev)

---

## GraphQL API

Utilizing this API, you can retrieve and modify data on products, vendors, 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., vendor 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         |
| Vendor  | facebookLink, instagramLink, twitterLink, youtubeLink | `social_media_links` |
| Vendor  | owner               | `representative`                |
| Vendor  | 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-vendor 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`  
- `VendorCategoryCreated`, `Destroyed`, `Updated`  
- `VendorCreated`, `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.