ShopTools AI selects coupon offers from a catalog. Valid JSON alone does not make a record suitable for display or testing: a code field may contain a product SKU, while a supposed store address may lead to a tracker.
The contract below is a design model for this kind of integration. It defines useful data requirements; it does not claim to document every field in the current ShopTools API.
Define meaning as well as type
For each field, specify acceptable values and what happens when validation fails. Distinguish a failed download from a malformed record. One bad offer should not silently change how the rest are interpreted.
- Offer type: a promo code, a deal without a code or an offer tied to a specific product.
- Code: a string intended for submission to the merchant, not a SKU or a placeholder saying no code is required.
- Region and dates: known values or explicit uncertainty, without invented eligibility.
- Destination: the verified merchant domain, separate from the affiliate link.
Separate URL roles and validation responsibilities
A server adapter is a useful place for feed-specific extraction and normalization. The client still needs its own checks: its release and cached records may not match the server's current assumptions.
A product URL identifies an item, a merchant domain establishes store context, and an affiliate URL describes a route. Missing data is not a reason to substitute one of these fields for another.
If only the tracking host is known, the merchant destination remains unknown. An incomplete record belongs in a data-quality workflow rather than behind an enabled button promising a coupon check.
Identity is not the same as deduplication
Keep the upstream offer ID within the source's namespace. A merchant name or advertiser ID alone cannot distinguish all of its promotions. Renaming a title should not sever the record's history.
Deduplication needs a separately defined key. A code string alone is insufficient because different merchants can use it. Country, campaign and product restrictions may also mean two similar records must remain separate.
When a fallback key hashes normalized fields, document those fields and how collisions are handled. Hashing a short coupon code does not guarantee anonymity and does not create proof of payment.
A click identifier belongs to an event; an offer ID belongs to a record. Attempts can be linked to that record without implying a sale. Retention periods and access to the resulting data need their own decisions.
Exercise the contract with invalid inputs
- Send an unexpected container instead of an array and check that its format is not guessed.
- Test placeholder codes, SKUs, unknown countries and contradictory dates.
- Compare identical codes from different merchants and separate campaigns from one merchant.
- Test schema upgrades, incomplete exports and repeated processing of the same record.
An export timestamp describes the data snapshot, not a successful test of every coupon. A fully valid offer is still only a candidate: the merchant determines eligibility and the final price.
By the ShopTools AI editorial team.
Some ShopTools links are affiliate links. ShopTools may earn a commission on a qualifying purchase confirmed by the retailer; a click alone does not guarantee a commission.
Prepared with AI assistance. Product descriptions were checked against ShopTools code and interface; this is not a report of tests at every store.