Deeproots Help Documentation Help Center

How It All Fits Together

The plugin's main components, how the site talks to AIQ Ecommerce, how product data flows in, and how the cart and checkout work.

Updated October 1, 2026

How your site talks to AIQ Ecommerce

The path

WordPress plugin
    │  POST /api/v1/dispense/proxy
    │  X-Client-Key:     CLT_...
    │  X-Site-Domain:    yourdispensary.com
    │  X-Plugin-Version: 1.1.0
    │  { endpoint, method, query, body, venue_id }
    ▼
Licensing service
    │  Validation Successful
    ▼
AIQ Ecommerce API

The response comes back the same way, and the plugin unwraps the service’s envelope so call sites receive the AIQ Ecommerce payload itself.

How product data flows in

What triggers a sync

Trigger Hook
Scheduled dispense_products_cron_sync
Manual, from the settings screen dispense_products_background_sync (a single scheduled event)

Both call AIQ_Ecommerce_Products_API::sync_products().

The sequence

1.  Is a Client Key configured?          No → stop. Nothing is deleted.
2.  Read the selected venues
3.  Delete products for venues that were deselected
4.  For each venue:
      Fetch offers and banners
      Fetch products in pages of 100
        For each product:
          Disabled?              → delete any existing post
          New with no menu URL?  → skip
          Otherwise              → create or update
          Apply sale pricing from percentage discounts
          Assign category, cannabis type, terpenes, brand, venue
        Pause between batches and between pages
5.  Assign offer terms to products
6.  Prune orphaned offers — only if every venue's offers were fetched cleanly
7.  Delete stale products for the selected venues
8.  Record the stats

The rules that decide what exists

Condition Result
Product disabled in AIQ Ecommerce Existing post deleted; no new post created
New product with no productUrl Skipped
Existing product, no productUrl Still updated
Product missing from this sync's results Deleted by the stale cleanup
Product from a venue not currently selected Left alone entirely

Safeguards worth knowing about

These exist because the alternative is a wiped storefront, and they shape how you should reason about failures:

  1. A failed sync deletes nothing. The stale cleanup only runs after a successful pass.
  2. Offer pruning requires every venue to have succeeded. A transient error on one venue cannot strip valid offers from that venue’s products.
  3. The stale cleanup is time-boxed to about 200 seconds and processes in batches of 50, so it stops rather than timing out mid-way.
  4. The sync raises its own execution limit to 300 seconds where the host permits it.
  5. Venue resolution is checked first. If no venue post can be resolved for the selected venues, the cleanup is skipped entirely rather than deleting on a wrong assumption.

Where the data lands

Covered in full in Data Reference. In short: one dispense_product post per product per venue, with dispense_* post meta and six taxonomies.

How the cart and checkout work

The mode gate

Everything below is skipped when the plugin is in sync-only mode:

public static function is_cart_enabled() {
    $mode = get_option('dispense_mode', 'full');
    return (bool) apply_filters('dispense_cart_enabled', $mode !== 'sync_only');
}

When it returns false, AIQ_Ecommerce_Cart_API registers the four cart shortcodes as no-ops — so a leftover shortcode degrades to nothing rather than printing [dispense_add_to_cart] at a visitor — and returns before wiring anything else. No session, no scripts, no AJAX endpoints, no checkout render.

Session handling

The cart is identified by a cart ID and a venue ID held in $_SESSION, and mirrored into two cookies:

Cookie Contains
dispense_cart_id The AIQ Ecommerce cart ID
dispense_venue_id The venue the cart belongs to

The cookies exist because PHP’s session file is frequently garbage-collected well before the 30-day lifetime, particularly on shared hosting that ignores session.gc_maxlifetime. Mirroring the handle lets the session be restored on the next request.

Lifetime defaults to 30 days and is filterable:

add_filter('dispense_cart_session_lifetime', fn () => 7 * DAY_IN_SECONDS);

Cookie parameters mirror the PHP session cookie, so SameSite and Secure requirements stay consistent.

Checkout rendering

render_checkout_page_without_theme_chrome() runs on template_redirect at priority 0:

Is this the configured checkout page?     No  → return
Is the minimal shell enabled?             No  → return, theme renders it normally
Otherwise → emit a minimal document with wp_head/wp_footer,
            the checkout shortcode, no-cache headers, and exit

Returning early is what hands the request back to the theme, which then renders the page content — already the checkout shortcode — inside the normal layout.

add_filter('dispense_checkout_use_minimal_shell', '__return_false');

Purchase attribution

The checkout is an iframe, so the parent page cannot observe the order completing. The plugin works around it:

  1. On begin_checkout, the cart is written to sessionStorage.
  2. AIQ Ecommerce returns the customer with dispense_order_complete and transaction_id on the URL.
  3. The plugin reads the snapshot back and pushes purchase with the real transaction ID.
  4. The snapshot is cleared, so a refresh cannot fire a duplicate.

Both parameter names are filterable — see Hooks & Extending.

The return_to parameter is added to the checkout link so the customer comes back where they started; it is validated with wp_validate_redirect() against a home-URL fallback.

Rewrite rules and query handling

The plugin registers rules for both URL structures, and rewrites the main query on category archives.

Localized:
  ^{base}/([^/]+)/product/([^/]+)/?$
  ^{base}/([^/]+)/categories/([^/]+)/?$
  ^{base}/([^/]+)/categories/([^/]+)/page/([0-9]+)/?$

Universal (additionally):
  ^product/([^/]+)/?$
  ^categories/([^/]+)/?$
  ^categories/([^/]+)/page/([0-9]+)/?$

Offers index:
  ^{offer-slug}/?$   →  pagename={index-page}&dispense_offers_index=1

Two query vars carry the parsed values: dispense_venue and dispense_category. A pre_get_posts handler converts them into a taxonomy query, merging with any existing tax_query so FacetWP’s facet filters (set at priority 1) survive rather than being overwritten. redirect_canonical is filtered off for the offers index and for category queries, so /offers/ stays /offers/ instead of redirecting to the listing page’s own slug.

Extension points

Filter Controls
dispense_cart_enabled Whether the cart runtime loads
dispense_cart_session_lifetime Cart session and cookie lifetime
dispense_checkout_use_minimal_shell Whether checkout drops theme chrome
dispense_purchase_complete_query_param The completion parameter name
dispense_purchase_transaction_query_param The transaction ID parameter name

Full detail: Hooks & Extending.

Did this answer your question?