VibeFox USPS for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.

PHP: 8.0 oder neuer.

USPS-Developer-Portal-App (nur für Live-Tarife): Melden Sie sich mit einem kostenlosen USPS-Geschäftskonto im USPS Developer Portal (developers.usps.com) an, erstellen Sie eine App und kopieren Sie deren Consumer Key und Consumer Secret. Das Plugin verwendet die aktuellen USPS-APIs mit OAuth 2.0. USPS hat die alte Web-Tools-API (User ID und XML) am 25. Januar 2026 abgeschaltet, daher funktioniert eine Web-Tools-User-ID nicht mehr. Ohne Schlüssel werden nur die Festpreise verwendet.

Ship-from ZIP code: Für Live-Tarife benötigen Sie die 5-stellige US-Postleitzahl, von der die Pakete versendet werden.

VibeFox-Lizenzschlüssel: Kauf auf vibefox.net. Ein Schlüssel gilt für eine Domain.

Installation

1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Alternativ können Sie den Ordner vfd_usps per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Shipping > VibeFox USPS oder klicken Sie auf der Plugins-Seite unter dem Namen des Plugins auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzbereich oben auf der Seite ein und klicken Sie auf Activate.

5. Geben Sie den Consumer Key und das Consumer Secret ein, die 5-stellige Ship from ZIP code und wählen Sie die Dienste aus. Wenn die Shopwährung nicht USD ist, geben Sie den USD exchange rate ein.

6. Fügen Sie VibeFox USPS unter WooCommerce > Settings > Shipping > Shipping zones einer Versandzone hinzu oder aktivieren Sie Ignore shipping zones und wählen Sie die Länder aus.

7. Optional können Sie Festpreise als Ersatz eingeben.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Shipping > VibeFox USPS. Sie gelten für alle Versandzonen. Wenn Sie die Methode einer Zone hinzufügen, hat das Zonenfenster nur ein Feld:

Title (zone): der Name dieser Option in der Kasse. Leer lassen, um den globalen Name zu verwenden.

Jedes Mal, wenn Sie die Einstellungen speichern, werden das zwischengespeicherte USPS-Token und die Tarife gelöscht. Sie können auch im Abschnitt USPS API auf Clear cached USPS token and rates klicken. Warnungen oberhalb der Einstellungen zeigen an, wenn nur einer der Schlüssel gesetzt ist, keine Schlüssel und keine Festpreise vorhanden sind, der Ship-from ZIP code fehlt, kein Dienst ausgewählt ist, der USD exchange rate fehlt oder die Testumgebung eingeschaltet ist.

General

Enable/Disable: schaltet die Methode in allen Zonen gleichzeitig ein oder aus.

Name: der Name der Versandmethode, der in der Kasse angezeigt wird. Standard: USPS.

Tax status: USPS-Preise enthalten keine Steuern. Taxable lässt WooCommerce die Versandsteuer auf die Kosten aufschlagen, None tut dies nicht.

USPS API (Live-Tarife)

Consumer Key: der Consumer Key (client_id) Ihrer USPS-Developer-App.

Consumer Secret: das Consumer Secret (client_secret) derselben App.

Test environment: verwendet die USPS Testing Environment for Mailers. Nur für Apps mit Zugang dazu. Für echte Preise ausgeschaltet lassen. Standard: aus.

Prices: welche USPS-Preise verwendet werden.

Services: die USPS-Dienste, die angeboten werden dürfen. Angezeigt wird der günstigste ausgewählte Dienst, den USPS für das Paket anbietet. Flat-Rate-, Cubic-, Hold-for-Pickup- und Sunday-Preise werden nie verwendet. Standard: USPS Ground Advantage, Priority Mail und First-Class Package International Service.

USD exchange rate: USPS-Preise sind in USD. Wenn Ihre Shopwährung nicht USD ist, geben Sie den Preis von 1 USD in Ihrer Shopwährung ein, zum Beispiel 0.92. Ohne ihn werden keine Live-Tarife verwendet, und es gelten die Festpreise. Nicht nötig, wenn die Shopwährung USD ist.

Versand ab und Paket (USPS-Preise hängen von der Versand-Postleitzahl, dem Gewicht und der Paketgröße ab)

Ship from ZIP code: die 5-stellige US-Postleitzahl, von der die Pakete versendet werden. Eine ZIP+4-Postleitzahl wird auf 5 Stellen gekürzt. Andere Werte werden mit einer Meldung abgelehnt.

Box size: optionale Kartonmaße in der Maßeinheit Ihres Shops, zum Beispiel 30x20x15. Leer lassen, um die Größe aus den Produktmaßen zu bilden: die längste Länge, die breiteste Breite und die gestapelten Höhen. Hat ein Produkt keine Maße, wird ein Karton mit 10 x 8 x 4 Zoll verwendet.

Default product weight (kg): das Gewicht für Produkte ohne Gewicht, bei USPS-Tarifen, Gewichtsgrenzen und Gewichtsstufen. Standard: 0.5.

Festpreise (Preise in Ihrer Shopwährung; werden verwendet, wenn keine API-Schlüssel eingegeben sind, und als Ersatz, wenn USPS keinen Tarif liefert: API nicht erreichbar, falsche Schlüssel, kein Dienst oder ein Ziel ohne US-Postleitzahl; lassen Sie beide leer, um die Methode in diesem Fall auszublenden)

Country prices: Preise nach Zielland und Warenkorbgewicht. Klicken Sie auf + Add country, um eine Zeile hinzuzufügen, und auf das Kreuz, um eine zu entfernen. Die Spalten sind Price sowie die Gewichtsstufen XS (bis 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) und XL (über 5 kg). Eine leere oder 0-Stufe verwendet Price. Die Zeile * Default gilt für alle anderen Länder. Werte, die keine Zahlen sind, werden mit einer Meldung gelöscht.

Fallback cost: ein fester Preis, wenn kein Länderpreis passt. Leer lassen, um die Methode in diesem Fall auszublenden.

Fixed price is: Per order berechnet den Preis einmal. Per item (each item priced by its own weight x quantity) berechnet jeden Artikel nach seinem eigenen Gewicht (das Standardgewicht, wenn er keins hat) und multipliziert es mit der Menge. USPS-Live-Tarife werden immer für das gesamte Paket angefragt.

Bedingungen

Free shipping from: die Warenkorb-Zwischensumme, ab der diese Methode kostenlos ist. Dann wird keine Anfrage an USPS gesendet. Leer lassen, um nie kostenlosen Versand anzubieten.

Minimum subtotal: die Methode nur anzeigen, wenn die Warenkorb-Zwischensumme mindestens diesen Betrag erreicht. Leer lassen, um sie immer anzuzeigen.

Min weight (kg): das minimale Warenkorbgewicht, damit diese Methode erscheint. 0 bedeutet keine Grenze.

Max weight (kg): die Methode wird ab diesem Warenkorbgewicht ausgeblendet. Standard: 30. USPS akzeptiert bis zu 70 lb (31,7 kg). 0 bedeutet keine Grenze.

Excluded shipping classes: blendet die Methode aus, wenn der Warenkorb ein Produkt aus einer dieser WooCommerce-Versandklassen enthält.

Verfügbarkeit ohne Versandzonen

Ignore shipping zones: bietet die Methode für die unten genannten Länder auch dann an, wenn sie keiner Versandzone hinzugefügt wurde.

Countries: die Zielländer für diesen Modus. Leer lassen, um alle Versandländer des Shops zu verwenden. Dieses Feld wird nur verwendet, wenn Ignore shipping zones eingeschaltet ist.

Erweitert

Debug log: protokolliert API-Anfragen und die Tarifberechnung unter WooCommerce > Status > Logs, Quelle vfd-usps. API-Fehler werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. Schlüssel, Tokens und Kundenadressen werden nie protokolliert.

Remove data on uninstall: wenn eingeschaltet, entfernt das Löschen des Plugins alle Plugin-Einstellungen und Zonenmethoden. Deaktivieren löscht nie Einstellungen.

So funktioniert es in der Kasse

Wenn der Kunde eine Lieferadresse eingibt, fragt WooCommerce das Plugin nach einem Tarif. Das Plugin prüft zuerst die Bedingungen: Warenkorbgewicht, Mindestzwischensumme und ausgeschlossene Versandklassen. Gilt kostenloser Versand, wird die Methode mit dem Preis 0 angezeigt und es wird keine Anfrage an USPS gesendet.

Das Plugin holt ein OAuth-Token von USPS und behält es, bis es abläuft. Ein von USPS abgelehntes Token wird erneuert und die Anfrage wiederholt. Für Ziele in den USA und ihren Territorien (einschließlich Puerto Rico, der US-Jungferninseln und Guam) fragt es die Domestic-Prices-API ab und benötigt die 5-stellige Postleitzahl des Kunden. Für andere Länder fragt es die International-Prices-API mit Land und Postleitzahl ab.

Die Anfrage enthält die Postleitzahl des Versandorts, das Warenkorbgewicht in Pfund, die Paketgröße in Zoll und die Preisart. Pakete über 70 lb erhalten die Festpreise. Der Kunde sieht eine Option mit dem günstigsten ausgewählten Dienst, umgerechnet in Ihre Shopwährung.

Jeder Tarif wird 1 Stunde zwischengespeichert. Ein fehlgeschlagener Tarif wird 10 Minuten gemerkt. Nach einem Timeout, einem Serverfehler, einem Ratenlimit oder abgelehnten Schlüsseln wird USPS 5 Minuten lang nicht angefragt. Das HTTP-Timeout beträgt 10 Sekunden. Beim Deaktivieren des Plugins werden das zwischengespeicherte Token und die Tarife gelöscht.

Wenn USPS keinen Tarif liefert, stammt der Preis aus Country prices und danach aus Fallback cost. Trifft nichts davon zu, wird die Methode ausgeblendet. Der Kunde sieht nie USPS-Fehlertexte.

Die Methode funktioniert in der klassischen Kasse und in den Warenkorb- und Kassen-Blöcken. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin berechnet nur Tarife. Es kauft keine Frankierung oder Versandetiketten, bucht keine Abholungen, verfolgt keine Sendungen und lässt Kunden keine Postfiliale oder Abholstelle wählen. Es zeigt eine Option, nicht mehrere USPS-Dienste. Es gibt keine Kartonpackung: Der Warenkorb wird als ein Paket berechnet. Versicherung und andere Zusatzleistungen sind nicht enthalten.

Bestellungen

Bei einem Live-Tarif speichert die Versandposition der Bestellung den USPS service, zum Beispiel USPS Ground Advantage. Der Shop-Manager sieht ihn auf dem Bestellbildschirm im Admin-Bereich.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzbereich befindet sich oben unter WooCommerce > Settings > Shipping > VibeFox USPS. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Bereich zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain. Mit Check now prüfen Sie den Status erneut, mit Change key geben Sie einen anderen Schlüssel ein und mit Remove key entfernen Sie ihn von dieser Website. Der Link Manage licenses and domains in your account öffnet Ihr vibefox.net-Konto.

Ein Schlüssel gilt für eine Domain. Das Entfernen des Schlüssels von einer Website gibt deren Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird USPS Kunden in der Kasse nicht angezeigt. Angemeldete Shop-Manager sehen es weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Eine Erinnerung erscheint auf der Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

USPS erscheint nicht in der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die Methode der Zone des Landes des Kunden hinzugefügt wurde (oder Ignore shipping zones eingeschaltet ist und das Land erlaubt ist). Prüfen Sie die Gewichtsgrenzen, die Minimum subtotal und die Excluded shipping classes. Ohne funktionierende USPS-Schlüssel braucht die Methode einen Festpreis (Country prices oder Fallback cost).

Live-Tarife erscheinen nicht: Prüfen Sie die Warnungen oben auf der Einstellungsseite. Schalten Sie Debug log ein und öffnen Sie WooCommerce > Status > Logs, Quelle vfd-usps. Dort werden falsche Schlüssel, die falsche Umgebung und USPS-Fehlermeldungen protokolliert. Inlandstarife benötigen die 5-stellige Postleitzahl des Kunden.

Mein Shop ist nicht in USD: USPS bietet nur Preise in USD an. Geben Sie den USD exchange rate ein. Ohne ihn wird der Live-Tarif nicht verwendet, und stattdessen wird der Festpreis angezeigt.

Eine Web-Tools-User-ID funktioniert nicht: Die alte Web-Tools-API ist abgeschaltet. Erstellen Sie eine App im USPS Developer Portal und verwenden Sie deren Consumer Key und Consumer Secret.

Tarife wirken nach einer Änderung veraltet: Der Zwischenspeicher wird beim Speichern der Einstellungen geleert. Sie können auch auf Clear cached USPS token and rates klicken.

Der Lizenzbereich zeigt einen Fehler: Folgen Sie der Meldung im Bereich. Wenn der Schlüssel zum Beispiel schon auf einer anderen Domain verwendet wird, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Hat sich die Adresse der Website geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Ist der Lizenzserver nicht erreichbar, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.

Deinstallation

Deaktivieren des Plugins behält die Einstellungen und löscht nur das zwischengespeicherte Token und die Tarife. Zum Entfernen deaktivieren Sie das Plugin und löschen es auf der Seite Plugins. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins sowie das zwischengespeicherte Token und die Tarife werden immer entfernt. Einstellungen und Zonenmethoden werden nur entfernt, wenn Remove data on uninstall eingeschaltet war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Versandpositionen.

USPS ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit USPS verbunden noch wird es von USPS unterstützt.