VibeFox USPS for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et actif. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Application du USPS Developer Portal (uniquement pour les tarifs en temps réel) : connectez-vous au USPS Developer Portal (developers.usps.com) avec un compte professionnel USPS gratuit, créez une application et copiez son Consumer Key et son Consumer Secret. L'extension utilise les API USPS actuelles avec OAuth 2.0. USPS a fermé l'ancienne API Web Tools (User ID et XML) le 25 janvier 2026 : un User ID Web Tools ne fonctionne donc plus. Sans clés, seuls les prix fixes sont utilisés.

Ship-from ZIP code: les tarifs en temps réel nécessitent le code ZIP à 5 chiffres des États-Unis d'où les colis sont expédiés.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier vfd_usps dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Shipping > VibeFox USPS, ou cliquez sur Settings sous le nom de l'extension dans la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Saisissez le Consumer Key et le Consumer Secret, le Ship from ZIP code à 5 chiffres, puis choisissez les services. Si la devise de votre boutique n'est pas l'USD, saisissez le USD exchange rate.

6. Ajoutez VibeFox USPS à une zone d'expédition dans WooCommerce > Settings > Shipping > Shipping zones, ou activez Ignore shipping zones et choisissez les pays.

7. Facultatif : saisissez des prix fixes en secours.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Shipping > VibeFox USPS. Ils s'appliquent à toutes les zones d'expédition. Lorsque vous ajoutez la méthode à une zone, la fenêtre de la zone ne comporte qu'un seul champ :

Title (zone): le nom de cette option au paiement. Laissez-le vide pour utiliser le Name général.

À chaque enregistrement des réglages, le jeton USPS et les tarifs en cache sont effacés. Vous pouvez aussi cliquer sur Clear cached USPS token and rates dans la section USPS API. Les avertissements affichés au-dessus des réglages vous signalent lorsqu'une seule des clés est renseignée, qu'il n'y a ni clés ni prix fixes, que le Ship from ZIP code manque, qu'aucun service n'est sélectionné, que le USD exchange rate manque ou que l'environnement de test est activé.

General

Enable/Disable: active ou désactive la méthode dans toutes les zones à la fois.

Name: le nom de la méthode d'expédition affiché au paiement. Par défaut : USPS.

Tax status: les tarifs USPS n'incluent pas les taxes. Taxable permet à WooCommerce d'ajouter la taxe sur l'expédition au coût, None ne l'ajoute pas.

USPS API (tarifs en temps réel)

Consumer Key: le Consumer Key (client_id) de votre application développeur USPS.

Consumer Secret: le Consumer Secret (client_secret) de la même application.

Test environment: utilise le USPS Testing Environment for Mailers. Réservé aux applications qui y ont accès. Laissez-le désactivé pour obtenir de vrais tarifs. Par défaut : désactivé.

Prices: les tarifs USPS utilisés.

Services: les services USPS susceptibles d'être proposés. Le service sélectionné le moins cher que USPS propose pour le colis est affiché. Les tarifs Flat Rate, Cubic, Hold for Pickup et Sunday ne sont jamais utilisés. Par défaut : USPS Ground Advantage, Priority Mail et First-Class Package International Service.

USD exchange rate: les tarifs USPS sont en USD. Si la devise de votre boutique n'est pas l'USD, saisissez le prix de 1 USD dans la devise de votre boutique, par exemple 0.92. Sans cette valeur, les tarifs en temps réel ne sont pas utilisés et ce sont les prix fixes qui s'appliquent. Inutile si la devise de la boutique est l'USD.

Expédition depuis et colis (les tarifs USPS dépendent du code ZIP d'origine, du poids et de la taille du colis)

Ship from ZIP code: le code ZIP à 5 chiffres des États-Unis d'où les colis sont expédiés. Un code ZIP+4 est tronqué à 5 chiffres. Les autres valeurs sont refusées avec un message.

Box size: dimensions facultatives du carton, dans l'unité de dimensions de votre boutique, par exemple 30x20x15. Laissez vide pour calculer la taille à partir des dimensions des produits : la plus grande longueur, la plus grande largeur et les hauteurs empilées. Si un produit n'a pas de dimensions, un carton de 10 x 8 x 4 pouces est utilisé.

Default product weight (kg): le poids utilisé pour les produits sans poids, dans les tarifs USPS, les limites de poids et les tranches de poids. Par défaut : 0.5.

Prix fixes (prix dans la devise de votre boutique ; utilisés lorsqu'aucune clé API n'est saisie et en secours lorsque USPS ne renvoie aucun tarif : API indisponible, clés erronées, aucun service ou destination sans code ZIP américain ; laissez les deux vides pour masquer la méthode dans ce cas)

Country prices: prix selon le pays de destination et le poids du panier. Cliquez sur + Add country pour ajouter une ligne et sur la croix pour en supprimer une. Les colonnes sont Price et les tranches de poids XS (jusqu'à 1 kg), S (1–2 kg), M (2–3 kg), L (3–5 kg) et XL (plus de 5 kg). Une tranche vide ou égale à 0 utilise Price. La ligne * Default s'applique à tout autre pays. Les valeurs qui ne sont pas des nombres sont effacées avec un message.

Fallback cost: un prix forfaitaire lorsqu'aucun prix par pays ne correspond. Laissez-le vide pour masquer la méthode dans ce cas.

Fixed price is: Per order facture le prix une seule fois. Per item (each item priced by its own weight x quantity) calcule chaque article selon son propre poids (le poids par défaut s'il n'en a pas) et le multiplie par sa quantité. Les tarifs USPS en temps réel sont toujours demandés pour le colis entier.

Conditions

Free shipping from: le sous-total du panier à partir duquel cette méthode est gratuite. Aucune requête n'est envoyée à USPS dans ce cas. Laissez vide pour ne jamais proposer la livraison gratuite.

Minimum subtotal: n'affiche la méthode que si le sous-total du panier atteint au moins ce montant. Laissez vide pour toujours l'afficher.

Min weight (kg): le poids minimum du panier pour que cette méthode apparaisse. 0 signifie sans limite.

Max weight (kg): la méthode est masquée au-delà de ce poids de panier. Par défaut : 30. USPS accepte jusqu'à 70 lb (31,7 kg). 0 signifie sans limite.

Excluded shipping classes: masque la méthode si le panier contient un produit appartenant à l'une de ces classes d'expédition WooCommerce.

Disponibilité sans zones d'expédition

Ignore shipping zones: propose la méthode pour les pays indiqués ci-dessous, même si elle n'a pas été ajoutée à une zone d'expédition.

Countries: les pays de destination pour ce mode. Laissez vide pour utiliser tous les pays d'expédition de la boutique. Ce champ n'est utilisé que lorsque Ignore shipping zones est activé.

Avancé

Debug log: journalise les requêtes API et le calcul des tarifs dans WooCommerce > Status > Logs, source vfd-usps. Les erreurs API sont toujours journalisées, même si cette option est désactivée. Les clés, les jetons et les adresses des clients ne sont jamais journalisés.

Remove data on uninstall: si activé, la suppression de l'extension efface tous ses réglages et les méthodes des zones. La désactivation ne supprime jamais les réglages.

Fonctionnement au paiement

Lorsque le client saisit une adresse de livraison, WooCommerce demande un tarif à l'extension. L'extension vérifie d'abord les conditions : poids du panier, sous-total minimum et classes d'expédition exclues. Si la livraison gratuite s'applique, la méthode est affichée avec un prix de 0 et aucune requête n'est envoyée à USPS.

L'extension obtient un jeton OAuth auprès de USPS et le conserve jusqu'à son expiration. Un jeton refusé par USPS est renouvelé et la demande est répétée. Pour les destinations aux États-Unis et dans leurs territoires (dont Porto Rico, les îles Vierges américaines et Guam), elle interroge l'API Domestic Prices et a besoin du code ZIP à 5 chiffres du client. Pour les autres pays, elle interroge l'API International Prices avec le pays et le code postal.

La requête contient le code ZIP d'expédition, le poids du panier en livres, la taille du colis en pouces et le type de tarif. Les colis de plus de 70 lb reçoivent les prix fixes. Le client voit une option avec le service sélectionné le moins cher, converti dans la devise de votre boutique.

Chaque tarif est mis en cache pendant 1 heure. Un tarif en échec est mémorisé pendant 10 minutes. Après un délai dépassé, une erreur serveur, une limite de requêtes ou des clés rejetées, USPS n'est pas sollicité pendant 5 minutes. Le délai HTTP est de 10 secondes. La désactivation de l'extension supprime le jeton et les tarifs en cache.

Si USPS ne renvoie aucun tarif, le prix provient de Country prices, puis de Fallback cost. Si aucun ne s'applique, la méthode est masquée. Le client ne voit jamais les messages d'erreur de USPS.

La méthode fonctionne sur le paiement classique et sur les blocs Panier et Paiement. Elle est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension calcule uniquement les tarifs. Elle n'achète ni affranchissements ni étiquettes d'expédition, ne réserve pas d'enlèvements, ne suit pas les colis et ne permet pas au client de choisir un bureau de poste ou un point de retrait. Elle affiche une seule option, et non plusieurs services USPS. Il n'y a pas de remplissage de cartons : le panier est évalué comme un seul colis. L'assurance et les autres services supplémentaires ne sont pas inclus.

Commandes

Pour un tarif en temps réel, la ligne d'expédition de la commande enregistre le USPS service, par exemple USPS Ground Advantage. Le gestionnaire de la boutique le voit sur l'écran d'administration de la commande.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Shipping > VibeFox USPS. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, USPS n'est pas proposé aux clients au paiement. Les gestionnaires connectés le voient toujours, avec la mention (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

USPS n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, et que la méthode est ajoutée à la zone du pays du client (ou que Ignore shipping zones est activé et que le pays est autorisé). Contrôlez les limites de poids, le Minimum subtotal et les Excluded shipping classes. Sans clés USPS valides, la méthode nécessite un prix fixe (Country prices ou Fallback cost).

Les tarifs en temps réel n'apparaissent pas : consultez les avertissements en haut de la page des réglages. Activez Debug log et ouvrez WooCommerce > Status > Logs, source vfd-usps. Les clés erronées, le mauvais environnement et les messages d'erreur USPS y sont journalisés. Les tarifs nationaux nécessitent le code ZIP à 5 chiffres du client.

Ma boutique n'est pas en USD : USPS ne cote qu'en USD. Saisissez le USD exchange rate. Sans lui, le tarif en temps réel n'est pas utilisé et le prix fixe s'affiche à la place.

Un User ID Web Tools ne fonctionne pas : l'ancienne API Web Tools a été fermée. Créez une application dans le USPS Developer Portal et utilisez son Consumer Key et son Consumer Secret.

Les tarifs semblent périmés après une modification : le cache est vidé lors de l'enregistrement des réglages. Vous pouvez aussi cliquer sur Clear cached USPS token and rates.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net puis cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Désinstallation

La désactivation de l'extension conserve les réglages et ne fait que vider le jeton et les tarifs en cache. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension, ainsi que le jeton et les tarifs en cache, sont toujours supprimés. Les réglages et les méthodes des zones ne sont supprimés que si Remove data on uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs lignes d'expédition.

USPS est une marque appartenant à son titulaire respectif. Cette extension n'est ni affiliée à USPS ni approuvée par USPS.