US Brand Offer Evidence Normalizer

Turn supplied US brand ad, offer, coupon, and landing-page evidence into closed, deterministic JSON for research, marketing operations, and automated workflows. Send inline evidence rows or one authorized Apify Dataset. The Actor validates source proof and terms; it does not browse, render pages, use proxies, call other Actors, or infer ownership from a name, ticker, slug, or free text.

What you send

Use exactly one source: rows or datasetId.

Field	Required	What it means
schemaVersion	yes	1.0 for this input contract.
requestId	yes	A bounded correlation ID. Reusing it in a later run does not deduplicate or combine purchases.
rows	one source	One to 100 closed evidence rows supplied in the request.
datasetId	one source	One Apify Dataset selected with READ permission. V1 reads at most 10 rows and probes one additional row to detect truncation.
options	no	labels: off by default, or caller-funded BYOK labels with an explicit model. maxItems is 1 to 100.
openrouterApiKey	BYOK only	Your own OpenRouter key when labels is byok. It is never returned or persisted.

This is a complete synthetic inline request that can be pasted into the input editor. It uses a first-party-domain proof so the row is eligible for a result.

{
  "schemaVersion": "1.0",
  "requestId": "offer-normalize-demo-001",
  "rows": [
    {
      "entity": {
        "entityId": "brand:demo-outfitters",
        "brandName": "Demo Outfitters",
        "legalName": null,
        "domain": "demo.example",
        "ticker": null,
        "aliases": [],
        "country": "US",
        "sourceEntityIds": ["prefill:demo-outfitters"]
      },
      "evidence": {
        "evidenceType": "landing_page",
        "sourceName": "synthetic-example",
        "sourceRecordId": "offer-001",
        "sourceUrl": "https://demo.example/offers/spring",
        "observedAt": "2026-08-04T08:00:00Z",
        "rawTitle": "Spring offer",
        "rawTermsText": "20% off orders $50+ with code SPRING20. Ends 2026-09-30.",
        "terms": {
          "offerKind": "percent_off",
          "percentOff": 20,
          "minPurchaseAmount": {"value": 50, "currency": "USD"},
          "couponCode": "SPRING20",
          "endAt": "2026-09-30T23:59:59Z"
        },
        "entityAttribution": {
          "status": "verified_by_source",
          "proofType": "first_party_domain",
          "proofValue": "demo.example",
          "sourceEntityId": "prefill:demo-outfitters",
          "proofUrl": "https://demo.example/",
          "proofDomain": "demo.example",
          "merchantId": null,
          "adAccountId": null,
          "officialSourceId": null
        },
        "additionalUrls": []
      }
    }
  ],
  "options": {"labels": "off", "maxItems": 100}
}

For Dataset input, omit rows and send datasetId instead. The Dataset must be authorized for this run; arbitrary URLs, pagination, hosts, tokens, proxy settings, and source credentials are not accepted.

What you get

Each fully verified, non-conflicting offer becomes one paid Dataset item. The row preserves source evidence and includes normalized terms, a deterministic offerId, offerKind, dedupeKey, attribution proof, conflict information, and needsReview. Ambiguous, conflicting, rejected, or unavailable evidence is reported in the non-paid OUTPUT summary and is not emitted as a paid fact.

Every run also writes a compact closed OUTPUT record. A successful run has the following shape; the Dataset item contains the detailed evidence row.

{
  "schemaVersion": "1.0",
  "requestId": "offer-normalize-demo-001",
  "requestDigest": "sha256:2d5173a6d8d0c18d2d8aa0de1dd7afcdb4f35f7c70b2e7d44d5ce0f9279f9887",
  "status": "found",
  "resultFound": true,
  "counts": {"input": 1, "deduped": 1, "verified": 1, "eligible": 1, "rejected": 0},
  "delivery": {"confirmedDatasetWrites": 1, "confirmedResultEvents": 1, "confirmedCharges": 1, "unknownOperations": 0, "lastReceiptId": "example-receipt"},
  "source": {"kind": "inline", "datasetId": null},
  "limits": {"maxItems": 100, "truncated": false},
  "analysisStatus": "skipped_no_key",
  "analysisModel": null,
  "usage": null,
  "sourceStats": {"datasetRequests": 0, "decodedBytes": 0, "elapsedMs": 12},
  "errors": []
}

The machine flow is: submit one closed JSON request, inspect OUTPUT, then consume only Dataset items with verified attribution and complete, non-conflicting normalization. Terminal statuses include found, no_match, invalid_input, dataset_not_found, dataset_forbidden, dataset_truncated, source_unavailable, partial, budget_stopped, pricing_misconfigured, and unknown_delivery.

API example

After the Actor is available in your Apify account, call it with the same JSON object through the standard Apify API:

curl -sS -X POST \
  'https://api.apify.com/v2/acts/zinin~us-brand-offer-evidence-normalizer/runs?waitForFinish=60' \
  -H 'Authorization: Bearer YOUR_APIFY_TOKEN' \
  -H 'Content-Type: application/json' \
  --data @input.json

An Apify client or an agent can use the same closed input and output contracts. The request ID is correlation metadata only: each separate Actor run is a new purchase, and V1 has no cross-run replay, ledger, or idempotency state.

Verification and limits

• Attribution requires source-specific proof, a source entity ID, original source fields, and exact comparable domain or identity agreement.
• Structured terms must agree with raw terms. A conflict is retained and is not billed as a verified result.
• Inline input is limited to 100 rows; a Dataset source is limited to 10 rows.
• Canonical serialized input is limited to 512 KiB; decoded Dataset data is limited to 2 MiB; row, URL, evidence-link, and text limits are enforced before delivery.
• One bounded BYOK request can label at most 10 rows. There is no model fallback, no browser, no login, no arbitrary URL fetch, and no cross-run state.
• A delivered result is charged only after the Actor confirms the exact platform event counter delta. Uncertain delivery stops remaining work and is never silently retried.

Pricing and discounts

Apify resolves pricing from the caller's subscription tier before the run and supplies the matching event-price pair to the SDK. The contract charges that tier's run-start event plus one result-found event for each fully delivered verified, non-conflicting row. There is no input-row, Dataset-item, rejection, deduplication, or BYOK charge.

Apify subscription tier	Discount	Run start	result-found
FREE	0%	$0.00500	$0.01000
BRONZE	5%	$0.00475	$0.00950
SILVER	10%	$0.00450	$0.00900
GOLD	15%	$0.00425	$0.00850
PLATINUM	18%	$0.00410	$0.00820
DIAMOND	20%	$0.00400	$0.00800

Only these six exact start/result pairs are accepted. Mixed pairs, missing or extra event names, non-finite values, and any apify-default-dataset-item event fail closed as pricing_misconfigured. The result event is emitted only with the corresponding delivered row.

The per-run maxItems option only caps how many rows this run may return. It is independent of the caller's subscription tier and never selects a price tier.

Bring your own key (BYOK)

Set options.labels to byok, provide an explicit OpenRouter model, and supply your own openrouterApiKey when you want optional offerCategory and audienceLabel values. Your key pays the model provider directly. The key is redacted from logs, output, persisted state, and request digests. Provider errors, timeouts, malformed responses, and bounded limits leave the deterministic offer facts, proof, deduplication, and billing eligibility unchanged. With labels: off, no model or key is used.

Machine and agent usage

The Actor is designed as a small machine-to-machine processor: closed JSON schemas, deterministic identifiers, bounded execution, explicit terminal statuses, and a one-row result billing unit make it suitable for scheduled jobs, MCP wrappers, and autonomous research or marketing agents. The metadata is machine-first, but this package does not promise a separate MCP server, x402 endpoint, payment facilitator, or catalog registration.

Related Actors

Actor	How it fits	Availability in this series
Shopify Store Intelligence	Add public Shopify store and catalog signals before normalizing a merchant's supplied offer evidence.	Public
Shopify Price Change Monitor	Pair offer evidence with observed store-level price and catalog changes for competitor monitoring.	Public
Structured Extract	Extract typed page fields and JSON-LD from a landing page before passing its evidence to this Actor.	Public
Intent Signal Aggregator	Add public hiring and news intent context when prioritizing normalized brand offers.	Public
Social Preview Checker	Check the social metadata of a landing page whose offer evidence is being evaluated.	Public

These links are public neighboring tools, not required sibling calls. A downstream workflow may join their output with this Actor's closed offer facts without assuming that any Actor runs another Actor internally.

Store text

SEO title: US Brand Offer Evidence Normalizer | Verified Offer Evidence

Meta description: Normalize supplied US brand ads, offers, coupons, and landing-page evidence into deterministic, attribution-aware JSON without browsing or sibling Actor calls.

Keywords: offer evidence normalization, coupon normalization, brand offer extraction, verified attribution, Apify Dataset processor, BYOK labels