analyze_after_sales_workload
ChatGPTUse for open workload, overdue promises and ready cases waiting across shops. Native summary and byStatus cover every authorized open case; only byShop is paginated. Done/cancelled excluded. Overdue excludes ready and compares promised company-local days; ready waiting requires proven transition and full 24-hour periods. Unknowns remain in coverage. as_of is current-read reference, not historical reconstruction. For individual cases use search_after_sales_cases with corresponding filters. Example: 'Current backlog' -> {}; 'Ready at least 15 days in SHOP-1' -> {shop_id:'SHOP-1',ready_min_days:15,page:1,limit:20}. No certain debt or supplier lead time follows.
analyze_customer_segments
ChatGPTNet spend is net turnover from signed sales movements at their business movement dates, including cancellations and returns and negative modifications, not amounts on initial baskets. historyNetSpend runs through asOf; periodNetSpend and previousNetSpend use their own inclusive movement-date windows. Frequency/recency remain native eligible initial-ticket metrics: zero purchases can coexist with negative turnover. Native business turnover of zero for a deposit/payment stays zero, not cash received. Honor company/shops, amount_mode, scope and exclude_retrocessions; null is unknown. Attribution uses a proven event customer ID or unambiguous initial ticket link within authorized shops, never names/contacts; unlinked movements are not attributed. Use first for counts, definitions and quality of decliningRegular and highValueInactive, not identities. Requires both sales:read and customers:read even though response is anonymous; sales-only accounts can use analyze_purchase_behavior for anonymous purchase aggregates instead. Current and immediately preceding windows have equal company-local civil-day lengths; to cannot exceed today's company-local day (enforced by API). Segments may overlap. historyComplete=null means older archives are unproven, not complete. Example: 'Who is buying less since July?' -> {from:'2026-07-01',to:'2026-09-24'}; 'Inactive high-value customers at 2000 EUR' -> {from:'2026-07-01',to:'2026-09-24',high_value_threshold:'2000.00',inactive_days:120}. Use list_customer_segment_members only on explicit request and with the same rules. Segment membership is not marketing consent or a CLV forecast.
analyze_customer_spend
ChatGPTUse to count customers meeting inclusive signed period-spend and minimum-purchase filters without returning names, customer IDs or contacts. Requires sales:read and customers:read. Signed net turnover uses business movement dates, including returns of earlier purchases, cancellations, SAV and modifications; it is not payments or lifetime value. Zero eligible purchases are allowed. Unknown complete amounts never qualify by known subtotal. Only customers with attributable period activity are candidates, even for a zero threshold. Archives are observed, not certified complete; read history.byShop and coverage warnings. Identity and optional contacts are current; no marketing action or inferred consent. Official summary is global, never a page subtotal. Example 1: 'How many customers spent at least 1000 in September?' -> {from:'2026-09-01',to:'2026-09-30',min_spend:'1000'}; Example 2: 'Count period activity with net between -500 and 0' -> {from:'2026-09-01',to:'2026-09-30',min_spend:'-500',max_spend:'0',min_purchases:0}. Use list_customers_by_spend for a bounded native rank; file/client delivery remains unvalidated.
analyze_payment_methods
ChatGPTUse for known payment-method collections/refunds and separate credit, gift-card and deposit uses by SETTLEMENT date, not sale business date. All signed amounts are incl. tax even if amount_mode=exclTax. These known flows are not turnover, an exhaustive cash reconciliation or treasury close; totals.complete remains false even without explicit exclusions. Example: 'September payment mix' -> {from:'2026-09-01',to:'2026-09-30'}; 'Payments in Paris' -> {from:'2026-09-01',to:'2026-09-30',shop_ids:['SHOP-1']}. For source entries use list_payment_entries only if separately available/authorized; preserve context and inspect coverage warnings.
analyze_product_performance
ChatGPTUse only after resolving one to 20 distinct product IDs for sales during an inclusive period against CURRENT available stock. One native product-sales aggregate and one current stock-summary aggregate are read at the same authorized company/shop scope; no catalogue or sale scan. Join only proven product IDs at product grain, never multiply one product turnover across size/item rows. The sales summary and coverage remain GLOBAL to the period even with product_ids; use each group for product figures. A missing/unresolved group stays null, not zero. Indicative available-units/gross-sales pace is withheld for unknown/unlimited stock or non-positive/unknown demand; it is not historical rotation, sell-through, GMROI or a reorder instruction. Example: 'Sales and stock for these rings' -> {product_ids:['PROD-1','PROD-2'],from:'2026-08-01',to:'2026-08-31'}; 'Only authorized Paris shops' -> {product_ids:['PROD-1','PROD-2'],from:'2026-08-01',to:'2026-08-31',shop_ids:['SHOP-1']}. Use get_stock_availability for exact item/size detail when authorized.
analyze_products_bought_together
ChatGPTUse for co-purchase evidence in reliable initial baskets, optionally anchored to a proven product ID. pairTickets counts co-occurring tickets; support divides by ALL eligible baskets, while confidenceAtoB and confidenceBtoA divide by baskets containing A or B respectively. From/to confidence sorts are oriented from/to product_id, not alphabetical productA/productB. Filtered rows do not change global basket denominators. Later returns do not erase an initial pair; observed cancellations exclude baskets. Low counts are weak evidence, not individual purchase probabilities. Example: 'Top product pairs' -> {from:'2026-09-01',to:'2026-09-30',sort_by:'occurrences'}; 'What is bought with PROD-1?' -> {from:'2026-09-01',to:'2026-09-30',product_id:'PROD-1',sort_by:'confidenceFrom'}. On HTTP 413 narrow the period/shops; do not invent a top list. Continue pages with unchanged filters.
analyze_purchase_behavior
ChatGPTUse for anonymous aggregate identified/guest purchase shares, observed repeat buying and frequency; no customer identity is returned. Served customers are identified people with eligible period purchases; record creation is NOT a first purchase. Recurrence is observed in authorized shops and available history only, not complete lifetime RFM/CLV; history.complete is null. Example: 'How many repeat customers in September?' -> {from:'2026-09-01',to:'2026-09-30'}; 'Paris purchase behavior' -> {from:'2026-09-01',to:'2026-09-30',shop_ids:['SHOP-1']}. Preserve period/scope/shop filters in follow-up; named segments require separately authorized customer tools, never reconstruct identities from this aggregate.
analyze_sales_breakdown
ChatGPTUse for a single native dimension: shops, sellers, company-local day, ISO week, month, historical status/action or current supplier/category/product type. Aggregation and sorting happen over all authorized facts before group pagination; summary and coverage remain whole-period. Use explicit sort_by for complete turnover, excluding-tax margin/cost or gross/net quantity; omitted sort ranks known turnover. Current classifications can be unclassified; historical sales amounts do not imply historical classifications. Group tickets/distincts may overlap and are not additive; seller contribution is not productivity. dimension='seller' also resolves native attributed seller IDs for article listings: find the named seller across group pages in the same company/shops/period, confirm homonyms, then use inspect_sales_activity with grain='line', seller_id=data[].id and line_type='product'. An unknown group with id=null is not a selectable seller. Do not scan sale documents to resolve or filter a seller. Example: 'Turnover by shop in September' -> {from:'2026-09-01',to:'2026-09-30',dimension:'shop'}; 'Top suppliers by margin' -> {from:'2026-09-01',to:'2026-09-30',dimension:'supplier',sort_by:'marginExclTax',sort_order:'desc',page:1,limit:20}. Continue pages with unchanged filters; use get_sales_summary for basket median without groups.
analyze_stock_age
ChatGPTUse for current articles by first-entry date or calendar age. Filters, ageDays and summary.age use initialInStockDate retained across transfers, never currentShopInStockDate. Age uses the API read-start Europe/Paris civil date, even when company timezone differs. Missing/future dates are counted separately and excluded from buckets/average; bands count articles and finite available units, not value. positive_available_only=true restricts the native population to known finite availability > 0 before summary and pages, independently of terminal state. Example: 'First entered last quarter' -> {entry_date_from:'2026-07-01',entry_date_to:'2026-09-30'}; 'Positive stock at least 365 days old' -> {min_age_days:365,positive_available_only:true,sort_by:'ageDays',sort_order:'desc',page:1,limit:20}. Follow pagination. No direct supplier/category/type or value-by-age-band filter; if authorized, resolve product IDs first. Current stock is not historical inventory.
analyze_stock_materials
ChatGPTUse this for a bounded current-stock material breakdown of one to ten resolved products, not a metal valuation or historical inventory. Resolve material definition/value IDs with list_characteristics and list_characteristic_values; material_filter optionally pushes an exact typed filter to stock/articles before item enrichment. At most three 100-row pages from start_page are read, then item IDs in 50-row batches. Material groups may overlap. Weight requires item-level material, numeric per-unit weight and unit in the same characteristic group plus explicit merchant-confirmed field semantics; the MCP cannot independently certify that convention. No theoretical product weight, metal-fineness conversion or price feed. Example: 'Group ring stock by configured metal' -> {product_ids:['PROD-1'],characteristic_code:'METAL'}; 'Inspect one proven material value from page two' -> {product_ids:['PROD-1'],characteristic_code:'METAL',material_filter:{characteristic_id:'CHAR-1',value_id:'VALUE-1'},start_page:2}. Only observations from returned pages are grouped; use nextStockPage with unchanged filters if present.
audit_catalog_availability
ChatGPTChoose this only for one to 20 already-resolved product IDs to review online publication, operational availability, physical anomalies and missing commercial data. It fetches light product references with visibility=all (including references without items), then at most three filtered pages of /stock/articles with state=all so terminal items with physical quantity are not hidden. It never uses availableOnly=false as an out-of-stock filter. A no-article or no-availability conclusion requires all filtered stock pages; when the cap, time budget or a source read prevents that, absent rows mean unknown. Offline with available stock may be an intentional publication choice, not an error. Null sale price is missing; zero sale price is known. No catalogue update is made. Example: 'Audit these two product IDs' -> {product_ids:['PROD-1','PROD-2']}; 'Audit only Paris stock, one page first' -> {product_ids:['PROD-1'],shop_ids:['SHOP-1'],max_stock_pages:1}. Use search_products to resolve IDs and get_stock_availability for a selected item or follow-up page; preserve exact filters.
compare_sales_periods
ChatGPTChoose this for two explicit inclusive business-date periods with identical authorized company, shops, tax mode, fact scope and retrocession policy. Two native activity reads are mandatory; dimension adds at most one 20-group breakdown page per period, never a scan. Whole-period turnover and excluding-tax margin deltas are computed only from complete source values. Percent growth is null with a reason when the prior base is unknown, zero or negative. Duration differences and non-atomic read times are explicit. A failed period or breakdown is partial, not zero; first-page group comparisons cannot prove a full contribution if either page continues. Do not average shop baskets/ratios or claim causality. Example: 'August versus July turnover' -> {current_from:'2026-08-01',current_to:'2026-08-31',previous_from:'2026-07-01',previous_to:'2026-07-31'}; 'Compare Paris shop contribution' -> {current_from:'2026-08-01',current_to:'2026-08-31',previous_from:'2026-07-01',previous_to:'2026-07-31',dimension:'shop'}. Use analyze_sales_breakdown for further pages if authorized.
get_after_sales_case
ChatGPTUse a known uuid from search_after_sales_cases for work, entrusted object, promise, quote and proven current-status age. Request finance only when needed: balance needs sav:read, sales:read and customer-credits:read; credits needs customer-credits:read; contact needs customers:pii:read. confirmedAmountDue is always null; provisionalAfterDeposits is an estimate and legacy remainingAmount/paid cannot prove debt. Use get_after_sales_timeline for transitions and get_after_sales_document for official PDF if allowed. Example: 'Status of SAV-1' -> {sav_id:'SAV-1'}; 'Show sourced finance' -> {sav_id:'SAV-1',include:['balance']}. Entrusted items are not saleable stock.
get_after_sales_document
ChatGPTUse only for the official intake/repair slip of a known after-sales case. The PDF is transferred through an authenticated GET and embedded as an MCP resource (maximum 5 MiB); no public URL or bearer token is returned. Do not fabricate a replacement document. Example: 'Give me the official slip for SAV-1' -> {sav_id:'SAV-1'}; 'Can I save the repair receipt for SAV-2?' -> {sav_id:'SAV-2'} and use the embedded PDF if the client supports it. PDF display/download support must be verified separately in Claude and ChatGPT.
get_after_sales_timeline
ChatGPTUse for documented steps of a known case, not backlog totals. The paginated journal can be incomplete; absence of an event proves nothing. Use get_after_sales_case for current status and proven age. Example: 'Steps for SAV-1' -> {sav_id:'SAV-1',page:1,limit:20}; 'Steps since September 1' -> {sav_id:'SAV-1',from:'2026-09-01T00:00:00Z'}. Do not reconstruct historical backlog from this log.
get_business_overview
ChatGPTChoose a concise management view only for explicitly named blocks: sales activity, current stock valuation and/or open SAV backlog. No default block or hidden customer identities, catalogue scan, anomaly list or supplier expansion. Each authorized block consumes one fixed native GET (at most three), retains its own quality/time and may be unknown even when the call succeeds. An ungranted block is marked forbidden without an upstream request; a failed block is not zero. Stock and SAV group pages can be incomplete although their native summaries are whole-population. If all requested rights are missing, reconnect with the appropriate grants. Sales needs explicit company-local inclusive dates; SAV accepts at most one selected shop. No cross-block causal inference or atomic snapshot. Example: 'August sales, stock and repairs' -> {blocks:['sales','stock','sav'],from:'2026-08-01',to:'2026-08-31'}; 'Only current repair backlog in COMP-1' -> {blocks:['sav'],company_id:'COMP-1'}. Use get_sales_summary, get_stock_value_summary or analyze_after_sales_workload for deeper authorized views.
get_connection_context
ChatGPTUse this read-only tool to learn which Commerce 360 companies and shops this authenticated connection can currently access and which read capabilities are available for each company. It takes no arguments and needs no business scope. Use it before company-scoped stock, sales or replenishment questions when the company or shop ID is unknown. If several companies are returned, ask the user to choose; do not pick the first. If a capability is false, do not treat that business read as available. A true capability is only an informational snapshot, not a grant or proof that any record exists; each later API call checks rights again. No pagination, stock totals, sales amounts or historical authorization are returned. Example 1: User asks 'Which shops can I analyze?' -> call with {} and present the company and shop IDs. Example 2: User asks 'Why can't I see sales for Lyon?' -> call with {}, inspect that company's salesRead/statisticsSalesRead and shops, then explain the observed scope or assignment; do not change permissions.
get_customer_credits
ChatGPTUse for notes and deposits of a known customer. Always transmit native type=note,deposit by default: omitting it in Lumos would include gift cards. Request gift_card explicitly only with gift-cards:read; every call also needs customers:read and customer-credits:read. Official amountLeft is a per-credit remaining balance, not a full-customer or network total; continue pages before any user-requested aggregate. Example: 'Active notes and deposits of CUST-1' -> {customer_id:'CUST-1',status:'active'}; 'Include their gift cards' -> {customer_id:'CUST-1',types:['note','deposit','gift_card'],page:1,limit:20}. Use get_gift_card for one known card uuid, not a global card search.
get_customer_history
ChatGPTUse for a known customer's selected sales, orders, reservations, SAV cases, quotes or credits. Each requested family requires its own right; missing rights fail rather than silently dropping a family. Every family is independently capped by limit_per_type (1-100), with hasMore for that family but no continuation cursor. The API may include gift-card credits in its credits family; for explicit credit types/pages use get_customer_credits. Example: 'Sales and repairs for CUST-1' -> {customer_id:'CUST-1',include:['sales','sav']}; 'Recent orders only' -> {customer_id:'CUST-1',include:['orders'],from:'2026-01-01',limit_per_type:20}. For additional sales use search_sales, for one SAV use get_after_sales_case if those tools are authorized; do not infer complete history from a capped family.
get_customer_profile
ChatGPTUse only after selecting an exact uuid from search_customers. Basic profile includes loyalty and non-contact identity, not purchase history. Personal contact/address/birthday/couple are locally withheld unless explicitly selected in personal_fields and customers:pii:read is granted; the API may otherwise publish them automatically to a PII-authorized account. Partner/billingAddress need an explicit include and PII rights; internalComments needs explicit include and internal-comments:read. Consent facts do not authorize an automatic campaign. Example: 'Show CUST-1 loyalty profile' -> {customer_id:'CUST-1'}; 'Check email contact and consent' -> {customer_id:'CUST-1',personal_fields:['contact'],include:['consents']}. Use get_customer_history for records or get_customer_purchase_summary for governed observed buying behavior when permitted.
get_customer_purchase_summary
ChatGPTNet spend is net turnover from signed sales movements at their business movement dates, including cancellations and returns and negative modifications, not amounts on initial baskets. historyNetSpend runs through asOf; periodNetSpend and previousNetSpend use their own inclusive movement-date windows. Frequency/recency remain native eligible initial-ticket metrics: zero purchases can coexist with negative turnover. Native business turnover of zero for a deposit/payment stays zero, not cash received. Honor company/shops, amount_mode, scope and exclude_retrocessions; null is unknown. Attribution uses a proven event customer ID or unambiguous initial ticket link within authorized shops, never names/contacts; unlinked movements are not attributed. Use for an exact customer uuid to compare observed recency, frequency and net turnover across authorized shops in current and preceding equal-length company-local day windows. No fuzzy cross-company join by name, line items, CLV prediction or proof of lifetime history. A 404 means no consolidated observable movement/ticket in this authorized scope, not 'never bought'. historyComplete=null remains unknown. Example: 'CUST-1 purchases in September so far' -> {customer_id:'CUST-1',from:'2026-09-01',to:'2026-09-24'}; 'Same customer in SHOP-1' -> {customer_id:'CUST-1',from:'2026-09-01',to:'2026-09-24',shop_ids:['SHOP-1']}. For documents use get_customer_history or search_sales if authorized; never infer missing older activity from zero observed facts.
get_gift_card
ChatGPTUse only for a known public gift-card uuid, e.g. from an explicitly authorized customer-credit page; the masked card number is not a lookup key or redeemable code. There is no GET search by number or total of all cards. Base read needs gift-cards:read; customer relation needs customers:read; origin, usages and invoice need sales:read. Example: 'Balance of CARD-1' -> {gift_card_id:'CARD-1'}; 'How was CARD-1 used?' -> {gift_card_id:'CARD-1',include:['usages']}. Amount is issued value; amountLeft is the official current balance, not new cash or turnover.
get_product_details
ChatGPTUse after search_products when the public product ID is known. The reference view reads one current product; the items view reads its attached physical items in one non-paginated API call. The items view defaults to currently available items; set available_only:false to include unavailable items. For potentially large item collections use search_product_items with product_id and pagination. Shop/stock views require stock rights. Example: 'Show BAG-001 details' -> {product_id:'PROD-1'}; 'Show its articles in Paris' -> {product_id:'PROD-1',view:'items',shop_id:'SHOP-1'}.
get_product_item_details
ChatGPTUse when an exact physical item ID is known and its serial number, price, promotion, shop or typed characteristics matter. A product's theoretical weight does not replace an item's measured weight; size variants are not interchangeable. Example: 'Show ITEM-1' -> {item_id:'ITEM-1'}; 'Show its material and shop' -> {item_id:'ITEM-1',include:['characteristics','shop']}. Use stock availability for allocations and operational quantity.
get_product_item_v1
ChatGPTDirect read-only GET /v1/product-items/{itemId}. Returns one physical item by public item id with price, promotion, availability and optional product, characteristics, media, shop, category or supplier relations.
get_product_v1
ChatGPTDirect read-only GET /v1/products/{productId}. Returns one product reference by public product id, with optional characteristics, media, prices, stock and items. Use after list_products_v1 when the user needs full product detail.
get_reference_details
ChatGPTGet full read-only details for one HBJO reference using reference, reference_uuid, reference_id, or article_code. Returns catalogue fields, supplier, stock status, and all articles.
get_reference_stock
ChatGPTGet stock availability for one HBJO reference or article, optionally filtered to one shop. Use this for direct questions like 'combien reste-t-il de cette référence ?'.
get_reference_stock_value
ChatGPTCompute finite stock value for one HBJO reference or article, optionally filtered to one shop. Uses article price times stockAvailable.
get_sale_details
ChatGPTUse for an identified sale's items, payments, discounts, shop, seller, invoice or origins, not for a period aggregate. Request only necessary relations. paymentsEvidence=historical_unknown is not proof of an unpaid balance; a similar item label is not a proven historical product join. Customer-credit details in payments are withheld without customer-credits:read; no customer contact relation is requested. Example: 'Show SALE-1' -> {sale_id:'SALE-1'} and read its document status/amounts; 'Explain its lines and payments' -> {sale_id:'SALE-1',include:['items','payments','discounts']} and check IDs and payment evidence. For signed period facts use inspect_sales_activity; for the official invoice use get_sale_invoice.
get_sale_invoice
ChatGPTUse for official invoice metadata of a known sale; request download=true only when the user explicitly needs its private PDF. Never reconstruct an invoice from sale figures. The PDF is fetched only after metadata says downloadAvailable=true, with user-bound authorization, 5 MiB and time bounds; it is an embedded MCP resource, never a public URL or base64 text. If unavailable, metadata alone is returned. Client rendering/download in Claude or ChatGPT is not yet validated. Example: 'Invoice metadata for SALE-1' -> {sale_id:'SALE-1'} and read official totals; 'Give me the official PDF' -> {sale_id:'SALE-1',download:true} and use the resource only if attached and supported.
get_sale_invoice_v1
ChatGPTDirect read-only GET /v1/sales/{saleId}/invoice. Returns official invoice metadata, totals, issue date, status, number, and whether the PDF is available. It does not download the binary PDF.
get_sale_v1
ChatGPTDirect read-only GET /v1/sales/{saleId}. Returns one sale with requested non-customer relations such as items, payments, discounts, shop, seller, invoice, or origins. Customer identity and contact details are intentionally redacted.
get_sales_summary
ChatGPTUse for whole-period signed turnover, returns, tax, discount, article cost/margin and baskets, not a list of sales. Dates are inclusive company-local days; API defaults: inclTax, extended scope, retrocessions included. Native aggregates cover all authorized facts, not a capped sales page. Average basket uses native shop-sale tickets; median uses only eligible positive initial baskets, so populations differ. Null is unknown, not zero; knownTurnover is only a subtotal. Margin is article margin excluding tax, not profit after expenses. Example: 'September turnover' -> {from:'2026-09-01',to:'2026-09-30'}; 'Paris sales excluding tax' -> {from:'2026-09-01',to:'2026-09-30',shop_ids:['SHOP-1'],amount_mode:'exclTax'}. For one-dimensional groups use analyze_sales_breakdown; for product groups use list_top_selling_products.
get_stock_availability
ChatGPTUse for a known product/item or bounded page of current physical stock, allocations, raw balance, floored availability, operational flags and native anomalies. state:active hides terminal rows, not zero availability. positive_available_only=true selects known finite availability > 0 before totals/pagination; false removes that filter, not its inverse. Unknown finite physical quantity is natively treated as zero and flagged; unlimited quantity is null. Availability is not historical inventory and first entry is not current-shop arrival. Example: 'How many ITEM-1 remain?' -> {item_id:'ITEM-1'}; 'Positive finite stock of PROD-1 in Paris' -> {product_id:'PROD-1',shop_ids:['SHOP-1'],positive_available_only:true,page:1,limit:20}. Continue native pages; summary is the full filtered population. Use list_stock_anomalies for proven source anomalies and get_stock_value_summary for valuation/productShop grouping. High quantity alone is not proof of incorrect stock.
get_stock_operations_summary
ChatGPTReturn an operational stock dashboard: reference/article counts, recent entries, stale stock, stock statuses, and anomaly counts. Use this for broad questions like 'fais un état du stock'.
get_stock_value_summary
ChatGPTUse for current finite available-stock valuation by shop, product, productShop pair, supplier, category or type, without scanning articles. productShop returns separate productId/shopId keys and native metrics; do not repeat product-wide amounts across shops or sum shop distincts into network distincts. Purchase cost is HT, sale price TTC; known subtotals are distinct from nullable complete values and zero cost is known. Unlimited/unknown physical quantity is excluded from finite valuation and counted separately. Supplier/category/type are current classification; single-dimension null ID means unclassified. Product IDs and positive_available_only apply before full summary/group pagination. This is not gross physical stock, historical inventory or accounting valuation. Example: 'Cost value by shop' -> {dimension:'shop',page:1,limit:20}; 'Positive stock by reference and shop' -> {dimension:'productShop',positive_available_only:true,sort_by:'knownCostValueExclTax',sort_order:'desc'}. Follow pagination for all groups; prefer native aggregates to item extraction. High average quantity is a fact to review, not a proven anomaly; inspect list_stock_anomalies for source flags.
inspect_sales_activity
ChatGPTUse for traceable signed sales facts over inclusive company-local business dates, including articles sold by an identified seller without scanning sale documents. grain='movement' returns entire movement amounts; grain='line' returns line amounts, persisted product/article IDs and current proven reference code/name. For a seller name first use analyze_sales_breakdown with dimension='seller', same company/shops/period, continue its group pages and confirm the exact seller ID; never silently choose a homonym. Then pass seller_id with grain='line', usually line_type='product'. Both filters are applied natively before counting/pagination. Attribution follows the same sale/order/SAV rules as seller breakdown, not the cashier's name. Product lines retain signed returns/cancellations; do not call gross positive lines net sales or sum only the first page. Unknown amounts/quantities remain null; labels are current, not historical. A product-filtered movement still carries the entire movement amount, never that product's share. A line's payment component is not a payment allocated to a product. nextCursor expires after 15 minutes, is bound to principal, rights, company, shops, all filters and limit; corrections can affect later pages. Example: 'Movements for SALE-1' -> {grain:'movement',from:'2026-09-01',to:'2026-09-30',sale_id:'SALE-1'}; 'Articles sold by the confirmed seller SELLER-1 this year' -> {grain:'line',from:'2026-01-01',to:'2026-10-06',seller_id:'SELLER-1',line_type:'product',limit:100}. Continue every cursor page with unchanged arguments; report incomplete coverage if stopped. Use get_sales_summary for whole-period totals, search_product_items for explicit bounded article enrichment, and list_payment_entries for settlement dates.
list_catalog_changes
ChatGPTUse for incremental catalogue synchronization since a known ISO instant, not to infer physical stock movements or a complete deletion log. Keep the returned until bound fixed across pages and reuse it as the next cycle's since. Example: 'Changes since yesterday' -> {since:'2026-09-23T00:00:00Z',page:1,limit:20}; 'Only shop changes to a fixed cutoff' -> {since:'2026-09-01T00:00:00Z',until:'2026-09-24T00:00:00Z',types:['shops']}.
list_catalog_changes_v1
ChatGPTDirect read-only GET /v1/catalog/changes. Returns incremental catalogue changes since an ISO date-time for products, product-items, categories, characteristics, or shops. Use this for questions about what changed since a date.
list_catalog_products_v1
ChatGPTDirect read-only GET /v1/catalog/products. Returns the complete e-commerce catalogue feed with products, product items, prices, media, stock, shops, suppliers, updatedAt and pagination. Use this for native V1 catalogue fields or catalogue synchronization questions.
list_categories
ChatGPTUse to discover the actual hierarchy and category IDs before filtering products or stock. Do not derive an authoritative category from a product label. Example: 'Which categories are under rings?' -> {parent_id:'CAT-RINGS'}; 'Which second-hand categories exist?' -> {is_second_hand:true,include:['children']}.
list_categories_v1
ChatGPTDirect read-only GET /v1/categories. Returns catalogue categories, optionally filtered by parent, product type, online display or second-hand status, and can include child categories. Use for category filtering and navigation questions.
list_characteristic_values
ChatGPTUse after resolving a characteristic ID to learn configured or used values and IDs for a typed stock filter. A possible value is not evidence that it is present in current stock. Example: 'Which sizes are configured?' -> {characteristic_id:'CHAR-SIZE'}; 'Which sizes occur in available rings?' -> {characteristic_id:'CHAR-SIZE',category_id:'CAT-RINGS',used_only:true,available_only:true}.
list_characteristic_values_v1
ChatGPTDirect read-only GET /v1/characteristics/{characteristicId}/values. Returns allowed or used values for one characteristic, optionally scoped to product type, category or available stock.
list_characteristics
ChatGPTUse before filtering by metal, stone, size or another characteristic: resolve the configured ID, form and type rather than guessing a free-text code. A definition's presence does not prove any article has a value. Example: 'Which item characteristics represent size?' -> {form:'item'}; 'List ring characteristics and their values' -> {category_id:'CAT-RINGS',include:['values']}.
list_characteristics_v1
ChatGPTDirect read-only GET /v1/characteristics. Returns product and item characteristic definitions, optionally filtered by product type, category, display flag or form context, and can include referential values.
list_customer_segment_members
ChatGPTNet spend is net turnover from signed sales movements at their business movement dates, including cancellations and returns and negative modifications, not amounts on initial baskets. historyNetSpend runs through asOf; periodNetSpend and previousNetSpend use their own inclusive movement-date windows. Frequency/recency remain native eligible initial-ticket metrics: zero purchases can coexist with negative turnover. Native business turnover of zero for a deposit/payment stays zero, not cash received. Honor company/shops, amount_mode, scope and exclude_retrocessions; null is unknown. Attribution uses a proven event customer ID or unambiguous initial ticket link within authorized shops, never names/contacts; unlinked movements are not attributed. Use only after the user asks for members of one governed segment, with the same period, authorized shops, amount mode, scope and rules as the summary. Returns IDs and observed buying metrics only, never contacts or consents; no automatic profile enrichment or full-base extraction. Native order is oldest last purchase then uuid, not highest spend. Example: 'First 20 declining regulars' -> {segment:'decliningRegular',from:'2026-07-01',to:'2026-09-24',page:1,limit:20}; 'Inactive high-value members at 2000 EUR' -> {segment:'highValueInactive',from:'2026-07-01',to:'2026-09-24',high_value_threshold:'2000.00',page:1,limit:20}. Continue only when page < totalPages, preserving exact rules; membership is not campaign consent.
list_payment_entries
ChatGPTUse for dated signed settlement entries, optionally linked to one sale, when aggregated payment-method totals are insufficient. Business dates are settlement dates, not sale creation dates; values are incl. tax and credit/gift-card/deposit use is not new cash. Neither product_id nor payment-method filter exists, and payments must never be attributed to a product. Cursor pages are not complete totals; keep principal, rights, shops, filters, scope and limit unchanged across continuation, and restart after expiry (15 minutes). Example: 'Payments for SALE-1' -> {from:'2026-09-01',to:'2026-09-30',sale_id:'SALE-1'} and inspect known settlement entries; 'Known Paris payments this month' -> {from:'2026-09-01',to:'2026-09-30',shop_ids:['SHOP-1'],limit:50} and continue while nextCursor exists. For native payment mix totals use analyze_payment_methods; this is not turnover or a bank reconciliation.
list_product_items_for_product_v1
ChatGPTDirect read-only GET /v1/products/{productId}/items. Returns physical items attached to one product, with availability, shop, promotion, updatedSince and optional characteristics/media/shop relations. Use when the user asks for item-level stock for one known product.
list_product_items_v1
ChatGPTDirect read-only GET /v1/product-items. Searches physical items globally with stock availability, price range, promotion, second-hand, product, shop, supplier, product type, category, updatedSince and include filters. Use this for article-level questions across the stock.
list_product_types
ChatGPTUse to find configured product-type IDs and optional categories/characteristics. Types vary by jeweler and should not be inferred from generic jewelry terms. Example: 'List types' -> {}; 'Show online types and their characteristics' -> {displayed_online:true,include:['characteristics']}.
list_product_types_v1
ChatGPTDirect read-only GET /v1/product-types. Returns product types, optionally with categories and characteristics. Use this to discover product families before filtering products or characteristics.
list_products_v1
ChatGPTDirect read-only GET /v1/products. Searches and filters product references by text, online display, availability, updatedSince, supplier, product type, category, shop and optional include relations. Use this to find product IDs before requesting full product or item details.
list_recent_stock_entries
ChatGPTList articles whose inStockDate is in a date range. Use this for questions like 'articles entered in stock in the last 3 months'. If the user says last 3 months, use last_days=90.
list_references_by_stock_status
ChatGPTList HBJO references by computed stock status: available, out_of_stock, or unlimited. Use this for questions about ruptures, available stock, or unlimited references.
list_referential_shops_v1
ChatGPTDirect read-only GET /v1/shops. Returns Commerce 360 shop referential data. Use this when the user needs official shop IDs or wants to choose a shop filter.
list_restock_candidates_from_sales
ChatGPTUse when the jeweler provides an explicit inclusive sales period and coverage horizon. The API combines gross sales demand and current availability/allocations by product and shop: ceil(max(0, grossSalesQuantity / observedDays * coverageDays - availableQuantity)). Returns and cancellations do not reduce gross demand; allocations are already deducted and must not be subtracted twice. A null recommendation means demand quantity is unknown, not zero. No incoming supply, lead time, seasonality, item-size match or purchase order is included. Example: 'Plan 30 days using July sales' -> {from:'2026-07-01',to:'2026-07-31',coverage_days:30}; 'Only these products in Paris' -> {from:'2026-07-01',to:'2026-07-31',coverage_days:30,product_ids:['PROD-1'],shop_ids:['SHOP-1']}. Keep quality warnings and separate read instants; inspect individual items with get_stock_availability before a decision.
list_sales_v1
ChatGPTDirect read-only GET /v1/sales. Use to find documents by creation date, shop, status, action, number, customer public ID or seller_id. The seller is recorded on the current/history document, not the native Statistics sale/order/SAV attribution used by inspect_sales_activity grain=line. It filters before count and pagination, not signed turnover. Customer names and contact details are intentionally redacted. Example: 'Documents recorded for seller SELLER-1' -> {seller_id:'SELLER-1',page:1,limit:25}; 'Their next Paris page' -> {seller_id:'SELLER-1',shop_id:'SHOP-1',page:2,limit:25}, keeping all filters unchanged. Prefer search_sales for the canonical reader and dedicated sales analysis tools for totals.
list_shops
ChatGPTUse this read-only official shop referential to find shop IDs, names, short names and cities, including shops with no current stock. A shop in this referential is not necessarily accessible for every business call; use get_connection_context to check the authenticated assignment. Example: 'Which shops are active?' -> {active_only:true}; 'List also inactive shops' -> {active_only:false}. Homonyms require disambiguation by ID.
list_stale_stock
ChatGPTList available articles whose inStockDate is older than a threshold. Use this for dormant/old stock questions, for example stock older than 12 months.
list_stock_anomalies
ChatGPTUse to inspect native source anomalies: negative physical quantity, over-allocation, terminal stock, allocated terminal items, missing finite physical quantity or missing cost. One item may have several anomaly categories; do not add category counts as distinct items. Zero cost is known, not missing. This is not an online-publication audit and never fixes data. Example: 'Find overallocated items' -> {category:'over_allocated'}; 'Anomalies for PROD-1' -> {product_id:'PROD-1',page:1,limit:20}. Keep the summary's full filtered population separate from the page and inspect a matching item with get_stock_availability if needed.
list_stock_value_by_shop
ChatGPTBreak down finite stock value by HBJO shop. Use this for questions about stock value per boutique or store.
list_stock_value_by_supplier
ChatGPTBreak down finite stock value by HBJO supplier. Use this for supplier valuation, vendor exposure, or stock value ranking by supplier.
list_suppliers
ChatGPTList suppliers found in HBJO references, optionally filtered by supplier name, short name, or UUID. Use this before supplier-specific catalogue searches.
list_top_selling_products
ChatGPTUse for product groups ranked natively over the whole period by complete turnover, gross sold quantity, signed net quantity, excluding-tax cost or margin. Choose sort_by explicitly: omitted sort ranks known turnover, not complete turnover. product_id/product_ids select returned groups and totalGroups only; summary and meta.coverage remain GLOBAL to the period. Use the selected row.metrics for product sales, never the global summary. Unresolved historical product groups have null id and a reason; do not guess an ID. Example: 'Top 20 by quantity' -> {from:'2026-09-01',to:'2026-09-30',sort_by:'soldQuantity',limit:20}; 'Sales of PROD-1' -> {from:'2026-09-01',to:'2026-09-30',product_id:'PROD-1',sort_by:'turnover'}. Resolve an exact product ID with search_products if permitted; no catalog scope is needed for this native ranking. Continue pages with unchanged filters.
list_top_stock_value_references
ChatGPTList HBJO references ranked by finite stock value, highest first. Use this to identify the most valuable references in stock.
prepare_customer_visit
ChatGPTUse only after search_customers has resolved one exact customer ID; never select a namesake automatically. Choose explicit blocks among profile, bounded history, note/deposit credits, governed purchase statistics and SAV. Each block/family checks its own scopes; forbidden, unknown, failed and truncated are distinct from no activity. Profile/history/credits each use one initial GET when selected and permitted. SAV reuses a requested history SAV family instead of rereading it; otherwise it uses one customer-filtered SAV page. Only up to three explicitly selected, already-observed SAV case IDs may receive detail; an optional balance still cannot prove debt. No contacts, addresses, comments, gift-card numbers, campaign, CRM note or message. Example: 'Prepare CUST-1 from sales and credits' -> {customer_id:'CUST-1',blocks:['profile','history','credits'],history_families:['sales']}; 'Inspect one observed repair without finance' -> {customer_id:'CUST-1',blocks:['sav'],sav_case_ids:['SAV-1']}. For more history follow the authorized native readers; do not infer preferences from a bounded list.
read_catalog_products
ChatGPTUse only when rich product/item/media/price/stock projections or explicit synchronization are needed. Prefer search_products with include supplier for a lightweight supplier lookup. By default only published products and non-dummy items are returned. include_unpublished includes both publication states; include_dummy adds fictitious items but never counts them as available. createWebProductSheet is a web-team request, not proof of a live page. Rich fields include advised price, promotion dates, sale flags, nomenclature, type and item stock quantities; null remains unknown. Shop filtering also scopes aggregates and effective advised price. This is paginated current state, not stock-movement history; updated_since may miss allocation-only changes, so refresh stock separately. Example: 'Rich view of these products, including offline' -> {product_ids:['PROD-1','PROD-2'],include_unpublished:true}; 'Audit dummy articles on one shop' -> {shop_uuid:'SHOP-1',include_dummy:true,page:1,limit:20}.
search_after_sales_cases
ChatGPTUse for operational cases by number/text, current status, creation, promised availability or proven current-status age. These are distinct filters: an old case with a new promise must use availability dates, not creation dates. Age comes from a coherent SAV_STATUS transition, never updatedAt. This page is not a backlog total; use analyze_after_sales_workload for open-case aggregates. Reuse uuid in get_after_sales_case or get_after_sales_timeline. Example: 'Cases promised this week' -> {availability_from:'2026-09-21',availability_to:'2026-09-27'}; 'Ready for at least 15 days' -> {status:'ready',status_age_min_days:15}. Null status age means unknown, not recent.
search_customers
ChatGPTUse directory mode for a bounded customer list filtered by name/text, home shops, company, type, guest state, update time, recorded consents, contact presence and observed purchases. Purchase criteria or include=purchaseStats need sales:read and every company history shop including closed shops; guest=true cannot be combined with purchase criteria, purchaseStats, from/to or amount_mode because native purchase readers exclude guests. Last purchase before is exclusive, after inclusive. purchaseStats includes signed Statistics net spend at business movement dates; from/to is a paired inclusive amount window, otherwise observed history through as_of. Presence filters need customers:pii:read. Metadata records the effective scope and unknown history; no implicit 24-month rule. Use export_customers for a complete private extraction. Use identity mode only with a specific identity criterion and customers:pii:read. Directory without a filter is refused to avoid a broad extraction. Rows are candidate records, not a fuzzy cross-company merge; never select the first namesake silently. Directory contact coordinates are withheld even when the token has PII rights; use an exact profile lookup if authorized. Example: 'Customers named Martin' -> {mode:'directory',search:'Martin',page:1,limit:20}; 'Find customer number C-123 exactly' -> {mode:'identity',customer_number:'C-123',match_mode:'exact'}. Ask for disambiguation if several IDs match; reuse the selected uuid for get_customer_profile or get_customer_purchase_summary if authorized.
search_product_items
ChatGPTUse for physical article search by shop, product, supplier, price including tax, promotion, second-hand state or a batch of up to 50 known item IDs. This is a paginated current item read, not initial-stock-age history. Example: 'Promotional items between 500 and 1000 EUR' -> {has_promotion:true,price_min:500,price_max:1000}; 'Enrich these IDs' -> {item_ids:['ITEM-1','ITEM-2'],available_only:false}. Compare requested and returned IDs; missing does not prove deletion or disclose another tenant.
search_products
ChatGPTUse the light product search for exact reference/EAN/ID or partial wording, supplier, category, type and visibility. Include supplier for a cheap commercial-supplier lookup; use read_catalog_products only for rich catalogue projection. An exact selector is not text search. Names may be shared by multiple products: disambiguate by public ID, reference or EAN rather than silently picking one. Current availability is not historical inventory. Example: 'Find BAG-001 even if offline' -> {reference:'BAG-001',visibility:'all'}; 'Which products belong to supplier SUP-1?' -> {supplier_id:'SUP-1',include:['supplier'],page:1,limit:20}. Continue pages only when pagination.hasNextPage is true.
search_references
ChatGPTSearch HBJO catalogue references by reference code, product name, article code, supplier, shop, or characteristic value. Use this when the user gives a partial reference, product wording, supplier, or article text.
search_references_by_characteristic
ChatGPTSearch HBJO references by article characteristic code and optional value. Real characteristic codes include SIZE, STONE, METAL_WEIGHT, WEIGHT_OF_THE_STONE, and STONE_CUTTING.
search_sales
ChatGPTUse to locate sale documents by exact or partial number, creation instant, authorized customer ID, seller_id, current status/action or shop before reading a document. seller_id selects the seller recorded on the current/history document before count and pagination; it is not the native Statistics sale/order/SAV attribution used by inspect_sales_activity grain=line. Pagination covers documents only; it is not signed turnover and creation dates are not sales business dates. Customer contact fields are not requested. Example: 'Find V-2026-00184' -> {number:'V-2026-00184',page:1,limit:20} and check the public ID before detail; 'Documents recorded for seller SELLER-1 in Paris' -> {seller_id:'SELLER-1',shop_id:'SHOP-1',page:1,limit:25} and continue pages with the same filters, not as a period turnover total. Use get_sales_summary for turnover or inspect_sales_activity for signed facts and Statistics seller attribution.
search_suppliers
ChatGPTUse to resolve a current commercial supplier by public ID or name before filtering products or stock valuation. Includes suppliers with no current stock; a supplier is not necessarily a brand. No purchase terms, lead times or price lists are returned. Example: 'Find Dupont suppliers' -> {search:'Dupont',page:1,limit:20}; 'Which supplier is SUP-1?' -> {supplier_id:'SUP-1'}.
suggest_stock_transfers
ChatGPTUse this only for up to twenty resolved products, two distinct authorized shops and explicit inclusive company-local sales dates. The receiver's native gross-demand replenishment gives its need; donor gross sales protect a reserve. Current donor articles are read in at most three pages and only operational finite, anomaly-free availability can support a provisional product-level quantity. Optional required_item_characteristics restrict and recheck exact item-level size/variant evidence; without them size compatibility is unverified and no physical piece is selected. Missing donor history, unknown quantity, partial pages or mismatched effective scopes withhold all numbers, not imply surplus. No arrivals, logistics, product equivalence, order or transfer execution. Example: 'Could Paris supply Lyon for PROD-1?' -> {product_ids:['PROD-1'],origin_shop_id:'SHOP-PARIS',destination_shop_id:'SHOP-LYON',from:'2026-09-01',to:'2026-09-30',coverage_days:30}; 'Only a verified size for Lyon' -> {product_ids:['PROD-1'],origin_shop_id:'SHOP-PARIS',destination_shop_id:'SHOP-LYON',from:'2026-09-01',to:'2026-09-30',coverage_days:30,required_item_characteristics:[{characteristic_id:'SIZE-1',characteristic_code:'SIZE',value_id:'SIZE-54'}]}. Inspect exact pieces and logistics with the merchant before any action.
