Rückgaben und Stornos

Schickt ein Kunde eine Bestellung zurück, storniert sie oder wird die Zahlung zurückgebucht, soll dafür keine Provision fließen. Auf dieser Seite lernst du, wie dein Shop das mit einem Storno meldet: eine Anfrage pro Bestellung, und das gebuchte Geld geht dorthin zurück, woher es kam.

Kurz gesagt:

• Sende POST https://cli.gs/api/v1/track/reversal mit der orderId und einem reason.
• Ein Storno nimmt die ganze Provision zurück und schreibt Provision und Netzwerkgebühr deinem Guthaben gut.
• Er funktioniert, bis die Provision für eine Auszahlung festgeschrieben ist. Danach lautet die Antwort 409 CONVERSION_FINAL.
• Stornos dürfen wiederholt werden und werden wie Conversion-Meldungen signiert.

Was ein Storno bewirkt

• War die Provision gebucht, wird sie vom Guthaben des Publishers abgezogen, egal ob sie gerade vorläufig oder verfügbar ist. Provision und Netzwerkgebühr werden deinem Guthaben gutgeschrieben.
• War die Conversion nie gebucht, etwa weil sie noch zur Prüfung geparkt war, ändert sich nur ihr Status.
• Der Status der Conversion wird REVERSED, und der Publisher wird benachrichtigt. Hast du eine Status-Rückmeldung eingerichtet, erhält dein Shop conversion.reversed.

Wie lange ein Storno möglich ist

Ein Storno ist möglich, solange die Conversion offen, freigegeben, fällig oder in Prüfung ist. Sobald ihre Provision für eine Publisher-Auszahlung festgeschrieben ist, ist sie endgültig. Die Anfrage wird dann mit 409 CONVERSION_FINAL abgelehnt.

Melde Rückgaben also zügig. Wähle eine Haltefrist, die dein Rückgaberecht abdeckt: siehe Bedingungen und Provisionsregeln. Die Haltefrist ist die Wartezeit zwischen Freigabe und Auszahlung.

Die Anfrage

POST https://cli.gs/api/v1/track/reversal
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Sende entweder orderId oder conversionId. Stornos werden genauso signiert wie Conversion-Meldungen: siehe Signierte Anfragen.

Gründe

Ein Storno nimmt immer die ganze Provision zurück. Teilrückgaben werden nicht unterstützt. Kommt nur ein Teil einer Bestellung zurück, entscheide nach deinen Bedingungen, ob du die ganze Conversion stornierst.

Beispiele

cURL

curl -X POST https://cli.gs/api/v1/track/reversal \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "100234", "reason": "RETURN", "note": "Retoure vom 12.10." }'

Node.js

// Call this from your refund or cancellation handler.
async function reportReversal(orderId, reason, note) {
  const res = await fetch("https://cli.gs/api/v1/track/reversal", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CLIGS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ orderId: String(orderId), reason, note }),
    signal: AbortSignal.timeout(5000),
  });
  const data = await res.json().catch(() => ({}));

  if (res.ok) return data;                         // { ok: true, conversionId, status, duplicate }
  if (res.status === 404) return null;             // no conversion for this order: nothing to reverse
  if (res.status === 409) {
    console.warn("Commission already final", data.conversionId);
    return null;
  }
  if (res.status >= 500 || res.status === 429) throw new Error("retry later");
  throw new Error(`cli.gs refused the reversal: ${res.status} ${data.error}`);
}

// await reportReversal("100234", "RETURN", "Retoure vom 12.10.");

In WooCommerce eignen sich die Hooks woocommerce_order_status_refunded und woocommerce_order_status_cancelled für diesen Aufruf. Rufe ihn bei Bestellungen mit _cligs_ref auf.

Antworten

{ "ok": true, "conversionId": "cmg3x1q2w0001abcd9876efgh", "status": "REVERSED", "duplicate": false }

Wie Conversion-Meldungen dürfen auch Stornos wiederholt werden. Test-Conversions lassen sich nicht stornieren; sie haben ohnehin nie Geld bewegt.

Weiter

Wenn manche Shopseiten deinen Server nicht aufrufen können, lies über das Tracking-Pixel als Fallback.