Tracking über Gutscheincodes

Rekomi legt Gutscheine und Promotion-Codes in deinem Namen an und schreibt dem richtigen Affiliate den Verkauf gut, wenn ein Kunde einen Code im Checkout einlöst. Kein Klick-Cookie nötig, kein Tracking-Skript. Nutze das, wenn deine Käufer einen Code eintippen statt auf einen Link zu klicken (Influencer-Programme, Podcast-Spots, Offline-Werbung). In einem Workspace mit Stripe werden die Codes als Stripe-Gutscheine (Coupons) und Promotion-Codes angelegt; in einem mit Shopify verbundenen Workspace entstehen die Codes pro Affiliate stattdessen direkt in Shopify als Rabattcodes.

Erforderlicher Plan: ab Starter für den direkten API-Zugriff mit rk_live_*. Dashboard-Sitzungen funktionieren in jedem bezahlten Plan.

Konzepte

• Kampagnen-Gutschein: die Regeln des Rabatts. Entspricht 1:1 einem Stripe-coupon. Du legst Prozentsatz oder Betrag, Laufzeit, maximale Einlösungen und Ablaufdatum fest. Nach dem Anlegen ist der Rabatt unveränderlich (eine Regel von Stripe). Um einen Rabatt zu ändern, archivierst du den übergeordneten Gutschein und legst einen neuen an.
• Affiliate-Gutschein: ein einlösbarer Code, der zu genau einem Affiliate gehört. Entspricht 1:1 einem Stripe-promotion_code. Pro Affiliate sind mehrere erlaubt (Wunschvarianten wie SARAH20, SARAHSUMMER).

Attribution: Löst ein Kunde im Checkout einen Promotion-Code ein, sieht der Stripe-Webhook von Rekomi invoice.discounts[].promotion_code und schreibt den Verkauf dem Affiliate gut, dem der Code gehört. Ist overridesClickAttribution eingeschaltet (empfohlen und im Dashboard vorausgewählt), gewinnt der Gutschein auch dann, wenn ein Klick-Cookie existiert. Erstattungen stornieren die Provision, und sobald die Bestellung vollständig erstattet ist, markieren sie die Conversion als erstattet und senken den Einlösezähler.

Authentifizierung

Alle Endpunkte akzeptieren entweder ein Dashboard-JWT oder einen Bearer-Schlüssel der öffentlichen API:

Authorization: Bearer rk_live_xxx

Einen Schlüssel bekommst du unter /dashboard/settings/api-keys. Lesende Aufrufe brauchen die Berechtigung read, schreibende read_write.

Einen Kampagnen-Gutschein anlegen

Damit legst du die Rabattregeln fest, die die Codes pro Affiliate übernehmen.

POST /api/v1/campaigns/{programId}/coupons

Request-Body:

{
  "name": "Summer 20% off",
  "discountType": "PercentOff",
  "discountValue": 20,
  "discountCurrency": null,
  "duration": "Once",
  "durationInMonths": null,
  "maxRedemptionsPerCode": 100,
  "expiresAt": "2026-12-31T23:59:59Z",
  "selfMintMode": "Disabled",
  "grantedAffiliateIds": [],
  "maxCodesPerAffiliate": 0,
  "overridesClickAttribution": true,
  "productRefs": []
}

Validierung:

• discountType ist PercentOff (discountValue 1-100) oder AmountOff (discountValue als positive Anzahl der kleinsten Einheit von discountCurrency, also Cent bei USD und ganze Yen bei JPY; discountCurrency ist dann Pflicht, nach ISO 4217).
• duration ist Once | Repeating | Forever. Bei Repeating ist durationInMonths Pflicht (1-94).
• expiresAt muss, wenn gesetzt, in der Zukunft liegen.
• maxRedemptionsPerCode ist, wenn gesetzt, ≥ 1.
• productRefs: optionales Array von Stripe-Produkt-IDs (prod_...), auf die der Gutschein beschränkt wird. Höchstens 100 Einträge. Lass es weg oder sende ein leeres Array für einen Gutschein auf die ganze Bestellung (Standard). Kampagnen-Gutscheine lassen sich über diesen Endpunkt nur mit verbundenem Stripe-Weg anlegen; Workspaces ohne Stripe-Verbindung bekommen 422 stripe_not_connected. productRefs müssen Stripe-Produkt-IDs sein und gelten derzeit nur für Codes, die in Stripe angelegt werden.

Felder für selbst erstellte Codes (Self-Mint):

• selfMintMode: "Disabled" | "AllAffiliates" | "SpecificAffiliates". Legt fest, wer sich aus diesem Gutschein selbst einen Wunschcode erstellen darf. Self-Mint läuft derzeit über den Stripe-Weg: Affiliates von Workspaces ohne Stripe-Weg, über den Codes angelegt werden können (auch mit Shopify verbundene Shops), bekommen Self-Mint nicht angeboten, und der Endpunkt zum Erstellen liefert dort 422 stripe_not_connected.
• grantedAffiliateIds: die Positivliste der Affiliate-IDs, nur genutzt, wenn selfMintMode den Wert "SpecificAffiliates" hat. Entfernst du später einen Affiliate aus der Liste, werden auch alle Codes widerrufen, die er sich schon aus diesem Gutschein erstellt hat.
• maxCodesPerAffiliate: positive Obergrenze für die Zahl aktiver Codes, die ein einzelner Affiliate aus diesem Gutschein haben darf; 0 oder weggelassen heißt unbegrenzt.
• allowAffiliateSelfMint wird als Alias aus älteren Versionen weiter akzeptiert und spiegelt den Modus: true entspricht "AllAffiliates", false entspricht "Disabled".

Zum Anlegen eines Gutscheins braucht es zuerst eine aktive Zahlungsverbindung: Ohne Stripe-Verbindung bekommst du 422 stripe_not_connected.

Antwort: 201 Created mit dem vollständigen Datensatz des Kampagnen-Gutscheins, einschließlich stripeCouponId und productRefs (leeres Array, wenn der Gutschein für die ganze Bestellung gilt).

curl -X POST https://api.rekomi.com/api/v1/campaigns/$PROGRAM_ID/coupons \
  -H "Authorization: Bearer $REKOMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Summer 20% off",
    "discountType": "PercentOff",
    "discountValue": 20,
    "duration": "Once",
    "selfMintMode": "Disabled",
    "overridesClickAttribution": true
  }'

const res = await fetch(
  `https://api.rekomi.com/api/v1/campaigns/${programId}/coupons`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.REKOMI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Summer 20% off",
      discountType: "PercentOff",
      discountValue: 20,
      duration: "Once",
      selfMintMode: "Disabled",
      overridesClickAttribution: true,
    }),
  },
);
const coupon = await res.json();

Auflisten, aktualisieren, archivieren, löschen

Mit diesen Endpunkten verwaltest du bestehende Kampagnen-Gutscheine.

GET    /api/v1/campaigns/{programId}/coupons
GET    /api/v1/campaigns/{programId}/coupons/{id}
GET    /api/v1/campaigns/{programId}/coupons/affiliates   # approved affiliates for the self-mint allow-list picker; add ?couponId= to see isGranted and mintedCodeCount per affiliate
PATCH  /api/v1/campaigns/{programId}/coupons/{id}        # editable: name, self-mint settings, attribution toggle
POST   /api/v1/campaigns/{programId}/coupons/{id}/archive
DELETE /api/v1/campaigns/{programId}/coupons/{id}        # only when no per-affiliate codes exist

PATCH akzeptiert name, die Self-Mint-Einstellungen (selfMintMode, grantedAffiliateIds und das ältere allowAffiliateSelfMint), overridesClickAttribution und maxCodesPerAffiliate. Die Rabattregeln bleiben nach den Vorgaben von Stripe unveränderlich. Archivieren setzt isActive=false, deaktiviert alle zugehörigen Codes auf der Plattform, auf der sie angelegt wurden, und markiert sie lokal als widerrufen.

Einen Gutschein pro Affiliate erzeugen

Damit legst du einen einzelnen einlösbaren Code an, der zu einem Affiliate gehört.

POST /api/v1/affiliates/{affiliateId}/coupons

Request-Body:

{
  "campaignCouponId": "c0upon01-...",
  "code": "SARAH20"
}

• campaignCouponId ist Pflicht. Der Kampagnen-Gutschein muss zum selben Programm gehören wie der Affiliate.
• code ist optional. Ist er null, erzeugt Rekomi einen Code aus 8 Zeichen im Crockford-Stil (ohne 0/O, 1/I/L, damit er sich fehlerfrei abschreiben lässt). Ist er gesetzt, muss er auf ^[A-Z0-9_-]{3,32}$ passen.
• Codes sind unter den aktiven Codes einer Organisation eindeutig; ein widerrufener Code gibt seine Zeichenfolge für eine neue Erstellung frei. Duplikate liefern 422 code_already_taken.
• In einem mit Shopify verbundenen Workspace schlägt das Erzeugen von Codes pro Affiliate bei einem veralteten Shopify-Token mit 422 shopify_reconnect_required fehl; verbinde Shopify im Dashboard neu und versuche es erneut.

Antwort: 201 Created mit dem neuen Datensatz des Affiliate-Gutscheins, einschließlich stripePromotionCodeId.

Auflisten und widerrufen

Liste die Codes eines Affiliates auf oder deaktiviere einen.

GET    /api/v1/affiliates/{affiliateId}/coupons
DELETE /api/v1/affiliates/{affiliateId}/coupons/{id}    # revokes (deactivates in Stripe + marks inactive)

Codes, die Affiliates selbst erstellen

Setzt die Marke bei einem Kampagnen-Gutschein selfMintMode auf "AllAffiliates" (oder nennt den Affiliate unter "SpecificAffiliates" in grantedAffiliateIds), kann sich dieser Affiliate unter /a eigene Wunschcodes erstellen:

POST /api/me/coupons/mint

Request-Body:

{
  "campaignCouponId": "c0upon01-...",
  "code": "SARAH-SPRING"
}

Der Endpunkt läuft mit der Authentifizierung der Affiliate-Seite (Clerk-JWT, ohne Organisationskontext). Der Aufrufer muss zum selben Programm gehören, auf das der Kampagnen-Gutschein zielt, auf der Self-Mint-Positivliste des Gutscheins stehen, den Status Approved (freigegeben) haben und, falls eine Obergrenze gesetzt ist, innerhalb von maxCodesPerAffiliate bleiben; der Wunschcode muss den regulären Ausdruck oben erfüllen.

Verhalten bei der Attribution

Bei jedem Stripe-Ereignis invoice.paid oder customer.subscription.created liest Rekomi discounts[].promotion_code aus der Payload. Gehört der Promotion-Code zu einer deiner AffiliateCoupon-Zeilen, gilt:

1. overridesClickAttribution=true (Standard): Zuordnung zum Affiliate, dem der Gutschein gehört, auch wenn ein Klick-Cookie existiert. Conversion.attributionMethod = "coupon".
2. overridesClickAttribution=false: Zuerst werden Metadaten und Kundenhistorie geprüft. Schreiben diese niemandem den Verkauf gut, wird auf den Inhaber des Gutscheins zurückgegriffen. attributionMethod = "metadata_or_customer" oder "coupon", je nachdem, was gewonnen hat.
3. Checkout-Metadaten oder Kundenhistorie verweisen auf denselben Affiliate, dem der eingelöste Code gehört: Die Conversion erfasst attributionMethod = "coupon_with_metadata". (Der Webhook zieht in diesem Fall nie Klick-Cookies heran.)

Die Conversion-Zeile enthält affiliateCouponId mit Verweis auf den eingelösten Gutschein. Die Verarbeitung von Erstattungen nutzt das, um redemptionCount zu senken, und lastRedeemedAt wird bei jeder erfolgreichen Conversion ebenfalls aktualisiert.

Erstattungen

Wenn Stripe charge.refunded auslöst, macht Rekomi Folgendes:

1. Es findet die Conversion über payment_intent_id oder charge_id.
2. Es storniert die Provision anteilig zum erstatteten Betrag.
3. Es setzt den Status der Conversion auf Refunded und refundedAt, sobald die Erstattungen insgesamt den vollen ursprünglichen Betrag abdecken; bei einer Teilerstattung bleibt der ursprüngliche Status.
4. Ist affiliateCouponId gesetzt, senkt es den redemptionCount des Gutscheins nur bei der Erstattung, mit der die Conversion vollständig erstattet ist (nie bei Teilerstattungen, und so abgesichert, dass wiederholte Zustellungen den Zähler nie unter null drücken).
5. Es sendet den Webhook conversion.refunded.

Webhook-Ereignisse

Siehe die Referenz zu Webhooks. Ereignisse zu Gutscheinen gibt es in zwei Familien. campaign_coupon.created, campaign_coupon.updated, campaign_coupon.deactivated und campaign_coupon.deleted lösen für den übergeordneten Gutschein aus. affiliate_coupon.created, affiliate_coupon.deactivated und affiliate_coupon.revoked lösen für die einzelnen Codes pro Affiliate aus. Abonniere * für alles, oder liste beim Anlegen des Endpunkts jedes Gutschein-Ereignis einzeln auf; Platzhalter mit Präfix wie campaign_coupon.* werden nicht unterstützt.

Rate-Limits

Die Endpunkte für Kampagnen-Gutscheine und Gutscheine pro Affiliate teilen sich das Standardkontingent für authentifizierte Anfragen (600 Anfragen pro Minute und Schlüssel; siehe Rate-Limits). Die Rate-Limits von Stripe gelten unabhängig davon; wer mehr als ein paar Codes pro Sekunde in großen Mengen anlegt, kann mit 422 stripe_create_failed scheitern. Jede Anfrage trägt beim Zahlungsanbieter einen stabilen Idempotenzschlüssel. Du kannst eine Anfrage also gefahrlos wiederholen, ohne dass Codes doppelt entstehen.