Polar verbinden und seine Bestellungen mit Besuchen verknüpfen

01Polar verbinden

1. 1

   Einen Zugriffstoken in Polar erstellen

   Tally liest nur deine Bestellungen und muss nie Geld bewegen. Öffne in Polar Settings, Access Tokens, erstelle einen Organisations-Token und gib ihm nur diese Scopes:

   Berechtigung	Zugriff	Wozu
   Organizations	organizations:read	Der Name der Organisation, damit du erkennst, welche verbunden ist.
   Orders	orders:read	Jede Zahlung: Betrag, Steuer, Metadaten und die E-Mail des Kunden (sofort gehasht, nie gespeichert).
   Refunds	refunds:read	Erstattungen.
   Disputes	disputes:read	Rückbuchungen: Streitfälle, die du verloren hast.
   Webhooks	webhooks:write	Tally legt einen eigenen Webhook-Endpunkt an, damit Zahlungen binnen Sekunden ankommen.

   Ein Sandbox-Token geht auch: Tally versucht es in der Sandbox von Polar, wenn die Produktion den Token nicht kennt.

2. 2

   Den Zugriffstoken einfügen

   Öffne auf der Seite Integrations deiner Website (oder im Schritt Payments, wenn du eine Website hinzufügst) Polar und fülle aus:

   • Access token: Er beginnt mit polar_oat_. Tally speichert ihn verschlüsselt und zeigt ihn nie wieder an.

   Klicke dann auf Connect Polar.

3. 3

   Tally prüft den Zugang und importiert das letzte Jahr

   Jeder fehlende Scope des Tokens wird genannt, ein eigener Webhook-Endpunkt kommt hinzu, damit neue Bestellungen sofort ankommen, und die letzten 365 Tage werden importiert, Erstattungen und verlorene Streitfälle inklusive.

02Die Besucher-ID in den Metadaten übergeben

Wo dein Server den Checkout erstellt, lies das Cookie _tally_vid und übergib es als tally_visitor_id in metadata: Polar kopiert es in die Bestellung und das Abo, Verlängerungen folgen also. An einem Checkout-Link hängst du die Besucher-ID als reference_id an, die Polar in den Metadaten des Checkouts behält.

// Express with cookie-parser, where you create the Polar checkout.
app.post('/checkout', async (req, res) => {
  const visitorId = req.cookies['_tally_vid'];
  const response = await fetch('https://api.polar.sh/v1/checkouts/', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.POLAR_ACCESS_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      products: ['your-product-id'],
      metadata: visitorId ? { 'tally_visitor_id': visitorId } : {},
      success_url: 'https://example.com/thanks?checkout_id={CHECKOUT_ID}',
    }),
  });
  const checkout = await response.json();
  res.redirect(303, checkout.url);
});

// On pages with Polar checkout links: add the visitor id as reference_id. Polar's embed
// marks its links with data-polar-checkout; use your own selector for plain links.
const visitorId = (document.cookie.match(/(?:^|; )_tally_vid=([\w-]+)/) || [])[1];
for (const link of document.querySelectorAll('a[data-polar-checkout]')) {
  const url = new URL(link.href);
  if (visitorId && !url.searchParams.has('reference_id')) {
    url.searchParams.set('reference_id', visitorId);
    link.href = url.href;
  }
}

03Auf einer Website ohne Cookies

Ohne Cookie gibt es keine ID zum Übergeben, identifiziere den Käufer also mit der E-Mail, mit der er bezahlt: Ziele und identify.

04Prüfen, ob es geklappt hat

05Was nicht gelesen wird