Documentation FITLD

Il y a deux façons d'ajouter FITLD. Les deux mettent le même bouton Trouver ma taille sur vos pages produit.

Vous utilisez l'app ? Allez à Installer avec l'app Shopify. Avec le script, en bref :

1. 1Créez un compte marque sur fitld.com/signup
2. 2Ouvrez Installation dans votre tableau de bord et copiez le code (il contient votre identifiant de widget)
3. 3Shopify : Boutique en ligne → Thèmes → ⋯ → Modifier le code → ouvrez layout/theme.liquid et collez avant </body>. Site sur mesure : collez avant </body> sur vos pages produit.
4. 4De retour dans le tableau de bord, dans Installation → Vérifier qu'il est en ligne, collez l'adresse d'une page produit pour confirmer que le widget, votre identifiant et le guide des tailles sont bien en place.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-mode="product">
</script>

Avec data-mode="product", le widget place le bouton sous votre sélecteur de taille, sur les pages produit uniquement, puis sélectionne la taille confirmée dans votre propre sélecteur. Sans cet attribut, le script se charge sans rien afficher : utilisez l'un des modes ci-dessous pour placer le bouton vous-même.

Environ 5 minutes, sans code. L'app ajoute le bouton Trouver ma taille via les intégrations d'app de votre thème, envoie vos commandes et remboursements à FITLD toute seule, et votre forfait est ajouté à votre facture Shopify.

1. Installer l'app

1. 1Dans le Shopify App Store, ouvrez FITLD Size Finder et cliquez sur Installer. Shopify affiche ce que FITLD peut voir : approuvez.
2. 2Choisissez un forfait. Il est ajouté à votre facture Shopify.
3. 3Vous avez déjà un compte FITLD ? Si l'e-mail de votre boutique dans Shopify est celui que vous utilisez sur fitld.com, l'app vous propose de vous connecter et relier les deux. Vos guides des tailles et résultats restent dans un seul compte, et un forfait payé sur fitld.com continue.

2. Suivre les trois étapes de l'accueil

L'app s'ouvre sur Configurer FITLD. Chaque étape indique où cliquer, dans l'ordre, et se coche toute seule une fois faite.

1. 1Activez le bouton Trouver ma taille. Cliquez sur Ouvrir l'éditeur de thème : FITLD y est déjà activé dans les intégrations d'app. Cliquez sur Enregistrer, puis sur C'est enregistré dans l'app.
2. 2Donnez un guide des tailles à vos produits. Cliquez sur Ajouter des guides des tailles, cochez vos produits et cliquez sur Ajouter un guide des tailles. Choisissez un guide standard, ou utilisez Importer un guide des tailles pour lire celui que vous utilisez déjà.
3. 3Essayez-le sur votre boutique. Ouvrez un produit, appuyez sur Trouver ma taille et indiquez quelques mesures. De retour dans l'app, cliquez sur Vérifier à nouveau.

3. Voir vos résultats

Une fois le bouton en ligne, l'accueil montre combien d'acheteurs ont obtenu une taille, les commandes passées et combien ont été remboursées. Tableau de bord complet ouvre fitld.com, avec les rapports par produit et par taille.

Vérifier ou refaire une étape

Cliquez sur Guide de configuration dans l'accueil pour rouvrir les trois étapes, par exemple après un changement de thème ou l'ajout de produits. Si le bouton est désactivé dans votre thème, ou si plus aucun produit n'a de guide des tailles, l'accueil revient de lui-même aux étapes de configuration.

Vous préférez payer sur fitld.com, ou ne pas installer d'app ? Collez plutôt le script. Si votre boutique a déjà l'app FITLD, passez cette partie : le bouton apparaîtrait deux fois. Environ 15 minutes. Il vous faut votre identifiant de widget FITLD (tableau de bord, Installation) et un accès à l'administration Shopify.

1. Ajoutez le widget à votre thème

1. 1Dans l'administration Shopify, ouvrez Boutique en ligne → Thèmes. À côté de votre thème actif, choisissez ⋯ → Modifier le code.
2. 2Ouvrez layout/theme.liquid.
3. 3Collez le code ci-dessous juste avant la balise </body>, remplacez wgt_YOUR_WIDGET_ID par le vôtre et cliquez sur Enregistrer.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-mode="product"
  async>
</script>

Ne mettez jamais que votre identifiant de widget dans votre thème. Votre clé API secrète (fit_sk_…) reste dans le tableau de bord et sur votre propre serveur.

2. Associez vos produits

FITLD trouve le bon guide des tailles depuis la page produit. Si vos identifiants produit FITLD sont vos SKU Shopify, il n'y a rien à faire. Sinon, utilisez Produits → Lier des produits dans le tableau de bord pour relier chaque produit FITLD à sa page.

3. Connectez commandes et remboursements

C'est ce qui permet à FITLD de vous montrer si les clients ont acheté la taille recommandée et à quelle fréquence ces commandes ont été remboursées.

1. 1Dans le tableau de bord FITLD, ouvrez Installation → Connecter vos commandes. Saisissez votre adresse your-store.myshopify.com et copiez l'adresse du webhook.
2. 2Dans l'administration Shopify, ouvrez Paramètres → Notifications → Webhooks et cliquez sur Créer un webhook. Événement : Paiement de commande. Format : JSON. URL : celle que vous avez copiée. Enregistrez.
3. 3Créez un second webhook avec l'événement Création de remboursement, au format JSON, et la même URL.
4. 4Shopify affiche une clé de signature sous la liste des webhooks (« Vos webhooks seront signés avec… »). Copiez-la et collez-la dans le tableau de bord FITLD.
5. 5Cliquez sur Envoyer une notification de test dans Shopify, ou passez une commande test. Le tableau de bord indique quand la dernière commande est arrivée.

4. Vérifiez une page produit

Ouvrez un produit de votre boutique. Un bouton Trouver ma taille apparaît sous le sélecteur de taille. Vous pouvez aussi utiliser Installation → Vérifier qu'il est en ligne pour contrôler en une fois le script, votre identifiant de widget et le guide des tailles.

Avant que le widget puisse aider vos clients, FITLD vérifie que votre boutique est accessible et que vos pages produit sont liées à un guide des tailles. La vérification de la page Installation fait tout en une fois, sans deviner si le code est bien en place.

1. 1Ouvrez Installation → Vérifier qu'il est en ligne et collez l'adresse d'une page produit en ligne (par exemple https://your-store.com/products/classic-tee).
2. 2FITLD récupère la page, détecte votre plateforme et essaie de l'associer à un produit de votre catalogue.
3. 3Passez en revue les contrôles ci-dessous : chacun passe au vert quand il est validé.

Boutiques protégées par mot de passe

Si votre boutique (ou seulement cette page) est protégée par un mot de passe Shopify, choisissez Ma boutique demande un mot de passe et saisissez-le. FITLD l'utilise uniquement pour cette vérification ; il n'est jamais conservé. Une boutique encore protégée n'est pas visible des clients : le widget ne peut donc pas encore y apparaître.

Quatre façons de placer le bouton Trouver ma taille. Choisissez-en une par boutique.

Automatique sur les produits (recommandé)

Ajoutez data-mode="product". Le bouton apparaît sous votre sélecteur de taille, uniquement sur les pages produit, jamais sur l'accueil ni les collections.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-mode="product">
</script>

Ancrer à un sélecteur

Ajoutez data-attach-to pointant vers votre sélecteur de taille. Le bouton apparaît juste après. À utiliser quand la détection automatique ne reconnaît pas votre code.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-attach-to=".product-size-selector">
</script>

Plusieurs produits

Ajoutez vos propres boutons avec des attributs data-pid. Le widget les branche automatiquement.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID">
</script>

<button class="my-size-btn" data-pid="SKU001">Find My Size</button>
<button class="my-size-btn" data-pid="SKU002">Find My Size</button>

<script>
  document.querySelectorAll('.my-size-btn').forEach(function(btn) {
    btn.addEventListener('click', function() {
      FitAPI.setProduct(this.dataset.pid);
      FitAPI.open();
    });
  });
</script>

Bouton flottant (facultatif)

Ajoutez data-mode="fab" pour un bouton flottant en bas à droite.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-mode="fab">
</script>

Sélection automatique de la taille

Quand un client confirme une taille, le widget vérifie le stock et la sélectionne dans votre propre sélecteur : un <select>, des boutons radio ou des pastilles. La détection est automatique ; ancrez le sélecteur si votre code est inhabituel.

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-fitld-size-target="#size-picker">
</script>

Ajoutez quelques produits à la main, ou importez tout un catalogue d'un coup. L'import accepte un classeur Excel mis en forme (.xlsx) ou un CSV.

Téléchargez le modèle

Dans Produits → Importer un fichier, téléchargez le modèle FITLD. C'est un .xlsx mis en forme avec cinq feuilles : Products et Size chart (vos données), plus Instructions, Categories et Fields Guide.

Remplissez-le

L'import parcourt le haut de chaque feuille et trouve automatiquement la ligne d'en-tête : vous pouvez garder ou supprimer le titre, les mentions REQUIRED, les libellés et les lignes d'exemple grises. Les lignes d'exemple sont aussi validées : si vous en remplacez une, les listes déroulantes s'appliquent toujours.

Products : une ligne par produit, avec l'unit des mesures (cm ou in). Size chart : une ligne par taille (chaque taille a ses propres mesures). Choisissez le SKU du produit dans la liste sur la première ligne de taille, puis laissez le SKU vide sur les lignes suivantes : un SKU vide reprend celui du dessus, donc un t-shirt du S au XXL ne demande qu'une seule saisie du SKU. Le libellé d'une taille peut être n'importe quoi (M, 42, 6-12M, 34/36).

Vous préférez ne pas gérer les lignes de taille dans Excel ? Après l'envoi, l'aperçu vous permet de modifier le guide de chaque produit dans le navigateur : cliquez sur le nombre de tailles d'une ligne, réglez Number of sizes (tapez 4 et quatre lignes apparaissent, tapez 3 et une disparaît), choisissez l'unit et remplissez tailles et mesures avec une validation en direct. Le SKU est déjà renseigné pour chaque ligne : vous n'avez jamais à le retaper.

L'unité est portée par le produit, pas par la ligne de taille : vous pouvez donc les mélanger librement. Produit 1 en cm, produit 2 en in : chaque produit est lu dans sa propre unité et FITLD convertit en interne, sans effet sur le calcul.

FITLD valide d'abord chaque ligne et signale celles qui échouent avec une raison, pour que vous corrigiez et renvoyiez le fichier. Les lignes valides deviennent des produits du catalogue avec leur guide des tailles. Enregistrez en .xlsx : un CSV ne garde que la première feuille et dépend donc de l'ancien format à une seule feuille.

Deux façons d'afficher votre logo, votre nom et vos couleurs dans le widget. L'option 1 est la plus simple : il suffit d'ajouter des attributs à votre balise script.

Option 1 — Balise script (recommandée)

<script src="https://fitld.com/fitld-widget.js"
  data-widget-id="wgt_YOUR_WIDGET_ID"
  data-brand-logo="https://your-site.com/logo.svg"
  data-brand-name="Your Brand"
  data-accent-color="#b08a52">
</script>

Recommandations pour le logo

PNG transparent ou SVG · logotype horizontal · URL HTTPS publique · n'importe quel format (affiché à hauteur fixe, largeur automatique) · doit rester lisible en thème clair comme sombre.

Option 2 — JavaScript

<script>
  FitAPI.init({
    brandLogo: "https://your-site.com/logo.svg",
    brandAccent: "#b08a52",
    brandName: "Your Brand"
  });
</script>

Les changements apparaissent dès le rechargement, rien à configurer dans le tableau de bord.

Méthodes avancées pour les intégrations sur mesure.

Accès direct à l'API pour les intégrations sur mesure. Tous les points d'accès renvoient du JSON.

Base URL: https://api.fitld.com/v1. Everything under /v1 keeps its request and response shape; a breaking change would come as a new version, and /v1 would keep working. Older integrations that call /api/… keep working too. Every field, error code and webhook payload is in the API reference.

Test mode

Every account also has a test widget ID (wgt_test_…) and a test secret key (fit_sk_test_…), under Settings → Test mode. Use them on a staging store or during development: sizes come from your real charts, but nothing counts toward your plan or appears in Results. Test responses include "livemode": false and the header FITLD-Mode: test.

Test credentials work only with the endpoints on this page, never with account data, and allow 1,000 requests a day. Switch to your live widget ID and API key before your store goes live.

POST /v1/widget/recommend

Point d'accès public utilisé par le widget. Accepte des mesures d'invité ou des jetons de client connecté.

{
  "widgetId": "wgt_YOUR_WIDGET_ID",
  "productId": "SKU001",
  "measurements": {
    "unit": "cm",
    "chest": 96,
    "waist": 80,
    "hips": 98
  }
}

{
  "recommended_size": "M",
  "confidence": 0.87,
  "fit_quality": "great",
  "measurement_gap_cm": 1.2,
  "category": "Tops",
  "guest": true
}

POST /v1/recommend-size/guest

Calcul de taille de serveur à serveur avec votre clé API secrète. Les requêtes envoyées par un navigateur depuis un autre site sont refusées : utilisez l'identifiant de widget dans le code de la boutique.

POST https://api.fitld.com/v1/recommend-size/guest
Headers: x-api-key: fit_sk_YOUR_API_KEY

{
  "productId": "SKU001",
  "measurements": { "chest": 96, "waist": 80 }
}

POST /v1/products/resolve

Retrouve un produit par SKU, URL ou identifiant externe.

{
  "widgetId": "wgt_YOUR_WIDGET_ID",
  "productId": "SKU001"
}

{
  "productId": "SKU001",
  "productName": "Classic Oxford",
  "category": "Tops"
}

Errors and request IDs

Every response has an X-Request-Id header. Errors also return it in the body, with a message you can show and a code your code can check. Messages may be reworded; codes don’t change. Quote the request ID when you email contact@fitld.com and we can find that exact request. Every code is listed under Error codes.

{
  "error": "Authentication required. Provide x-api-key or widgetId.",
  "code": "authentication_required",
  "requestId": "req_8fK2xQm1Lw0aZt7c"
}

FITLD relie la taille confirmée par un client à la commande qu'il passe, pour que vous voyiez quelles commandes vos recommandations ont influencées.

Quand un client confirme une taille, le widget marque son panier avec la session. Il écrit les valeurs à la fois comme note_attributes du panier Shopify et comme propriétés cachées de ligne :

Les propriétés de ligne comptent car « Acheter maintenant » et le paiement accéléré abandonnent les attributs du panier ; les propriétés restent sur la ligne et y survivent.

Comment les commandes sont associées

Sur Shopify, le webhook orders/paid envoie chaque commande payée à FITLD. FITLD enregistre chaque ligne, la relie à la session FITLD du client quand il y en a une, et note si la taille achetée correspond à la recommandation. Les totaux apparaissent dans la page Résultats du tableau de bord. Mise en place : Installer sur Shopify.

Seules les lignes achetées pendant une session où le client a utilisé FITLD comptent comme commandes après FITLD. Les ventes de produits qui ont simplement un guide des tailles FITLD sont affichées à part, pour contexte.

Remboursements

Avec le webhook refunds/create connecté (même URL), FITLD enregistre les unités remboursées par ligne et compare les taux de remboursement : clients ayant utilisé FITLD ou non, et clients ayant acheté la taille recommandée ou une autre. Les taux apparaissent dès qu'un groupe compte au moins 30 unités.

Désactivez le marquage du panier pour une boutique avec data-fitld-cart-attrs="false".

FITLD can call your server when something happens. Add an endpoint under Settings → Webhooks, choose the events, and FITLD sends each one as a signed POST with a JSON body. Answer with any 2xx status within 10 seconds.

Events never contain shopper measurements or who the shopper is. Order, refund and return events need the Shopify connection; the others work on any store.

{
  "id": "evt_Q2xmN0VtZ3pDbFh0",
  "type": "order.attributed",
  "created": "2026-11-10T14:02:11.402Z",
  "livemode": true,
  "api_version": "v1",
  "data": {
    "order_id": "5890112340",
    "order_name": "#1042",
    "currency": "EUR",
    "paid_at": "2026-11-10T14:01:58.000Z",
    "lines": [{
      "product_id": "OXFORD-SHIRT",
      "sku": "OXF-BLU-M",
      "product_name": "Classic Oxford",
      "size": "M",
      "recommended_size": "M",
      "size_matched": true,
      "quantity": 1
    }]
  }
}

Check the signature

Every call has a FITLD-Signature header: t=<unix seconds>,v1=<signature>. The signature is the hex HMAC-SHA256 of t, a dot, and the raw body, made with your endpoint’s signing secret (whsec_…, shown once when you add the endpoint). Refuse calls that don’t match or are older than 5 minutes.

const crypto = require("crypto");

// Use the raw request body, exactly as received (before JSON parsing).
function verifyFitld(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false; // older than 5 minutes
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

app.post("/fitld/webhooks", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyFitld(req.body.toString("utf8"), req.get("FITLD-Signature") || "", process.env.FITLD_WEBHOOK_SECRET)) {
    return res.status(400).end();
  }
  const event = JSON.parse(req.body);
  // Answer quickly, then do the work: FITLD waits 10 seconds at most.
  res.status(200).end();
  handle(event); // e.g. event.type === "order.attributed"
});

Retries

If your server doesn’t answer with a 2xx, FITLD tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours. Every attempt carries the same event id (also in the FITLD-Event-Id header), so you can ignore one you’ve already handled. An endpoint failing for 3 days is turned off; turn it back on in Settings. Recent calls, their answers and a Resend button are on the endpoint’s page.

Chaque formule inclut un nombre mensuel de recommandations de taille. Une recommandation est comptée chaque fois qu'un client obtient une taille avec le widget ou que votre serveur appelle l'API.

Dépasser ne casse pas votre boutique. Le widget continue de servir vos clients jusqu'à deux fois votre volume mensuel, et nous vous écrivons à 80 % et 100 %. Ce n'est qu'au-delà du double que l'API renvoie une erreur HTTP 429 avec "code": "quota_exceeded".

Pour protéger le service, chaque session client peut demander jusqu'à 120 recommandations par heure, avec un plafond plus élevé par réseau pour ne pas bloquer les clients qui partagent une connexion mobile. Les appels API avec clé secrète sont limités à 100 par minute.

Each error has an HTTP status and a code. Check the code in your integration: it stays the same even when the message is reworded.

Problèmes fréquents et solutions.

1. 1Le widget n'apparaît pas : utilisez Installation → Vérifier qu'il est en ligne ; il contrôle le script, votre identifiant de widget et le guide des tailles sur votre page en ligne. Vous pouvez aussi ouvrir la console du navigateur (F12) et vérifier que l'URL du script se charge sans erreur.
2. 2« Ce produit n'est pas encore relié à un guide des tailles FITLD » : FITLD n'a pas pu relier la page à un produit. Avec l'app Shopify, ouvrez Size charts et vérifiez que le produit en a un. Un produit n'est relié que si ses tailles figurent dans le guide : s'il apparaît comme ignoré, choisissez un guide qui contient ses tailles. Avec le script, l'identifiant du produit dans FITLD doit être son handle (la fin de son adresse), son SKU ou l'adresse de sa page.
3. 3« Aucune taille de ce produit ne convient » : les mesures du client sont en dehors de toutes les tailles du guide. FITLD le dit au lieu de recommander la taille la plus proche. Si cela arrive souvent, ajoutez les tailles manquantes au guide.
4. 4Mauvaise taille recommandée : vérifiez que vos guides des tailles sont complets dans Produits. Les mesures manquantes réduisent la précision.
5. 5Your site sets a Content-Security-Policy: allow FITLD's two addresses: script-src https://fitld.com, connect-src https://api.fitld.com https://fitld.com and font-src https://fitld.com. The widget loads its size window from fitld.com and asks api.fitld.com for sizes; it calls nothing else.
6. 6Boutique protégée par mot de passe : les clients arrivent sur la page de mot de passe au lieu de votre produit, le widget ne peut donc pas se charger pour eux. Retirez le mot de passe pour mettre la boutique en ligne ; la vérification peut toujours lire la page si vous fournissez le mot de passe.
7. 7Page anti-robots : si la vérification signale un contrôle anti-robots, la boutique est accessible aux vrais visiteurs mais bloque les contrôles automatisés. Vérifiez le widget visuellement dans un navigateur.
8. 8« Secret API keys can't be used from a website » : vous avez utilisé data-api-key ou envoyé x-api-key depuis une boutique. Utilisez data-widget-id à la place, et régénérez la clé dans les paramètres si elle a été publiée.
9. 9Contacter le support : toujours bloqué ? Écrivez à contact@fitld.com.