Author: vheyn@technocore.co.za
Updated: 2026-04-16
¶ ObjServiceFHShopify
Shopify GraphQL Admin API integration for FullHouse retail. Manages product
catalogue, promotions, pricing, collections, and variant management on the
FullHouse Shopify store.
¶ API Version
- Shopify GraphQL Admin API 2026-01
- Authentication: Access Token via
X-Shopify-Access-Tokenheader - Single endpoint:
/admin/api/2026-01/graphql.json - Cost-based rate limiting (2000 points, 100/sec restore)
¶ CLI Commands
python ObjServiceFHShopify.py <command> [options]
| Command | Description |
|---|---|
batch-push [set] |
Push products: promo, active, old, comma-separated SKUs, or GROUP-xxxxx |
sync-audit |
Audit Shopify vs trader data (title, price, status, tags, SKUs) |
sync-audit --fix |
Auto-fix mismatched products |
singleton --sku SKU |
Push specific SKUs (comma-separated) |
promo-email |
Send branded promotion status email with AI review |
calibrate |
Measure push speed (N products, timing stats) |
promotions |
Show past, current, and future promotions |
list-products |
Retrieve and display all Shopify products |
recon |
Reconcile trader promotions vs Shopify prices |
product --sku SKU |
Look up a product on Shopify |
status-email |
Generate and send status email |
delete --sku SKU |
Delete products by SKU |
sync |
Sync all products (active, promo, deleted sets) |
update |
Update a specific product set |
locations |
Update inventory locations |
cache-config |
Configure inventory cache settings |
¶ Product Push Pipeline
¶ Flow: batch-push promo
- Promo tag cleanup --
clean_previous_promo_tags()removesspecial
and old promo name tags from products in the previous promotion that are
not in the current promotion. - Stale SKU inclusion -- previous promo SKUs not in current promo are
added to the push list so they get updated with current pricing (no promo). - Bulk data load --
_build_product_data_bulk()fetches trader data
for all SKUs in one query. - Cache validation --
is_product_cache_valid()checks price, promotion,
title, and time-based staleness. Products already archived on both sides
are skipped. - Per-product push --
create_product()for each SKU:- Resets
_colour_to_sku_mapper product (prevents group state leaks) - Fetches promotion and warranty data
- Builds title (brand + short title, truncated at first dash)
- Detects option level (0=single, 1=bedding/size, 2=warranty, 3=colour)
- Builds options and variants with per-variant pricing
- Checks for existing product (update vs create)
- Updates existing variant SKUs and prices via
_update_existing_variants() - Uploads images via
productCreateMedia, links to variants - Publishes to sales channels
- Resets
- Timing -- every push reports per-product elapsed time, rolling ETA,
and batch summary (total, avg, fastest, slowest, throughput/min). - Logging --
log_event("shopify", "product_push", ...)for each
successful push with timing.
¶ Option Levels
| Level | Type | Options | Example |
|---|---|---|---|
| 0 | Single variant | None | Simple product |
| 1 | Bedding/Size | Size + Length | Bed sets, rugs, vinyl |
| 2 | Warranty | Warranty (No extension / 2 years @ Rxxx) | Appliances |
| 3 | Colour | Colour | Furniture (GROUP push) |
¶ Variant Updates on Existing Products
When a product exists and variant count matches, _update_existing_variants()
runs via productVariantsBulkUpdate to fix SKUs, prices, and compare-at
prices. Matches variants by option values first, falls back to positional
matching when option text has changed (e.g. warranty price update).
¶ Per-Variant Metafield Data
Each variant in a GROUP-* push carries the underlying trader SKU on a
private _alt_sku field. _variant_data_for(real_sku, base_*) looks up
the variant's own promo, warranty, stock, lead time and price (cached per
push) and overlays them onto the base product data. The metafield builders
(_build_variant_metafields) are then invoked with the real SKU so credit
amortisation, deposit, instalment, stock and warranty all reflect that
variant rather than the parent.
Without this, every variant would inherit the parent's snapshot — a King
size bed would show the Double's R7999 / R644 instalment instead of its
own R11499 / R890.
¶ Image Pipeline
variant_imagesdict built per product:- Multi-variant: scan
local.documents/pims/<alt_sku>_*pims.jpgfor
each group member (primary + gallery shots, e.g.23494_1_pims.jpg). - Single-variant: same scan against the base SKU.
- Multi-variant: scan
- Pre-upload dedup — fetch existing media on the product (when
is_update), compute_canonical_image_name(url)to strip Shopify's
CDN-rewritten hash suffix, skip uploads whose canonical name already
exists. - Upload —
productCreateMediawithoriginalSourcepointing at
the public PIMS URL (fhgo.co.za/image/pims) andaltset to either
the colour name (option_level=3) or pipe-joined option values
(option_level=1, e.g."Double|Standard Length"). - Post-upload dedup —
_dedupe_product_media(gid)groups uploaded
media by canonical filename, keeps the oldest (preserves variant→image
bindings), deletes the rest. Catches duplicates from earlier sessions
that slipped past the pre-upload dedup. - Variant linking —
_link_images_to_variants(gid)runs on every
push (not gated on new uploads, so re-pushes still reconcile stale
bindings). Matches by joined option values first, then by the first
option (colour-only products), then falls back to the master image
so no variant ever goes blank when its PIMS file is missing.
¶ Promotion System
¶ Date Handling
Trader promotion_header.PH_STARTDATE / PH_ENDDATE are char(50) storing
dates as DD.MM.YYYY. All queries use STR_TO_DATE(col, '%d.%m.%Y') for
date comparison.
¶ Promotion Queries (YAML)
| Query | Purpose |
|---|---|
get_promotion_data_single |
Single SKU promo lookup with date filter |
get_promotion_data_bulk |
Bulk SKU promo lookup with date filter |
get_product_set_promo |
Current promo SKUs (up to 7 days past end) |
get_previous_promotion |
Last expired promotion headers |
get_previous_promotion_skus |
SKUs from last expired promotion |
¶ Promo Tags
- Products on promotion get
specialtag + promotion name tag clean_previous_promo_tags()removes these from expired promo products- Products in both previous and current promo retain tags
¶ Promo Email (promo-email)
Branded HTML email with FullHouse styling via ObjTemplate.build_email_html().
Sections:
- Active Promotions -- summary table with product counts
- Current promo products -- grouped by promotion name, with Shopify
tag status tick/cross, PIMS images (50px), SKU, description, price,
promo price, markdown % - AI Review -- local Ollama LLM summary per section (default model
fromAiConstants.DEFAULT_OLLAMA_MODEL) - Previous Promotion -- verify tags removed, with "New Promotion"
column showing if SKU moved to current promo. Three states:- Blue star: also in current promo (OK)
- Red cross: still tagged on Shopify (needs cleanup)
- Green tick: tag removed (clean)
- Grey dash: not on Shopify
- Shopify products -- grouped by promotion tag, with source images
(50px), price, compare-at, status. Extended warranty variants excluded.
Recipients from config.yaml shopify.notify_emails or --to flag.
¶ Sync Audit (sync-audit)
Compares all Shopify products against trader data. Checks:
| Check | Description |
|---|---|
| TITLE | Shopify title longer than expected (description leak) |
| PRICE | Price mismatch vs trader/promo price |
| STATUS | Should be ACTIVE but ARCHIVED, or vice versa |
| MISSING_TAG | On promotion but no special tag |
| STALE_TAG | Has special tag but not on promotion |
| NULL_SKU | Variant with null SKU |
| NO_IMAGE | No media attached |
| NOT_IN_TRADER | SKU not found in trader database |
--fix clears inventory/variant cache for affected SKUs and re-pushes.
¶ Configuration (config.yaml)
fullhouse:
shopify:
image_base_url: https://fhgo.co.za/image/pims
vat_rate: 15
notify_emails: vheyn@technocore.co.za,owen@technocore.co.za
¶ Key GraphQL Mutations
| Mutation | Usage |
|---|---|
productCreate |
New product with options |
productUpdate |
Update title, description, tags, status |
productVariantsBulkCreate |
Create variants (strategy: REMOVE_STANDALONE_VARIANT) |
productVariantsBulkUpdate |
Update variant SKU, price, mediaId, metafields |
productCreateMedia |
Upload images |
productDeleteMedia |
Remove duplicate media (_dedupe_product_media) |
metafieldDefinitionCreate |
Register my_fields definitions with PUBLIC_READ |
productDelete |
Delete product |
tagsRemove |
Remove specific tags (promo cleanup) |
¶ Metafield System
Product- and variant-level metafields are pushed under the my_fields
namespace with PUBLIC_READ storefront access (matches the legacy
classic site so existing storefront templates keep working without rewrites).
¶ Product-level (meta_* keys, 18 total)
Credit (price, instalment, deposit, months), promotion (name, price,
discount, on_promotion flag), guarantee/warranty (period, extended
warranty + cost), stock (level, lead_time, can_order, can_order_message),
TV-licence flag.
¶ Variant-level (m_* keys + variant_level_description)
Product metafields rewritten with the m_ prefix so storefront templates
that drill into specific variants (e.g. extended-warranty selector) keep
working. variant_level_description is a multi_line_text_field carrying
the per-variant body HTML — header lists the variant's option values
("Double · Standard Length"), then the shared product copy follows.
¶ Credit Amortisation
_compute_credit_data(sku) defers to
ObjTextFHInstalment.ObjProcessText.Compute() — the same module the legacy
fullhouse_product_api report uses — so credit values match what's printed
on customer-facing artifacts. Replaces the snapshot
meta_product.Web_Instalment / Deposit columns which can drift after rate
or fee changes. Returns {credit_installment, credit_deposit, credit_months, credit_price}.
¶ Database Tables
| Table | Purpose |
|---|---|
data_shopify_inventory |
Product cache (title, status, price, promo, sync time) |
data_shopify_variants |
Variant cache (SKU, product ID, GraphQL ID) |
data_shopify_variants_all |
Full variant data from GraphQL response |
data_shopify_images |
Image hash cache for dedup |
data_shopify_colourmap |
68 colour code to display name mappings |
data_shopify_meta |
Product metafield snapshot |
data_shopify_confirmed |
Manually-verified product list (ProductCode, ConfirmedBy, ConfirmedAt, Notes) |
¶ Group Push (Colour & Size Variants)
Push a variant group: singleton --sku GROUP-21924 or
batch-push GROUP-21924. The singleton CLI auto-detects the
GROUP- prefix, calls get_group_skus, and passes the group set to
push_products_batch which collapses N alternates into 1 product with N
variants (rather than N separate products).
- Resolves group GUID to member SKUs via
get_group_with_descriptions - Collapses to primary SKU, builds colour/size options from group
descriptions - Format:
"Product - Colour"(1 option) or"Product - Size - Length"
(2 options) - Per-variant pricing from bulk data via
_variant_pricesmap - Each variant carries
_alt_skuso per-variant metafields fetch its
own credit, stock and warranty - Images uploaded with alt text =
"Size|Length"or colour name; linked
by matching joined option values, with fallback to master image when
a variant has no PIMS file
¶ Collection Mapping
Raw trader categories mapped to Shopify collection names via
collection_name_map in YAML:
BEDROOM SUITE → Bedroom
BASE SETS → Bedroom
WHITES → Appliances
KITCHEN APPLIANCES → Appliances
Smart collections created from tags (category, subcategory, promotion name).
Custom collection membership via collectionsToJoin on ProductInput.
¶ Product Status
| Trader State | Shopify Status |
|---|---|
allowdisplay=0 |
ARCHIVED |
meta_can_order_message=Archived |
ARCHIVED |
| All other | ACTIVE |
Archived products are skipped during promo push if not already on Shopify,
or if already ARCHIVED on Shopify (no redundant update).
¶ Timing and Calibration
Every push_products_batch call reports:
- Per-product elapsed time with rolling ETA
- Batch summary: total seconds, average, fastest, slowest, throughput/min
log_eventper successful push and batch completion
calibrate command runs a timed push of N products for benchmarking.
¶ Stock Workflow
Product display rules:
- Archived:
PM_IS_WEB=0or status in (3,7,8,9,11) -- hidden - Ranged + stock: "In Stock"
- Listed + stock: "In Stock"
- Listed + no stock: "Supplier Order"
- Discontinued/clearance + stock: "In Stock"
- Discontinued/clearance + no stock: "Archived"
¶ Useful SQL
Find stale local records:
SELECT * FROM `core.axion`.data_shopify_variants
WHERE NOT Sku LIKE '%\_%' AND NOT Sku = ''
AND DATEDIFF(NOW(), LastUpdate) > 0
AND NOT Sku IN ('CURRENT', 'COMPLETE')
ORDER BY LastUpdate
PIMS images: https://fhgo.co.za/image/pims/{sku}_pims.jpg