NOGL
Retailer docs

Retailer documentation

Plan, validate and review a connection.

A technical guide for the retailer and the person responsible for the source. Agree the data contract before granting access or relying on a recurring delivery.

1. Choose the access path

A public observation, a private data extract and an outbound notification have different permissions and acceptance criteria. Choose one path for the first test.

  • Public source: agree URLs, country, product scope and observation date. Accessible Shopify catalogs can be tried in the public demo; other coverage needs confirmation.
  • Customer-owned input: agree a limited export or approved access method. Listing a platform in the directory does not establish a working authenticated connector.
  • Outbound delivery: agree the destination and recipients. Validate a test delivery before relying on a digest, worksheet or notification.

2. Write a small data contract

Record what a row means, which system owns it and what a successful handoff looks like. The example below is a proposed catalog contract, not an upload format accepted by every connector.

  • Scope: named source, market, product range, date window and read or write direction.
  • Identity: stable product and variant keys; document mappings when IDs differ between systems.
  • Values: field types, currency, tax treatment, units, time zone and rules for missing values.
  • Delivery: agreed method, schedule, freshness limit, owner and how to stop or revoke access.
Example catalog contract
FieldMeaningValidation
product_key / variant_keyStable source identityUnique at the agreed row grain
observed_atObservation time with time zoneWithin the accepted freshness window
gtinGlobal trade item number shown on the source listing8, 12, 13 or 14 digits with a valid check digit; unknown stays empty
delivery_termsDelivery fee, lead time and delivery area as displayedCurrency and tax basis recorded; unknown stays unknown and is never read as zero
price / currencyDisplayed or agreed price basisTax and currency definition recorded
availabilitySource availability labelUnknown remains distinct from unavailable
source_referenceTraceable source record or URLReviewer can reconcile the sample
Review a product record

Fictional field-scope example

Review the field before planning the connection

A public listing, a requested private field and a proposed write are different kinds of evidence. Use this fictional example to separate them before discussing a connection. This guide does not connect an account.

Illustration version: t21-v1

Start with one retailer question

Choose a question to inspect a fixed example. The choice changes only this illustration; it requests no data or permissions.

What does this public offer show?

F01 · Variant title

Trace the field to its source

Compare the source field with the proposed NOGL field. A proposed match is not a verified mapping. An ambiguous or missing identity stays unresolved.

Source field
listing.variant_title
Proposed NOGL field
product.title
Source ID
FX-PUBLIC-01
Fictional source reference
fixture:catalog/linen-shirt-blue-m
Mapping status
Proposed match — not verified

Separate access from direction

Public evidence does not establish access to private records. Requested access is not granted access. A proposed write requires a separate scope and approval review; no write runs here.

Direction
Read evidence
Access status
Public example only
  • Permission evidence: not supplied
  • Merchant approval: unknown
  • NOGL runtime support: unverified

The displayed direction and access status follow the selected field; selecting a field never changes its permission, approval, mapping or runtime evidence.

Keep the missing context visible

Check source version, observation time, variant, location, currency and unit where relevant. Missing values stay unknown; they do not become zero. An availability label does not establish location-level stock.

Illustrative value
Linen shirt · blue · M
Currency
Not supplied
Unit basis
Not supplied
Value observation time
2026-09-30T09:00:00Z
Value source ID
FX-PUBLIC-01
Source / proposal version
fixture-v1
Requested scope version
fixture-v1
Evidence scope
Authored public-listing example; one variant, German market, one displayed offer.
Metadata basis
Authored illustration; missing value or time has no asserted observation provenance.

fixture-v1 describes this authored illustration, not a verified source schema or supplier quote version.

Proposal metadata is not value provenance

One fictional variant only; source identity remains a proposal.

Prepare a human review

Show the unresolved items for the selected question. A source owner must verify identity, field meaning, minimum permission and the intended direction. These notes are an illustration, not a submitted request or an approval.

Show review notes

These open items belong to the selected question; none is resolved by this example.

  • F01 · Variant title

    One fictional variant only; source identity remains a proposal.

  • F02 · Displayed price

    EUR is supplied in the fixture; tax and shipping basis are unknown.

  • F03 · Availability wording

    Listing wording only; no quantity, location or sales evidence.

A source owner must verify identity, field meaning, minimum permission and intended direction before a separately authorized test.

Agree a bounded next step

Use the connection plan to agree source ownership, data limits and a separately authorized test. Connector feasibility, runtime support and merchant approval remain unverified. Nothing is imported, published or synchronized here.

Plan a bounded connection reviewReview product informationSee the seven-stage cycle

3. Authorise the minimum agreed scope

Use the setup method agreed with NOGL and your source administrator. This documentation does not grant permissions or connect accounts.

  • Have the source owner approve the fields and destination. Begin with a test sample or a limited read scope where appropriate.
  • Separate test and production destinations. Check whether an output appends records or replaces an existing range.
  • Agree a secure credential exchange if credentials are required. Never send passwords, API keys or customer records through a general contact form.
  • Record the person responsible for revocation, credential rotation and changes to the source schema.

4. Validate against the source

Review a small sample together before expanding coverage. Successful transport alone does not prove that the data is complete or suitable for the retail question.

  • Count received, missing and duplicate records. Compare stable keys and a few known products directly with the source.
  • Reconcile prices, currencies, units and timestamps. Distinguish an unavailable value from a genuine zero.
  • For a public scan, keep observed count and completeness separate. A partial result is useful evidence but not a complete catalog total.
  • For an outbound message or worksheet, inspect the actual destination and recipient visibility. Confirm replacement and duplicate behaviour.
  • Record the test date, scope, result, unresolved gaps and the person approving the next step.
Compare prepared MCP records

5. Agree the health review

Before making a recurring connection part of a decision process, agree who reviews failures and how stale data is presented. These are acceptance requirements, not claims of a live monitoring dashboard.

  • Last successful observation or delivery, expected cadence and maximum acceptable delay.
  • Record counts and changes in missing or invalid fields compared with the previous accepted run.
  • Failure category, affected scope and next action; keep credentials and personal data out of shared logs.
  • Named business and technical owners, escalation route and a tested pause or revocation procedure.

6. Connection verification protocols

Before moving from an agreed schema to active execution, run through the three-phase bounded verification protocol: pre-flight transport handshake, payload completeness audit, and post-ingest reconciliation.

  • Pre-flight handshake: Verify TLS 1.3 encryption boundary, bearer token or HMAC signature validity, and endpoint responsiveness with a single-record ping before initiating batch extract.
  • Payload completeness check: Compare batch manifest count with landed row count. Verify checksums and ensure zero silent truncation across long description or attribute fields.
  • Identity & grain contract: Reconcile unique primary keys against the agreed row grain. Reject or quarantine batches containing colliding product_key or variant_key records.
  • Null-tolerance threshold: Enforce strict null-rate bounds (<0.1% for core price, currency, and availability attributes; unmapped fields must remain explicit null, never zero).
  • Idempotency validation: Confirm replay safety by processing a sample payload twice; verify landed state results in zero duplicate rows or phantom revisions.
VP-01 · Phase 1: Connection VerificationAcceptance Gate

Pre-flight Transport Handshake

Verify transport isolation, TLS cipher boundary, and credential scope before initiating batch transport.

  • TLS 1.3 encryption verified with valid SAN hostname certificate
  • OAuth2 token / API key verified with read-only principal boundary
  • Single-row probe handshake returns HTTP 200 within 500ms timeout window
  • Source rate-limit governor acknowledged; backoff schedule confirmed

Fallback: Halt connection initialization; raise configuration ticket without retry storm.

VP-02 · Phase 2: Transport & Schema ConformanceAcceptance Gate

Payload Completeness & Lineage Audit

Reconcile transmitted payload volume and schema structure against the declared source manifest.

  • Transmitted row count matches source manifest checksum within 0% variance
  • No silent string truncation across description and attribute payloads
  • Mandatory identifier keys (product_key, variant_key) present and non-null
  • Timestamp fields normalized to ISO 8601 UTC with verified timezone offset

Fallback: Divert inconsistent batch to quarantined staging bucket; preserve raw payload for inspection.

VP-03 · Phase 3: Data Integrity GateAcceptance Gate

Post-Ingest Reconciliation & Idempotency

Verify that landed entities reconcile with historical baselines and replay safely without mutation.

  • Duplicate transmission produces zero new rows and identical landed checksum
  • Null-rate across required commercial fields (price, currency, status) remains below 0.1%
  • Catalog entity keys map 1:1 to canonical retailer identifiers without orphan variants
  • Explicit distinction preserved between unavailable stock and unobserved inventory

Fallback: Freeze downstream model ingestion; notify merchandising and technical owners.

7. Data-flow health checkpoints & circuit breakers

Operational connections require agreed health checkpoints that trigger fail-stop circuit breakers rather than corrupt downstream retail decision models.

  • Freshness SLA checkpoint: Define maximum tolerable ingest delay (e.g., 6h for public catalog observations, 1h for order events). Exceeding SLA raises an amber warning and freezes downstream forecast weights.
  • Schema drift circuit breaker: Any unexpected column insertion, type mismatch, or breaking field renaming immediately diverts incoming payloads into an isolated dead-letter queue (DLQ).
  • Price anomaly gate: Abrupt catalog-wide price shifts (>25% median change in a single sync) trigger a review hold pending explicit merchandising sign-off.
  • Credential revocation protocol: On auth failure (HTTP 401/403), connector execution pauses immediately; automatic retries are capped at 3 with exponential backoff to avoid vendor account lockout.
  • Human escalation pathway: Assign named technical and merchandising reviewers responsible for investigating circuit-breaker trips and authorising resume operations.
HP-01

Freshness SLA Checkpoint

Metric
Ingestion delay relative to source generation timestamp
Threshold
Max 6 hours for catalog extracts; max 1 hour for order/inventory feeds
Response
Tag dataset as stale, log SLA breach incident, freeze automated decision weights
Owner
Technical Data Operations
HP-02

Null-Rate Boundary Circuit Breaker

Metric
Percentage of null or missing values across mandatory commercial fields
Threshold
> 0.5% missing prices or > 0.1% missing SKU keys in batch
Response
Trip pipeline circuit breaker, stop landed table writeback, alert data engineer
Owner
Data Quality Lead
HP-03

Schema Drift & Column Evolution Gate

Metric
Field name, data type, or nullability changes against registered contract
Threshold
Zero tolerance for unannounced removals or type conversions
Response
Quarantine batch into Dead-Letter Queue (DLQ), emit schema drift notification
Owner
Integration Architect
HP-04

Commercial Price Anomaly Detector

Metric
Median price shift across overlapping product catalog records
Threshold
Aggregate price shift exceeding 25% across > 100 items in a single update
Response
Require manual merchandising sign-off before propagating into pricing engine
Owner
Merchandising Lead

Troubleshooting a test

Keep the failing scope small enough to reproduce. Provide a source name, approximate time and a sanitised description to support.

  • No rows: check the agreed date window, market, filters and source permissions before assuming an empty catalog.
  • Partial results: review reported completeness, request failures and source limits; do not relabel an observed count as a total.
  • Mismatched products: check variant keys, bundles, pack sizes and locale-specific records.
  • Stale output: compare source timestamps with delivery time and the agreed schedule.
  • Rejected access or failed delivery: ask the authorised source owner to check permissions and destination configuration. Do not paste credentials into a ticket.

Source & cost · public reference

USITC HTS Online reference

A bounded public record for a U.S. tariff-schedule lookup. It keeps the observed source, date and jurisdiction visible without turning a public reference into a classification or duty decision.

Jurisdiction
United States · U.S. Harmonized Tariff Schedule
Observed revision
2026 HTS Revision 21 · archive date 2026-10-09
Observed search
6109
Provenance
Official USITC public search and archive, observed in a public browser session; CBP CROSS is shown as a separate adjacent ruling source.

Evidence views

Showing the public USITC search evidence.

Before you use this reference

Confirm the product, country and jurisdiction, and current tariff treatment with your responsible customs or trade-compliance team. This page records a public source observation; it is not a product classification or duty calculation.

Use this as a reference only; no product classification, duty calculation or legal determination is provided here.