Created by potrace 1.16, written by Peter Selinger 2001-2019

Miva Developer Docs

Google and Microsoft want information that Miva products don’t have built in: a brand, a GTIN (barcode number), and for clothing a gender and age group. You keep these in product custom fields, and the feed files read them by code.

The Google and Microsoft files already map these custom fields:

Feed attribute Custom field code Field type Needed for
brand brand Text field Most new products
gtin gtin Text field Products with a manufacturer barcode
mpn sku by default, or mpn Text field Products without a GTIN
identifier_exists identifier_exists Drop-down: yes, no Products with no GTIN and no MPN
gender gender Drop-down: male, female, unisex Clothing and accessories
age_group age_group Drop-down: newborn, infant, toddler, kids, adult Clothing and accessories
google_product_category google_product_category Text field Optional; helps Google classify the product

Each one is left out of a product’s row when the product has no value, so an empty field never sends a blank attribute. Create only the fields you need.

Which identifiers Google needs#

Google checks product identifiers in this order:

  1. A product with a manufacturer barcode needs its GTIN: the UPC (12 digits, North America), EAN (13 digits), JAN, ISBN or ITF-14 printed under the barcode. Enter digits only.
  2. A product without a GTIN needs a brand and an MPN (manufacturer part number).
  3. A product with neither, such as a custom, handmade or vintage item, needs identifier_exists set to no.

Products with variants usually have a different GTIN for each size and color. Enter each variant’s GTIN on its variant part product.

For clothing, Google also requires color, size, gender and age_group. Color and size come from the variant attributes; see Variants.

Google’s product data specification lists every attribute and which products need it.

Create the fields#

Import the template#

google-merchant-custom-fields.xml creates all seven fields on a Google Shopping tab of the product edit screen, with the drop-down choices filled in.

  1. Open the file and change YOUR_STORE_CODE to your store code.
  2. Remove any field your store already has. A store that already has a brand field should remove that ProductField_Add block. Importing a field code that exists fails for that field only.
  3. Go to Data Management > Import > XML Provisioning and import it.

Or create them by hand#

  1. Click the Settings gear, go to Utilities > Custom Fields, and click New Custom Field.
  2. Choose Product Custom Field.
  3. Enter the code from the table above, for example gtin, and a name, for example GTIN. The code must match exactly.
  4. Choose the field type. For a drop-down, add the choices in Google’s spelling: male, female, unisex.
  5. Optionally choose a group. A group appears as its own tab on the product edit screen.
  6. Click Add.

Miva’s Custom Fields documentation covers the other options, such as Facet and Public.

Use fields you already have#

If your store already keeps this information under other codes, for example upc or manufacturer, change source= in the feed file instead of creating new fields:

<Field source="upc" output="g:gtin">
    <Condition field="upc" operator="is_empty" output="" />
</Field>
<Field source="manufacturer" output="g:brand" />

In a feed you’ve already imported, change the source on the feed’s Feed Fields tab. For a Data Builder feed, change it on the Data Builder field’s Mapping tab and run its All Products task.

To send the mpn custom field instead of the SKU, change source="sku" to source="mpn" on the mpn line.

Fill in the values#

Any of these work:

  • On the product edit screen, on the Google Shopping tab (or the Custom Fields tab if you didn’t use a group).
  • With a product import from a CSV file, mapping a column to each custom field.
  • With provisioning XML. The template ends with commented-out examples:
<Module code="customfields" feature="fields_prod">
    <ProductFieldValue_Delete product="TEE-RED-S" field="gtin" />
    <ProductField_Value product="TEE-RED-S" field="gtin">012345678905</ProductField_Value>
    <ProductFieldValue_Delete product="TEE" field="brand" />
    <ProductField_Value product="TEE" field="brand">Your Brand</ProductField_Value>
</Module>

Deleting the value before setting it makes a re-import replace the old value.

Variants#

Field Set it on
gtin Each variant part product (each size and color has its own barcode)
brand, gender, age_group, google_product_category, identifier_exists The master product

In a Feed Builder feed, a variant row uses its part product’s value when it has one, and the master product’s otherwise. If the master product has a GTIN and its parts don’t, every variant row gets the master’s GTIN, and Google rejects the duplicates. Put GTINs on the parts, not the master. In a Data Builder field, the ready-made files read brand, gender, age_group, google_product_category and identifier_exists from the master product (Value from: Master product) and gtin from the variant itself.

Other custom fields#

Any product custom field can be added to a feed the same way. Add a <Field> with the custom field’s code as the source, or pick it from the source list on the Feed Fields tab. Common ones for Google:

Attribute Use
custom_label_0 to custom_label_4 Your own groupings for Google Ads campaigns, such as season or margin
product_highlight Short selling points
multipack, is_bundle Multipacks and bundles
adult Adult products

A field that should only appear when filled in needs the same “is empty” condition as the GTIN example above.

Microsoft, Meta and Pinterest#

  • The Microsoft files use the same fields as the Google files.
  • The Meta and Pinterest files map brand. To add a GTIN, add a line like this to the field list (Meta and Pinterest call it gtin):

    <Field source="gtin" output="gtin">
        <Condition field="gtin" operator="is_empty" output="" />
    </Field>
    

    For a Data Builder file, also add gtin to the column line in the feed’s <HeaderText>, in the same position.