Wie fügt man in BigCommerce beim Bezahlvorgang „Round-Up“-Spenden hinzu?

This entry was posted in BigCommerce and tagged on by .

Das haben Sie wahrscheinlich schon einmal an der Kasse eines Supermarkts gesehen. Ihr Gesamtbetrag beträgt 47,35 $, und das System fragt Sie, ob Sie auf 48,00 $ aufrunden möchten, wobei die zusätzlichen 65 Cent an eine Wohltätigkeitsorganisation gehen. Es ist eine kleine Bitte, der man leicht zustimmen kann, und im Laufe der Zeit kommt dabei eine ordentliche Summe zusammen. Das Gleiche können Sie auch in einem BigCommerce-Shop umsetzen. Diese Funktion ist zwar nicht standardmäßig integriert, lässt sich aber problemlos hinzufügen. Sie benötigen lediglich eine kleine Backend-Funktion und die Server-to-Server (S2S) Cart-API von BigCommerce, damit es funktioniert. So habe ich es umgesetzt.

So funktioniert es, Schritt für Schritt

  1. Der Kunde gelangt zur Kasse, und der Warenkorb-Gesamtbetrag wird wie gewohnt berechnet.
  2. Er sieht ein Kontrollkästchen mit einem Text wie „Meine Bestellung aufrunden, um die Differenz zu spenden“.
  3. Wenn er es anklickt, fügt eine kleine Backend-Funktion dem Warenkorb eine neue Position namens „Spende“ hinzu, deren Preis der Aufrundungsdifferenz entspricht.
  4. Der Warenkorb-Gesamtbetrag wird sofort aktualisiert, und die Spende erscheint als eigene Position auf der Bestellung.

Wichtig ist, dass dies nicht nur auf dem Bildschirm geschehen darf. Man kann nicht einfach eine höhere Zahl anzeigen und es dabei belassen. BigCommerce muss diese Spende tatsächlich als echten Artikel im Warenkorb erkennen, sonst wird sie später weder auf der Bestellung noch in Berichten korrekt angezeigt.

Warum ich eine Backend-Funktion verwendet habe, anstatt dies im Browser zu erledigen

Mit BigCommerce lassen sich Warenkorbdaten recht einfach über den Browser auslesen, doch Änderungen am Warenkorb, die vertrauenswürdig sein sollen, müssen an einem sichereren Ort erfolgen. Würde man dies direkt im Browser versuchen, müsste man die API-Schlüssel des Shops jedem offenlegen, der die Entwicklertools öffnet – und das möchte man natürlich nicht.

Stattdessen habe ich daher eine kleine serverlose Funktion (ich habe Vercel verwendet, aber jeder ähnliche Dienst funktioniert einwandfrei) als Zwischenschicht eingesetzt. Sie verwaltet die API-Schlüssel und ist die einzige Instanz, die tatsächlich mit BigCommerce kommuniziert. Dadurch hast du außerdem eine zentrale Stelle, an der du die Regeln steuern kannst, beispielsweise wie viel jemand spenden darf oder ob du auf den nächsten Dollar oder die nächsten fünf Dollar aufrundest.

Was die Funktion konkret macht

Nichts Besonderes. Sie ruft den Warenkorb-Gesamtbetrag ab, berechnet, wie viel zusätzlich benötigt wird, um ihn aufzurunden, und fügt diesen Betrag über die S2S-Cart-API als Einzelposten hinzu.

// /api/round-up.js (Vercel serverless function)
export default async function handler(req, res) {
  const { cartId, currentTotal } = req.body;

  const roundedTotal = Math.ceil(currentTotal);
  const donationAmount = +(roundedTotal - currentTotal).toFixed(2);

  if (donationAmount <= 0) {
    return res.status(200).json({ message: "Already a round number" });
  }

  // Add the donation as a line item using the S2S Cart API
  const response = await fetch(
    `https://api.bigcommerce.com/stores/{store_hash}/v3/carts/${cartId}/items`,
    {
      method: "POST",
      headers: {
        "X-Auth-Token": process.env.BC_API_TOKEN,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        line_items: [
          {
            name: "Round-Up Donation",
            quantity: 1,
            list_price: donationAmount,
          },
        ],
      }),
    }
  );

  const data = await response.json();
  res.status(200).json(data);
}

Ein paar Dinge, die ich dabei gelernt habe:

  • Lass keine Duplikate entstehen. Wenn jemand das Kontrollkästchen aktiviert, deaktiviert und dann erneut aktiviert, musst du zuerst die alte Spendenposition entfernen und nicht einfach immer neue hinzufügen. Am einfachsten ist es, die von der API zurückgegebene Positions-ID zu speichern und sie an einem Ort abzulegen, auf den das Frontend zugreifen kann, beispielsweise in einem Cookie oder einem lokalen Status, der mit dem Warenkorb verknüpft ist.
  • Die Rundungsregel liegt in Ihrem Ermessen und ist nicht fest vorgegeben. Manche Shops runden auf den nächsten Dollar auf. Andere runden auf die nächsten fünf Dollar auf oder lassen den Käufer den Betrag selbst wählen. Halten Sie dies als eine Einstellung, die Sie ändern können, anstatt Math.ceil überall fest zu programmieren.
  • Manchmal benötigst du ein echtes Produkt und nicht nur eine Artikelposition. Je nachdem, wie dein Katalog und deine Steuern eingerichtet sind, benötigst du möglicherweise ein tatsächliches, verstecktes „Spenden“-Produkt in BigCommerce anstelle einer vollständig fiktiven Artikelposition, insbesondere wenn die Steuern dafür korrekt berechnet werden sollen.

Was passiert, wenn jemand seine Meinung ändert?

Es kommt auch vor, dass Nutzer das Kontrollkästchen deaktivieren. In diesem Fall benötigst du eine entsprechende Funktion, die die Spende entfernt:

await fetch(
  `https://api.bigcommerce.com/stores/{store_hash}/v3/carts/${cartId}/items/${donationLineItemId}`,
  {
    method: "DELETE",
    headers: { "X-Auth-Token": process.env.BC_API_TOKEN },
  }
);

Stellen Sie sicher, dass das Kontrollkästchen auf dem Bildschirm tatsächlich mit dem Inhalt des Warenkorbs übereinstimmt. Manchmal ändert ein Kunde die Menge oder löst einen Gutschein ein, was dazu führen kann, dass die Spende nicht mehr stimmt, ohne dass er das Kontrollkästchen überhaupt berührt hat. Es lohnt sich, bei jeder Änderung des Warenkorb-Gesamtbetrags noch einmal zu überprüfen, ob die Spende noch vorhanden ist.

Auf der Shop-Seite

Das Kontrollkästchen selbst ist einfach. Platzieren Sie es einfach in der Nähe der Bestellübersicht und verwenden Sie ein wenig JavaScript, um:

  • den aktuellen Warenkorb-Gesamtbetrag abzurufen,
  • Ihre Backend-Funktion aufzurufen, wenn das Kontrollkästchen aktiviert oder deaktiviert wird,
  • den Gesamtbetrag auf dem Bildschirm zu aktualisieren, sobald Sie eine Antwort erhalten haben.

Wenn sich der Warenkorb-Gesamtbetrag schnell ändern kann, beispielsweise wenn jemand einen Gutscheincode eingibt oder Mengen ändert, fügen Sie eine kurze Verzögerung ein, bevor Sie Ihre Funktion aufrufen. Andernfalls rufen Sie sie am Ende viel öfter auf, als nötig.

Vergiss Steuern und Buchhaltung nicht

Sprich mit dem Finanzverantwortlichen des Shops, bevor du diese Funktion implementierst – nicht erst danach. Spenden müssen oft steuerbefreit sein, und die meisten Händler möchten, dass Spendengelder getrennt von den tatsächlichen Produktverkäufen ausgewiesen werden. Das lässt sich im Vorfeld viel einfacher planen als später nachbessern.

Fazit

Diese Funktion sieht von außen betrachtet einfach aus – nur ein Kontrollkästchen –, betrifft aber den Warenkorb, die Steuern und die Art und Weise, wie die Gelder ausgewiesen werden. Die Verwendung einer kleinen Backend-Funktion in Verbindung mit der S2S Cart API sorgt für Übersichtlichkeit und Sicherheit und macht es einfach, die Rundungsregel später zu ändern, ohne den Code Ihres Themes anzutasten.

Wenn Sie vorhaben, so etwas zu entwickeln, sollten Sie sich im Vorfeld Zeit nehmen, um die Geschäftsregeln zu klären – zum Beispiel, wie hoch der Aufrundungsbetrag sein soll, wie die Steuern gehandhabt werden sollen und was passiert, wenn jemand seine Meinung ändert. Das wird Ihnen mehr Zeit sparen als alles andere.

Bitte kontaktieren Sie uns unter manish@bay20.com oder rufen Sie uns unter +91-9582784309 oder +91-8800519180 an, wenn Sie Unterstützung im Zusammenhang mit Bigcommerce benötigen. Sie können auch unsere Website besuchen, um sich über unsere Dienstleistungen zu informieren.