Deeproots Help Documentation Help Center

Offers & Promotions

How offers reach your site, building an all-offers page, using offer banners, showing offer badges on products, and what happens when an offer ends.

Updated October 1, 2026

How offers reach your site

Offers are created in AIQ Ecommerce. The plugin imports them on every sync and does three things with each one:

  1. Creates an Offer term in the dispense_offer taxonomy, so the offer has a page of its own.
  2. Stores the offer’s details on that term — type, reward, minimum spend, description, images.
  3. Assigns the term to every product the offer applies to, and writes the offer names into each product’s dispense_product_offer field.

Find them at AIQ Ecommerce Products → Offers.

Dispense Products → Offers, listing imported offer terms with their product counts.
AIQ Ecommerce Products → Offers, listing imported offer terms with their product counts.

Each offer term stores:

Detail Meta key
Offer ID in AIQ Ecommerce dispense_offer_id
Offer type (e.g. SALE) dispense_offer_type
Deal type (e.g. FLAT) dispense_offer_deal_type
Reward type (e.g. PERCENT) dispense_offer_reward_type
Reward value dispense_offer_reward_value
Minimum spend dispense_offer_min_spend
Description dispense_offer_description
Offer image dispense_offer_image
Display order dispense_offer_order
Banner — desktop dispense_offer_banner_large
Banner — tablet dispense_offer_banner_medium
Banner — mobile dispense_offer_banner_small
Banner click-through URL dispense_offer_banner_link

Opening an offer term shows these in a readable panel rather than as raw meta.

An offer term edit screen showing the offer details panel: Offer Type, Deal Type, Reward, Minimum Spend, Description and the banner previews.
An offer term edit screen showing the offer details panel: Offer Type, Deal Type, Reward, Minimum Spend, Description and the banner previews.

Two pages per offer, and why

WordPress taxonomies give you a page per term but no built-in “list all terms” page. Offers need both, so the plugin provides them separately:

Page URL What it is
A single offer /offers/{offer-slug}/ The offer's own page, listing the products it applies to. Provided by WordPress automatically.
All offers /offers/ An index of every offer. Provided by a page you designate.

The offers part of both is the Offer Slug setting, so you can use deals, promotions, or whatever suits your site.

The all-offers page

Setting this up is a three-step job, and the order matters.

1. Create the page

Create a normal WordPress page — the default slug the plugin expects is offers-listing — and put this shortcode in it:

Shortcode
[dispense_offers]

2. Point the setting at it

Go to AIQ Ecommerce Products → API Settings → General → Offers Index Page and enter the page’s slug (offers-listing). Click Save Settings.

If the page does not exist yet, the setting warns you:

Go to Settings → Permalinks and click Save Changes without altering anything.

Now /offers/ shows your index page, while /offers/{offer-slug}/ still shows each individual offer. The address stays /offers/ — it does not redirect to the page’s own slug.

The Offer Slug and Offers Index Page fields on the General tab, with the Current URL Pattern line underneath.
The Offer Slug and Offers Index Page fields on the General tab, with the Current URL Pattern line underneath.
The front-end /offers/ page rendered by [dispense_offers], showing a grid of offer cards with banners.
The front-end /offers/ page rendered by [dispense_offers], showing a grid of offer cards with banners.

Leave Offers Index Page blank if you do not want an index at all.

Options for [dispense_offers]

Attribute Default What it does
columns 3 Number of grid columns
size large Banner size to prefer — falls back large → medium → small → offer image
hide_empty 0 0 shows every offer; 1 hides offers with no products
orderby name Field to order by
order ASC ASC or DESC
limit 0 Maximum offers to show (0 = all)
show_name 1 Show the offer name under the banner
show_type 1 Show the offer type badge

For example, a four-column grid of the six most recent offers, hiding empty ones:

Shortcode
[dispense_offers columns="4" limit="6" hide_empty="1"]

Each card links to the offer’s page, or to its Banner Link if one is set.

Why a shortcode rather than a page-builder loop

Use [dispense_offers] for the all-offers listing, not a page builder’s term loop. Page builders hand a term loop only their own built-in fields — usually just the term title — and never pass the loop’s term to custom dynamic fields. Build the index with a term loop and you get names with no banners.

The shortcode resolves every offer on the server, so each card gets its real banner and details.

This is a genuine limitation of the page builders, not of the plugin.

Single offer pages are different — dynamic fields work perfectly there, so design /offers/{slug}/ however you like with a taxonomy template.

Offer banners

Banners are images attached to offers in AIQ Ecommerce, in three sizes: desktop, tablet and mobile.

How a banner gets attached to an offer

Each banner in AIQ Ecommerce carries a link that says which offer it belongs to:

  • A specific offer ID — the banner belongs to that one offer.
  • The value ALL — the banner applies to every offer in the venue.

If an offer has both, its own specific banner wins over the venue-wide ALL banner.

Showing banners

Shortcode Output
[dispense_offer_banner] The banner as an <img> tag
[dispense_offer_banner size="medium"] The tablet-size banner
[dispense_offer_banner_url] Just the URL, for use as a background image

Both work out which offer you mean automatically — on the offer archive, in a term loop over dispense_offer, or from the first offer assigned to the product being shown. Pass term_id="123" to target a specific offer.

Every banner field falls back through the sizes and then to the offer’s own image, so you get something whenever any image exists. That means you can use a single tag and let it resolve, rather than writing responsive art-direction markup — reach for the per-device fields only when you genuinely want different crops on different screens.

A front-end single offer page showing a banner across the top and the offer's products listed underneath.
A front-end single offer page showing a banner across the top and the offer's products listed underneath.

Showing offer badges on products

There are two ways, depending on whether you want the offer’s name or its type.

The offer name, from the product's own field

Every product carries the names of its offers, comma-separated, in dispense_product_offer. Output that field in your product card and you get “20% Off Flower” on the badge.

Available in every page builder as Offer Details.

The offer type, as a short badge

Shortcode
[dispense_offer_type]

Outputs the type — SALE, for example — resolved from the current offer, or from the product’s first offer on a product page. Good for a short, consistent badge.

Showing the description

Shortcode
[dispense_offer_description]

Products on sale

A product with a percentage SALE discount also gets a sale price in dispense_product_sale_price and is added to a category called Sale. So a “was £X, now £Y” price display and a sale listing are both straightforward:

  • Show dispense_product_sale_price struck through against dispense_product_price.
  • Build a sale page as a category archive or query loop on the Sale category.

Offers that expire or are switched off

Offers are re-checked on every sync, and clean-up is automatic.

When an offer is disabled or deleted in AIQ Ecommerce:

  • It is removed from every product it was applied to.
  • Its name disappears from those products’ dispense_product_offer fields.
  • The offer term itself is removed once nothing references it.

Two safeguards apply:

  1. Offers are only pruned when every venue’s offers were fetched successfully. If one venue’s request fails, no pruning happens at all — a transient error can never strip valid offers off that venue’s products.
  2. Banner data is cleared rather than left stale. When a banner is unlinked from an offer, the stored banner URLs are emptied rather than kept pointing at an image that no longer applies.

Timing: an offer that ends in AIQ Ecommerce disappears from your site on the next sync — up to half an hour later on the default interval. If you run tightly timed promotions, either shorten the sync interval or run a manual sync when the promotion ends.

Front-end caching adds to that delay. A cached page can show an expired offer well after the sync removed it. See Caching & Site Speed.

Common problems

/offers/ shows a 404.

Three things to check in order: the page exists and is published; its slug matches Offers Index Page exactly; permalinks have been flushed at Settings → Permalinks → Save Changes.

My offers index shows names but no banners.

You built it with a page builder term loop. Use [dispense_offers] instead — see above for why.

An offer page has no products on it.

The offer term exists but no product is assigned to it. Check in AIQ Ecommerce that the offer actually applies to products, then run a manual sync.

An expired offer is still showing.

Run a manual sync. If it is still there afterwards, clear your page cache.

A banner shows on one offer but not another.

Only offers with a linked banner have one. Check the offer term’s details panel — if the banner fields are empty, no banner is linked in AIQ Ecommerce.

Offer badges are empty on my product cards.

Check the card is outputting dispense_product_offer, and that the product genuinely has an offer applied — open it in the admin and look at the Offer Details field.

Did this answer your question?