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:
- A failed sync deletes nothing. The stale cleanup only runs after a successful pass.
- Offer pruning requires every venue to have succeeded. A transient error on one venue cannot strip valid offers from that venue’s products.
- 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.
- The sync raises its own execution limit to 300 seconds where the host permits it.
- 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:
- On
begin_checkout, the cart is written tosessionStorage. - AIQ Ecommerce returns the customer with
dispense_order_completeandtransaction_idon the URL. - The plugin reads the snapshot back and pushes
purchasewith the real transaction ID. - 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.