Ibexa Commerce 4.6 : Product Types, attributs et variantes expliqués

Dans Ibexa Commerce, un produit reste lié au modèle de contenu du CMS, mais il reçoit aussi des données et des comportements commerciaux. Cette architecture est puissante, car elle permet de combiner des champs éditoriaux avec un prix, un stock, une fiscalité et des variantes. Elle peut toutefois sembler abstraite au début.

Cet article explique chaque niveau du modèle à partir de notre démonstration Ibexa Commerce 4.6.32. Nous verrons pourquoi un simple Content Type n'est pas encore un Product Type, ce que contient réellement le champ Product Specification et comment Ibexa distingue les attributs, les variantes, le prix et le stock.

1. La hiérarchie complète

Notre démonstration suit cette structure :

Groupe de Content Types « product »
└── Product Type « demo_product »
    ├── Product Specification
    ├── Name
    ├── Description
    └── Image
        ├── Produit « IBEXA-COURSE-001 »
        ├── Produit « IBEXA-NOTEBOOK-001 »
        └── Produit « IBEXA-POSTER-001 »

Il faut bien distinguer le schéma de ses instances :

demo_product définit les champs et leurs règles ;
IBEXA-COURSE-001 est un produit concret utilisant ce schéma ;
le nom, la description et l'image sont des valeurs éditoriales ;
le code, le prix et le stock participent au fonctionnement commercial.

2. Content Type et Product Type : quelle différence ?

Un Content Type décrit la structure d'un contenu Ibexa. Un article peut, par exemple, posséder un titre, un corps de texte et une image.

Un Product Type s'appuie sur ce même mécanisme, mais il est reconnu par le composant Product Catalog et peut recevoir des données commerciales.

Dans notre installation, deux conditions permettent au service Commerce de retrouver le type :

le Content Type appartient au groupe configuré product ;
il possède une définition de champ utilisant le FieldType ibexa_product_specification.

Le groupe organise et délimite les types recherchés. La présence du FieldType Product Specification constitue la caractéristique technique essentielle du Product Type.

3. Où retrouve-t-on cette structure dans le back-office ?

Deux écrans présentent le même modèle sous des angles différents.

Dans Product Catalog → Product Types, Ibexa affiche les types utilisables par Commerce. C'est le chemin recommandé pour créer un nouveau Product Type : l'interface propose sa nature et ajoute la structure commerciale obligatoire.

Dans Content structure → Content types → Product, on retrouve le Content Type sous-jacent, son groupe et toutes ses Field Definitions.

Ce ne sont donc pas deux objets indépendants. Le Product Type est construit au-dessus du système de Content Types d'Ibexa.

4. Field Definition et FieldType

Une Field Definition est un champ configuré dans notre schéma. Elle possède un identifiant, une position, un nom, des règles de validation et des options de traduction.

Un FieldType est le composant technique qui définit la nature de sa valeur et son comportement.

Dans notre migration :

-   identifier: specification
    type: ibexa_product_specification
    required: true
    translatable: false

-   identifier: name
    type: ezstring
    required: true
    searchable: true
    translatable: true

Ici :

specification et name sont les identifiants des Field Definitions ;
ibexa_product_specification et ezstring sont leurs FieldTypes ;
le premier apporte le comportement produit ;
le second stocke une chaîne de caractères classique.

Le champ pourrait s'appeler product_data au lieu de specification. Ce qui compte pour Ibexa Commerce est son type technique ibexa_product_specification.

5. Le rôle exact de Product Specification

Le champ Product Specification permet d'associer une identité commerciale au contenu. Lors de la création d'un produit, nous lui transmettons notamment un code unique :

-   fieldDefIdentifier: specification
    languageCode: eng-GB
    value:
        code: IBEXA-COURSE-001

Ce code sert ensuite de référence aux autres services Commerce.

Product Specification ne contient pas à lui seul toutes les données du produit. Il ne faut pas considérer ce champ comme un grand bloc regroupant le contenu, le prix et le stock.

Donnée	Composant responsable
Code produit	Product Specification
Nom, description et image	Champs du Content Type
Prix	Product Price
Disponibilité et stock	Product Availability
Taux fiscal	Région et catégorie de TVA
Sélection dans une offre	Product Catalog

Cette séparation permet notamment de gérer plusieurs devises, de modifier un stock sans republier le contenu éditorial et de construire différents catalogues à partir des mêmes produits.

6. Prix et stock sont des objets séparés

Dans notre démonstration, le produit, son prix et sa disponibilité sont créés par trois opérations distinctes :

-   type: product_price
    mode: create
    product_code: IBEXA-COURSE-001
    currency_code: EUR
    amount: 99.00

-   type: product_availability
    mode: create
    product_code: IBEXA-COURSE-001
    is_available: true
    is_infinite: false
    stock: 25

Un produit peut donc exister comme contenu sans être achetable. Il faut au minimum vérifier sa disponibilité, son prix dans la devise attendue et son inclusion dans le catalogue utilisé par le storefront.

7. Produit physique ou produit virtuel

Ibexa Commerce 4.6 propose deux natures lors de la création d'un Product Type :

Physical pour un produit matériel susceptible d'être expédié ;
Virtual pour un produit immatériel qui ne nécessite pas de livraison physique.

Notre type demo_product est physique. Cela explique pourquoi notre commande contient une expédition, un mode de livraison et un cycle allant jusqu'au statut Shipped.

La nature du Product Type n'est pas un simple libellé d'affichage. Elle permet au système et au projet d'adapter le parcours commercial, notamment autour de la livraison.

8. TVA et régions

Le taux de TVA dépend d'une région et d'une catégorie fiscale. Notre Product Type associe la région default à la catégorie standard :

fieldSettings:
    regions:
        default:
            region_identifier: default
            vat_category_identifier: standard

La catégorie standard est configurée à 20 % dans notre projet. Cette association appartient à la définition du Product Type, tandis que le montant est défini par la configuration fiscale de la région.

Cette distinction devient importante lorsque la boutique dessert plusieurs marchés avec des règles fiscales différentes.

9. Que sont les attributs ?

Les champs éditoriaux et les attributs produit ne répondent pas au même besoin.

Un champ comme description sert à rédiger et présenter le contenu. Un attribut exprime une caractéristique commerciale structurée, par exemple :

couleur : noir, bleu ou rouge ;
taille : S, M ou L ;
capacité : 128 Go ou 256 Go ;
format : papier ou numérique.

Les attributs sont organisés en groupes dans Product Catalog → Attribute Groups. Les définitions sont gérées dans Product Catalog → Attributes, puis associées au Product Type dans l'étape Attributes de son formulaire.

Un attribut peut servir uniquement à décrire ou filtrer les produits. Il peut aussi participer à la génération des variantes selon sa configuration.

10. Produit simple et produit avec variantes

Nos trois produits de démonstration sont des produits simples : chaque produit possède directement son propre code.

IBEXA-NOTEBOOK-001

Pour un produit décliné, le Product Type définit des attributs de variante. Chaque combinaison autorisée produit alors une variante identifiable séparément.

T-shirt
├── noir / S  → code distinct
├── noir / M  → code distinct
├── bleu / S  → code distinct
└── bleu / M  → code distinct

Une variante peut ainsi avoir son propre prix, sa propre disponibilité et son propre stock. Le produit de base porte les informations communes, tandis que les valeurs d'attribut différencient les déclinaisons.

Il faut choisir les attributs de variante avec soin. Trois couleurs et quatre tailles produisent déjà douze combinaisons possibles. Ajouter trop d'axes peut générer un nombre difficile à administrer.

11. Le rôle du catalogue

Créer un produit ne signifie pas automatiquement l'exposer dans toutes les boutiques. Un Product Catalog sélectionne un ensemble de produits selon des règles.

Notre commande de démonstration crée demo_catalog avec un filtre sur le Product Type demo_product. Le storefront utilise ensuite explicitement ce catalogue.

Cette couche permet, par exemple, de construire :

un catalogue public ;
un catalogue réservé aux professionnels ;
une sélection propre à un pays ;
une offre saisonnière ;
un catalogue limité à certains Product Types.

Le catalogue ne remplace donc ni le Product Type ni le stock. Il décide quels produits appartiennent à une offre donnée.

12. La méthode recommandée pour créer un Product Type

Depuis le back-office :

ouvrir Product Catalog → Product Types ;
cliquer sur Create ;
choisir Physical ou Virtual ;
définir l'identifiant, le nom et le schéma de nom ;
ajouter les champs éditoriaux ;
configurer les attributs si nécessaire ;
associer les catégories de TVA ;
enregistrer et créer un premier produit de test.

Pour un projet versionné, une migration YAML apporte ensuite un résultat reproductible entre les environnements. Notre fichier src/Migrations/Demo/01_product_type.yaml constitue un exemple minimal réellement exécuté.

13. Checklist de diagnostic

Si un contenu n'apparaît pas comme produit, vérifier dans cet ordre :

le Content Type appartient-il au groupe de produits configuré ?
possède-t-il exactement un champ ibexa_product_specification valide ?
le produit possède-t-il un code unique ?
sa devise est-elle activée ?
un prix existe-t-il pour cette devise ?
le produit est-il disponible et possède-t-il du stock ?
appartient-il au catalogue utilisé par le SiteAccess ?
le catalogue est-il publié ?
l'index de recherche a-t-il été mis à jour ?

Cette liste évite de chercher un problème de template lorsqu'il manque simplement un prix, une disponibilité ou une règle de catalogue.

Conclusion

Ibexa Commerce ne transforme pas un contenu en produit en ajoutant simplement un prix à une page. Il compose plusieurs responsabilités :

le Content Type structure les informations éditoriales ;
Product Specification fournit l'identité produit ;
Product Price gère les montants ;
Product Availability gère la disponibilité et le stock ;
les attributs décrivent et différencient les variantes ;
la TVA applique les règles fiscales ;
le catalogue sélectionne l'offre visible.

Une fois cette séparation comprise, le modèle devient beaucoup plus lisible. La prochaine étape pratique consiste à créer un second Product Type avec deux attributs de variante, puis à observer comment Ibexa génère et administre chaque déclinaison.

Ibexa Commerce 4.6 : Product Types, attributs et variantes expliqués