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

# Affiliate-Programm

> Partner, Conversions und Auszahlungen abrufen, Partner einladen und auf Affiliate-Webhooks reagieren.

Mit den Affiliate-Endpunkten synchronisieren Sie Ihr Partnerprogramm mit Ihren eigenen Systemen: Partner auflisten, zugeordnete Bestellungen nachverfolgen und Auszahlungen verfolgen.

> [!NOTE]
>
> Ihr Shop muss für das Affiliate-Programm freigeschaltet sein. Beantragen Sie dies im Dashboard unter **Affiliates**. Bis dahin liefert jeder Affiliate-Endpunkt `403` mit dem Code `FEATURE_NOT_ENABLED`.

## Endpunkte

| Methode | Pfad | Beschreibung |
| :- | :- | :- |
| `GET` | `/affiliates/partners` | Partner auflisten. Filtern Sie nach `status` oder suchen Sie mit `q`. |
| `POST` | `/affiliates/partners` | Einen Partner per E-Mail einladen. Der Partner ist sofort aktiv. |
| `GET` | `/affiliates/conversions` | Zugeordnete Bestellungen mit dem jeweiligen Provisionsstatus auflisten. |
| `GET` | `/affiliates/payouts` | Auszahlungsanfragen auflisten. Offene Anfragen stehen zuerst. |

Das Freigeben von Partnern, das Prüfen markierter Conversions und das Senden von Auszahlungen erfolgen weiterhin im Dashboard.

## Beträge und IDs

* Beträge in API-Antworten sind Ganzzahlen in der kleinsten Währungseinheit. `commission: 499` in `USD` entspricht 4,99 \$.
* Webhook-Payloads verwenden die Hauptwährungseinheit. `commission: 4.99` entspricht 4,99 \$.
* Partner und Auszahlungen verwenden 16-stellige öffentliche IDs. Conversions verwenden die öffentliche `invoice_id` der Bestellung.

## Paginierung

Listen-Endpunkte liefern 25 Einträge pro Seite mit einem `next_cursor`. Geben Sie ihn als `cursor` zurück, um die nächste Seite zu erhalten. Auf der letzten Seite ist `next_cursor` gleich `null`.

```bash theme={"system"}
curl "https://app.papelship.com/api/v1/affiliates/conversions?status=valid&cursor=1832" \
  -H "x-api-key: your_api_key" \
  -H "x-store-hash: your_store_hash"
```

Jede Liste liefert außerdem `counts`, die Anzahl der Datensätze pro Status:

```json theme={"system"}
{
  "success": true,
  "conversions": [ ... ],
  "next_cursor": 1807,
  "counts": { "valid": 40, "flagged": 2, "rejected": 1 }
}
```

## Partner einladen

```bash theme={"system"}
curl -X POST https://app.papelship.com/api/v1/affiliates/partners \
  -H "x-api-key: your_api_key" \
  -H "x-store-hash: your_store_hash" \
  -H "Content-Type: application/json" \
  -d '{ "email": "creator@example.com", "name": "Alex Creator" }'
```

```json Antwort (201) theme={"system"}
{ "success": true, "id": "7fKq2LmN9xPa3RtB" }
```

Schlüssel mit reinem Lesezugriff können keine Partner einladen.

## So werden Bestellungen zugeordnet

Eine Bestellung wird einem Partner auf einem der folgenden Wege gutgeschrieben, in der Reihenfolge ihrer Priorität:

1. **Partner-Gutschein.** Der Käufer hat einen Gutschein verwendet, der an den Partner gebunden ist.
2. **Tracking-Link.** Der Käufer hat einen Partner-Link geöffnet: `https://your-store.com/any-page?ref=CODE` oder `https://your-store.com/r/CODE`. Die Storefront merkt sich den Klick für die Dauer des Cookie-Zeitfensters des Programms.
3. **API.** Sie haben beim Erstellen der Rechnung `affiliateCode` übergeben. Die Conversion hat `source: "api"`.

Die Conversion wird abgelehnt, wenn der Käufer der Partner selbst ist oder wenn ein anderer Gutschein verwendet wird und das Programm keine Kombination von Gutscheinen erlaubt. Sie wird zur Prüfung markiert, wenn die Bestellung einen hohen Betrugs-Score hat oder der Partner in kurzer Zeit ungewöhnlich viele Bestellungen erhält.

## Provisionsstatus

| `commission_state` | Bedeutung |
| :- | :- |
| `unpaid` | Die Bestellung ist noch nicht abgeschlossen. |
| `held` | Markiert. Wartet auf Ihre Prüfung im Dashboard. |
| `pending` | Innerhalb der Haltefrist. Siehe `available_at`. |
| `available` | Der Partner kann eine Auszahlung anfordern. |
| `none` | Die Conversion wurde abgelehnt. |

Rückerstattungen machen die Provision automatisch rückgängig. `commission` ist immer der Nettobetrag.

## Webhooks

Abonnieren Sie diese Ereignisse unter **Entwickler › Webhooks**. Sie verwenden denselben Umschlag und denselben `PapelShip-Signature`-Header wie Bestellereignisse.

| Ereignis | Zeitpunkt |
| :- | :- |
| `affiliate.partner_applied` | Jemand bewirbt sich über die Storefront für Ihr Programm. |
| `affiliate.conversion` | Eine zugeordnete Bestellung wird abgeschlossen und die Provision erfasst. Wird einmal pro Bestellung gesendet. |
| `affiliate.payout_requested` | Ein Partner fordert eine Auszahlung an. |
| `affiliate.payout_sent` | Sie markieren eine Auszahlung als gesendet. |

```json affiliate.conversion theme={"system"}
{
  "id": "evt_9b2c...",
  "object": "event",
  "type": "affiliate.conversion",
  "created": 1791100000,
  "livemode": true,
  "store": { "id": "0bHQn0bU2dei", "name": "Acme", "slug": "acme" },
  "data": {
    "object": {
      "object": "affiliate_conversion",
      "order_id": "c35ffd-19a1b2c3d4e-8c7a20",
      "partner": { "id": "7fKq2LmN9xPa3RtB", "email": "creator@example.com" },
      "source": "link",
      "link_code": "alex",
      "status": "valid",
      "commission": 4.99,
      "currency": "USD",
      "available_at": "2026-10-18T12:00:00.000Z",
      "created_at": "2026-10-04T12:00:00.000Z"
    }
  }
}
```

```json affiliate.payout_sent theme={"system"}
{
  "type": "affiliate.payout_sent",
  "data": {
    "object": {
      "object": "affiliate_payout",
      "id": "Qm3vX8kL2pN7rT4w",
      "partner": { "id": "7fKq2LmN9xPa3RtB", "email": "creator@example.com" },
      "amount": 125,
      "currency": "USD",
      "method": "crypto",
      "coin": "USDT",
      "network": "TRC20",
      "amount_coin": 125.04,
      "status": "sent",
      "tx_hash": "a1b2c3...",
      "created_at": "2026-10-02T09:30:00.000Z"
    }
  }
}
```

## Fehler

Affiliate-Fehler enthalten einen maschinenlesbaren `code`:

```json theme={"system"}
{ "success": false, "code": "ALREADY_MEMBER", "error": "This email is already a partner of your store." }
```

| Code | Status | Bedeutung |
| :- | :- | :- |
| `FEATURE_NOT_ENABLED` | `403` | Der Shop ist nicht für das Affiliate-Programm freigeschaltet. |
| `INVALID_EMAIL` | `400` | Die E-Mail-Adresse ist ungültig. |
| `ALREADY_MEMBER` | `409` | Die E-Mail-Adresse gehört bereits zu einem Partner dieses Shops. |
| `BANNED` | `409` | Der Partner ist für diesen Shop gesperrt. |
| `NOT_FOUND` | `404` | Der Partner oder Datensatz existiert nicht. |


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