> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bestellungen erstellen und verwalten

> Erstellen Sie eine Bestellung über Ihre eigene Website, leiten Sie den Kunden zum Checkout weiter und verwalten Sie Zahlung, Stornierung und Rückerstattungen.

Eine Bestellung (Rechnung) enthält die Produkte, den Kunden und den Preis. Der Kunde bezahlt auf der gehosteten `checkout_url`, wo er eine beliebige Zahlungsmethode wählt, die Ihr Shop akzeptiert.

Bestellungen, die über die API erstellt werden, folgen denselben Regeln wie Ihre Storefront: Preise stammen aus Ihrem Katalog, Lagerbestand wird reserviert, Gutscheine und Produktregeln gelten, und Betrugsprüfungen werden ausgeführt.

## Bestellung erstellen

```bash cURL theme={"system"}
curl -X POST https://app.papelship.com/api/v1/invoices \
  -H "x-api-key: pk_live_your_key" \
  -H "x-store-hash: your_store_id" \
  -H "Idempotency-Key: 6f1c8a52-4f0e-4b8e-9a7c-2d1b3e5f7a90" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "buyer@example.com",
    "items": [
      { "product_id": "a1B2c3D4e5F6", "quantity": 1 },
      { "product_id": "Zx9Yw8Vu7Ts6", "variant_id": 881 }
    ],
    "coupon_code": "SUMMER10",
    "customer_ip": "203.0.113.10",
    "metadata": { "order_ref": "WEB-1042" }
  }'
```

```javascript Node.js theme={"system"}
const res = await fetch("https://app.papelship.com/api/v1/invoices", {
  method: "POST",
  headers: {
    "x-api-key": process.env.PAPELSHIP_API_KEY,
    "x-store-hash": process.env.PAPELSHIP_STORE_ID,
    "Idempotency-Key": order.id,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer_email: order.email,
    items: [{ product_id: "a1B2c3D4e5F6", quantity: 1 }],
    customer_ip: order.ip,
    metadata: { order_ref: order.id },
  }),
});
const { invoice } = await res.json();
// Leiten Sie den Kunden zu invoice.checkout_url weiter
```

```python Python theme={"system"}
import os, requests

res = requests.post(
    "https://app.papelship.com/api/v1/invoices",
    headers={
        "x-api-key": os.environ["PAPELSHIP_API_KEY"],
        "x-store-hash": os.environ["PAPELSHIP_STORE_ID"],
        "Idempotency-Key": order_id,
    },
    json={
        "customer_email": "buyer@example.com",
        "items": [{"product_id": "a1B2c3D4e5F6", "quantity": 1}],
        "metadata": {"order_ref": order_id},
    },
)
invoice = res.json()["invoice"]
```

```json Antwort (201) theme={"system"}
{
  "success": true,
  "invoice": {
    "id": "c35ffd-19a1b2c3d4e-8c7a20",
    "object": "invoice",
    "status": "pending",
    "currency": "USD",
    "total_cents": 3499,
    "customer_email": "buyer@example.com",
    "source": "api",
    "metadata": { "order_ref": "WEB-1042" },
    "checkout_url": "https://app.papelship.com/invoice/c35ffd-19a1b2c3d4e-8c7a20",
    "expires_at": "2026-10-04T15:00:00.000Z",
    "items": [ ... ]
  }
}
```

Leiten Sie den Kunden zur `checkout_url` weiter. Unbezahlte Bestellungen laufen nach 3 Stunden ab.

> [accordion] Felder, die Sie senden können
>
> | Feld | Hinweise |
> | :- | :- |
> | `customer_email` | Pflichtfeld. Erhält die Rechnungs-E-Mail und die Lieferung. |
> | `items` | Pflichtfeld. 1 bis 50 Positionen aus `product_id` (Hash-ID), `quantity` und `variant_id` für Produkte mit Varianten. |
> | `coupon_code` | Wird angewendet, wenn er für diese Produkte gültig ist. |
> | `customer_ip` | Die IP-Adresse des Käufers. Aktiviert Ihre Betrugs-, VPN- und Sperrlistenregeln für diese Bestellung. |
> | `expected_total_cents` | Optionale Prüfung. Der Aufruf schlägt mit `TOTAL_MISMATCH` fehl, wenn sich der Preis geändert hat. |
> | `shipping_address`, `shipping_rate_id` | Physische Produkte. Siehe unten. |
> | `custom_fields` | Antworten auf Ihre Checkout-Felder. |
> | `affiliate_code` | Schreibt die Bestellung einem Partner Ihres Affiliate-Programms gut. |
> | `send_email` | `false`, um die Rechnungs-E-Mail zu überspringen (Standard `true`). |
> | `metadata` | Bis zu 20 eigene Schlüssel/Wert-Strings. |

> [accordion] Fehler beim Erstellen
>
> | Code | Status | Bedeutung |
> | :- | :- | :- |
> | `PRODUCT_NOT_FOUND` | `404` | Eine `product_id` ist nicht in Ihrem Shop vorhanden. |
> | `OUT_OF_STOCK` | `409` | Nicht genügend Lagerbestand. `details.products` listet auf, was fehlt. |
> | `TOTAL_MISMATCH` | `409` | `expected_total_cents` stimmt nicht überein. `details.expected_total_cents` enthält den tatsächlichen Gesamtbetrag. |
> | `CURRENCY_MISMATCH` | `422` | Die Produkte haben unterschiedliche Währungen oder `currency` stimmt nicht überein. |
> | `INVALID_VARIANT` | `422` | Fehlende oder falsche `variant_id`. |
> | `ADDRESS_INVALID` | `422` | Unvollständige Lieferadresse. `details.fields` nennt die Felder. |
> | `CUSTOMER_BLOCKED` | `403` | Die E-Mail-Adresse oder IP steht auf Ihrer Sperrliste. |
> | `FRAUD_BLOCKED` | `403` | Ihre Betrugsregeln haben die Bestellung abgelehnt. |
> | `STORE_SUSPENDED` | `403` | Der Shop kann derzeit keine Bestellungen annehmen. |

## Physische Produkte

Fügen Sie für Produkte, die versendet werden, die Adresse hinzu. Rufen Sie die Optionen zuerst mit `POST /shipping/quote` ab oder lassen Sie `shipping_rate_id` weg, um den günstigsten Tarif zu verwenden.

```json theme={"system"}
{
  "customer_email": "buyer@example.com",
  "items": [{ "product_id": "Tsh1rtM3d1um", "variant_id": 2041, "quantity": 2 }],
  "shipping_address": {
    "full_name": "Alex Morgan",
    "phone": "+44 20 7946 0958",
    "country_code": "GB",
    "city": "London",
    "line1": "221B Baker Street",
    "postal_code": "NW1 6XE"
  },
  "shipping_rate_id": 12
}
```

Die Versandkosten werden zu `total_cents` addiert und als `shipping_cents` angezeigt. Ohne Adresse gibt der Kunde sie vor dem Bezahlen auf der Checkout-Seite ein. Versenden Sie die Bestellung nach der Zahlung mit [`POST /orders/{invoiceId}/shipments`](https://developers.papelship.com/de/user-api/fulfillment).

## Bestellstatus

| Status | Bedeutung |
| :- | :- |
| `pending` | Wartet auf die Zahlung des Kunden. |
| `payment_pending`, `payment_processing` | Der Kunde hat eine Methode gewählt; die Zahlung ist unterwegs. |
| `partial_payment` | Ein Teil des Betrags ist eingegangen (Krypto). |
| `manual_review_pending` | Eine manuelle Zahlung wartet auf Ihre Prüfung. |
| `completed` | Bezahlt und ausgeliefert. |
| `cancelled` | Vor der Zahlung storniert. |
| `expired` | Nicht rechtzeitig bezahlt. |

Warten Sie auf den Webhook `order.completed`, statt regelmäßig abzufragen. Siehe [Webhooks](https://developers.papelship.com/de/user-api/webhooks.md).

## Nach dem Erstellen der Bestellung

| Aktion | Endpunkt | Wann |
| :- | :- | :- |
| Als bezahlt markieren | `POST /invoices/{id}/complete` | Sie haben das Geld außerhalb von PapelShip erhalten (Banküberweisung, Bargeld). Liefert die Produkte aus. |
| Stornieren | `POST /invoices/{id}/cancel` | Die Bestellung ist unbezahlt. Gibt reservierten Lagerbestand frei. |
| Rückerstattung erfassen | `POST /invoices/{id}/refund` | Sie haben dem Kunden das Geld zurückgezahlt. Senden Sie `amount_cents` für eine Teilerstattung. |
| Gelieferte Inhalte ansehen | `GET /invoices/{id}/deliveries` | Lizenzschlüssel, Dateien und Notizen, die an den Kunden gesendet wurden. |
| Aktualisieren | `PATCH /invoices/{id}` | `metadata` oder `delivery_email` ändern. |

> [!TIP]
>
> Verwenden Sie Ihre eigene Bestell-ID als `Idempotency-Key` für Aufrufe zum Erstellen, Abschließen und Erstatten. Wiederholungen erzeugen dann niemals eine zweite Bestellung oder eine zweite Rückerstattung.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.