Custom Labels — Overview & Slot Configuration
Custom labels let you attach extra product data to your catalogue feed so you can create targeted ad sets and apply dynamic overlays inside Facebook and Instagram Ads Manager.
Available since v2.3.0
Overview
The Facebook product feed format supports five custom label fields per product — custom_label_0 through custom_label_4. These are free-text columns that Facebook does not interpret on its own; their value comes entirely from what you put in them. You define that value here, by assigning a data source to each slot.
Once your feed is generated with custom labels populated, you can use them in Facebook Ads Manager to:
- Filter product sets — show only new arrivals, only discounted products, or only a specific category in a given ad campaign.
- Apply ad overlays — some Facebook creative formats can display the custom label text directly on the product image (e.g. "On Sale", "Best Seller").
- Segment reporting — analyse performance by product group without changing your catalogue structure.
You have five independent slots. Each slot can carry a different type of data, and any slot you leave set to None is simply omitted from the feed for that product.
Slot Configuration
Go to Modules > Module Manager > Facebook & Instagram Product Catalogue Feed Pro > Configure, then click the Custom Labels tab.
You will see five selectors — Custom Label 0 through Custom Label 4. Each selector assigns one data type to that slot for every product in the feed. The order of the slots is arbitrary; choose any slot for any type.
Available Slot Types
| Slot type | What appears in the feed | Conditional? |
|---|---|---|
| None | Slot is omitted entirely | — |
| Product's main category | The name of the product's default category | No — every product gets a value |
| Product's reference | The product's reference code from your Back Office | No — every product gets a value |
| Product's Tag List | Comma-separated list of product tags (truncated at 100 characters) | No — products without tags get an empty value |
| "New Products" text | A custom text string you define, emitted only for recent products | Yes — only products added within the configured number of days |
| Product's "On Sale" text | A custom text string you define, emitted only for products with active price reductions | Yes — only products currently on sale |
| "Best Selling" Products text | A custom text string you define, emitted only for top-selling products | Yes — only products in the bestseller list |
| "Trending" Products text | A custom text string you define, emitted only for trending products | Yes — only products in the trending list |
Conditional Types — Supporting Fields
When you select a conditional type, additional configuration fields appear below the slot selectors.
New Products text
| Field | Description |
|---|---|
| New Products label (translatable) | The text written into the feed for qualifying products, e.g. New Arrival. One value per language. |
| New Products days | How many days after the product's creation date it is considered "new". Defaults to 30 days if left blank. |
On Sale text
| Field | Description |
|---|---|
| On Sale label (translatable) | The text written into the feed for products with active discounts, e.g. Sale. One value per language. |
Best Selling text
| Field | Description |
|---|---|
| Bestselling label (translatable) | The text written into the feed for qualifying products, e.g. Best Seller. |
| Number of bestseller products | How many top-selling products to tag. |
| Time range for bestseller products | The sales period to evaluate. Leave blank for all-time sales history. Accepts a number of days. |
Trending Products text
| Field | Description |
|---|---|
| Trending label (translatable) | The text written into the feed for qualifying products, e.g. Trending. |
| Number of trending products | How many products to tag. |
| Time range (window) | The recent window to measure sales velocity. |
| Comparison period | The earlier period to compare against, to determine acceleration. |
For conditional types (new, on-sale, bestseller, trending), products that do not meet the condition simply have no value written to that slot. The
custom_label_Nelement is omitted for those products rather than written as empty.
How Custom Label Values Appear in the Feed
Each configured slot is written as a separate XML element per product row:
<custom_label_0><![CDATA[New Arrival]]></custom_label_0>
<custom_label_2><![CDATA[Footwear > Trainers]]></custom_label_2>
<custom_label_4><![CDATA[Sale]]></custom_label_4>
Only slots with a non-empty value are emitted. If a product does not qualify for a conditional type, that element is not written at all for that product. Slot numbers directly match the field names Facebook expects — slot 0 becomes custom_label_0, slot 1 becomes custom_label_1, and so on.
When your store has multiple languages enabled, translatable labels (New Products, On Sale, Bestseller, Trending) use the language of the feed being generated, so each language feed carries the correct translated text.
Use Cases
Segmenting ad campaigns by product status
Assign slot 0 to "On Sale" text with value Sale. In Facebook Ads Manager, create a product set filtered by custom_label_0 = Sale. Run a dedicated remarketing campaign targeting only discounted products.
Highlighting new arrivals with an overlay
Assign slot 1 to "New Products" text with value New In and set the window to 14 days. Facebook dynamic creative can display this text as a badge on your product images, driving click-through for fresh inventory.
Combining category and promotional status
Use slot 0 for the product's main category and slot 1 for on-sale status. You can then build nested product sets in Ads Manager — for example, "Women's Shoes that are on sale" — without any additional catalogue work.
Tracking supplier or internal references
Assign a slot to Product's reference or Supplier reference to carry internal SKUs into the feed. This is useful when reconciling Facebook conversion data against your warehouse management system.
Important Notes
- Slot numbers are positional. If you later change which type a slot carries, the feed must be regenerated before Facebook sees the new values.
- The
tagstype truncates at 100 characters to comply with Facebook's field length limits. - Translatable label texts (New Products, On Sale, Bestseller, Trending) must be configured per language. If you leave the text blank for a language, those products will have an empty value for that slot in that language's feed.
- Bestseller and trending detection query your order history at feed generation time. Large order tables may add a few seconds to the generation cycle.
- These settings are per-shop in a multi-shop setup. Each shop can assign different slot types and label texts.
Troubleshooting
| Problem | Solution |
|---|---|
custom_label_N does not appear for any product | Check that the slot is not set to None and that the feed has been regenerated after saving. |
| New arrivals label appears for all products, not just recent ones | Check the New Products days field — a very high number may match everything. Reduce it to your intended window. |
| On-sale label not appearing for a product you expect to be discounted | The module checks for active price rules at generation time. Verify the product has a current catalogue price rule or special price applied. |
| Bestseller label not appearing after setup | Confirm that your store has order history in the selected time range. A period with no sales will return an empty bestseller list. |
| Label text is correct in one language but empty in another | Open the Custom Labels tab, switch language using the flag selector beside the label field, and fill in the translation for the missing language. |
Frequently Asked Questions
Can I assign the same slot type to more than one slot?
Yes. For example, you can put the category name in both slot 0 and slot 1. There is no restriction, though it is rarely useful to duplicate the same data across slots.
Does changing a slot's type affect already-published ads?
The change takes effect when you regenerate and Facebook re-syncs your catalogue. Until then, Facebook continues to show the previously generated values. Re-sync manually from Commerce Manager or wait for the scheduled sync.
What happens to a product that qualifies for neither the bestseller nor the trending condition — does it get an empty label or no label?
No label element is written for that product at all. The slot is simply absent, which Facebook treats as having no value. Your product sets that filter on that label will exclude the product.
Can I use a custom label to segment by price range?
Not directly through the label slots. The available types are fixed. A workaround is to assign the category slot and organise products into categories that reflect price tiers — then filter by category name in your product set.
How many days back does "all time" mean for bestsellers?
When the bestseller time range field is left blank or set to 0, the query has no date filter and includes the entire order history available in your database.
Are custom labels included in both the main feed and language/country override feeds?
Yes. Custom labels are generated during the product processing step, which runs for every feed variant — default, language overrides, and country overrides.