An offer payload is the populated data instance that represents one commercial offer in an API response.
The canonical Offer contains stable and per-dispatch identity, offer and merchant data, an executable action, and one or more Goals that identify billable events and their pricing. The payload is one Offer object, distinct from both the response envelope that contains it and the Offer schema that defines its structure.
From response envelope to Offer object
The hierarchy separates request-level response data from the fields that belong to one Offer.
Carries request-level metadata and the Offer collection.
Contains zero or more populated Offer objects; an empty collection is still a valid response.
Separates the inventory Offer from this served instance.
offer_info and entity describe what is offered and by whom.
Defines the supported next step. The integration must preserve the returned action URL for the documented handoff.
Identify the downstream events that can qualify for billing and define their CPA or CPS pricing.
- The executable action is defined by the applicable delivery contract. Its returned URL must not be replaced with a different URL.
- Integrations should validate each returned Offer against their current documented contract.
Offer payload vs Offer schema
The Offer schema is the versioned contract that defines fields, types, required properties, and validation rules. An offer payload is one concrete object populated according to that schema and returned for a particular query. See the Structured offer schema definition.
Example in practice
A project-management software Offer payload may include a stable offer identity, a per-dispatch identifier, structured offer and merchant data, an executable action, and one or more billable Goals. For the complete hosted response shape, see the Offer Query field reference.
Common questions about offer payload
What is the difference between offer_id and offer_instance_id?
offer_id identifies the stable inventory offer, while offer_instance_id identifies this particular dispatch of that offer. The two identity levels are not interchangeable.
What happens when an AON response contains an empty offers array?
The query succeeded but produced no suitable offers. An empty offers array is a valid no-match response; it does not contain an Offer payload for the publisher to render.
Should a publisher validate the returned Offer?
Yes. The complete Offer must be validated against the contract documented for that integration before the product uses or presents it.
What should an app do if a required field is missing from a returned offer?
Treat the Offer as invalid for the selected contract rather than silently inventing or reusing a value. Log the validation failure using your integration's supported diagnostics and avoid presenting an offer whose required action, identity, disclosure, or commercial meaning cannot be interpreted safely.
Which URL should an AON publisher use?
The publisher should use the returned action URL unchanged, following the tracking and handoff instructions for its integration.
Does an AON Offer payload confirm final price and availability?
No. It represents discovery-time offer data. The merchant or checkout system must confirm current price, availability, eligibility, and binding terms.
Sources
- AON Offer Query APIAON documentation
- AgentOffer ProtocolAON documentation
- Schema.org OfferRelated standard
- OpenAPI SpecificationRelated standard
- HTTP Semantics RFC 9110Related standard