orion/docs/guides/letzshop-marketplace-api.md

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

---

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

---

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

---

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

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