{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/placementapi-com/json-schema/placementapi-com-basket-compare-response-schema.json",
  "title": "BasketCompareResponse",
  "description": "The full comparison. Fields are added, never renamed. A failure is never returned as an empty or zero-savings body.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/placementapi-com-comparison-api-openapi.yml#/components/schemas/BasketCompareResponse",
  "type": "object",
  "required": [
    "version",
    "lines",
    "summary",
    "calculated_at"
  ],
  "properties": {
    "version": {
      "type": "integer",
      "const": 1
    },
    "lines": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/BasketCompareLine"
      },
      "description": "One result per input line, in input order."
    },
    "summary": {
      "$ref": "#/$defs/BasketCompareSummary"
    },
    "calculated_at": {
      "type": "string",
      "format": "date-time",
      "description": "When this comparison was computed."
    }
  },
  "$defs": {
    "BasketCompareCandidate": {
      "type": "object",
      "description": "The cheapest term-compatible live named offer for the line, priced all-in. A catalogue-price estimate as observed (see `observed_at`), never a vendor-confirmed price or guaranteed quote. Supplier identity is intentionally not exposed anywhere in this API. You are buying from us; which upstream marketplace fulfils a placement is not something you need or can act on.",
      "properties": {
        "offer_id": {
          "type": "string",
          "description": "The public, pseudonymised offer id (the same form the pricing resolver accepts). The internal supplier-scoped id is never returned."
        },
        "placement_type": {
          "type": "string",
          "description": "The offer's placement type; it equals the captured type, since only the same type is compared."
        },
        "unit_credits": {
          "type": "integer",
          "description": "Credits. 1 credit = 1 US cent. ALL-IN per placement: the placement price plus the content fee the resolved plan carries. This is the figure the buyer-credit total is built from."
        },
        "content_mode": {
          "type": "string",
          "enum": [
            "publisher",
            "service",
            "supplied"
          ],
          "description": "How the resolved plan sources the article: the publisher writes, we arrange a paid service, or the buyer supplies copy. (`papi_written` is reported here as `service`.)"
        },
        "content_tier": {
          "type": [
            "string",
            "null"
          ],
          "description": "The paid writing tier by name when `content_mode` is `service`; null otherwise."
        },
        "observed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the catalogue row was observed. The age of the price travels with it: this is a scrape, not a live quote, so an aged figure is quoted as observed rather than presented as current."
        },
        "link_attribute": {
          "type": "string",
          "description": "The offer's known link attribute, or `unknown` when the listing did not record one. A `dofollow: false` listing is `nofollow` and nothing more; `sponsored` is never inferred."
        },
        "writing": {
          "type": "string",
          "enum": [
            "included",
            "supplied",
            "unknown"
          ],
          "description": "The writing term the resolved plan actually delivers; `unknown` for a link-only placement, where writing does not apply."
        }
      }
    },
    "BasketCompareLine": {
      "type": "object",
      "required": [
        "id",
        "domain",
        "status",
        "candidate",
        "reasons",
        "observed_total_usd_minor",
        "candidate_total_credits",
        "estimated_savings_usd_minor"
      ],
      "description": "One compared line. A `comparable` line is an exact same-domain + same-type + known-term match; an `alternative` keeps a candidate that is shown but not claimed as the same placement; `unmatched` and `unsupported` carry no candidate.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The caller's line id, echoed."
        },
        "domain": {
          "type": "string",
          "description": "The captured domain, echoed as given."
        },
        "status": {
          "type": "string",
          "enum": [
            "comparable",
            "alternative",
            "unmatched",
            "unsupported"
          ],
          "description": "`comparable`: exact match and savings may be claimed. `alternative`: a candidate is shown but a term differs, the site is restricted, the captured price is non-USD or not all-in, or the pair overflowed — no saving is claimed. `unmatched`: no live named offer on that exact domain and type (never a silent substitution). `unsupported`: the placement type is not compared."
        },
        "candidate": {
          "oneOf": [
            {
              "$ref": "#/$defs/BasketCompareCandidate"
            },
            {
              "type": "null"
            }
          ],
          "description": "The chosen candidate, or null when the line is unmatched or unsupported (and null on an overflowed pair, where no cheapest is claimed)."
        },
        "reasons": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Human-readable explanation for the status and saving, including any overflow, restricted-flag or term-mismatch note. Not part of a machine contract."
        },
        "observed_total_usd_minor": {
          "type": [
            "integer",
            "null"
          ],
          "description": "The captured unit price times the quantity, in USD minor units, or null when no unambiguous USD price was captured. Shown even for ineligible lines so the buyer sees their own figure."
        },
        "candidate_total_credits": {
          "type": [
            "integer",
            "null"
          ],
          "description": "All-in candidate cost for the line's full quantity, in credits (1 credit = 1 US cent): `candidate.unit_credits` × quantity. Null when no candidate was priced."
        },
        "estimated_savings_usd_minor": {
          "type": [
            "integer",
            "null"
          ],
          "description": "`observed_total_usd_minor` minus `candidate_total_credits`, present only for a `comparable` line. Null for every alternative, unmatched or unsupported line, so a shown candidate never carries a saving it did not earn. A negative value is retained (the candidate costs more), not clamped."
        }
      }
    },
    "BasketCompareSummary": {
      "type": "object",
      "required": [
        "line_count",
        "comparable_line_count",
        "source_total_usd_minor",
        "matched_source_total_usd_minor",
        "matched_candidate_total_credits",
        "matched_estimated_savings_usd_minor",
        "whole_basket_estimated_savings_usd_minor"
      ],
      "description": "Basket-level totals. `matched_*` fields cover the comparable lines only; the whole-basket saving additionally requires every line to be comparable. A matched subset is never presented as a full-basket saving.",
      "properties": {
        "line_count": {
          "type": "integer",
          "description": "Lines in the request."
        },
        "comparable_line_count": {
          "type": "integer",
          "description": "Lines whose status is `comparable`."
        },
        "source_total_usd_minor": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Sum of every line's captured USD total, or null when any line had no unambiguous USD price. Never a converted or estimated total."
        },
        "matched_source_total_usd_minor": {
          "type": "integer",
          "description": "Sum of the captured totals of the comparable lines only."
        },
        "matched_candidate_total_credits": {
          "type": "integer",
          "description": "Sum of the all-in candidate totals of the comparable lines only, in credits."
        },
        "matched_estimated_savings_usd_minor": {
          "type": "integer",
          "description": "Savings on the comparable lines only. The cart adjustment is NOT folded in here."
        },
        "whole_basket_estimated_savings_usd_minor": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Matched savings plus `basket_adjustment_usd_minor`, or null unless every line is comparable. Null is why a partial basket never shows a whole-basket figure."
        }
      }
    }
  }
}