SEOAdvisors.com
Back to Home

Modeling Multistep Actions in Schema: Offers, Bookings, Confirmations & Refunds

Creative illustration of train tracks on wooden blocks, depicting decision making concepts.

Why model multistep actions for AI agents?

AI assistants and agentic search experiences expect machine-readable signals for each step of a commercial flow: the initial offer, the reservation/booking, the post‑purchase order/confirmation, and any subsequent refunds or returns. Using schema.org types and properties to represent those states makes it possible for assistants to verify availability, identify confirmations, and trigger follow-up actions (e.g., check‑in, cancellation, refund).

This article gives practical modelling patterns, JSON‑LD examples, and an implementation checklist to help publishers make their offers and transactional flows agent‑ready.

Pattern 1 — Offers and pre‑transaction signals (what to publish on listing pages)

Pre‑transaction pages should expose Offer (and where needed AggregateOffer) nested under the product/service. Key properties: price, priceCurrency, availability, url, and any hasMerchantReturnPolicy or itemOffered pointers. Using full schema.org URLs for controlled values (e.g., https://schema.org/InStock) improves interoperability.

Minimal JSON‑LD example (Offer inside a Product):

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Acme Concert Ticket",
  "offers": {
    "@type": "Offer",
    "price": "49.00",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://example.com/tickets/123"
  }
}

Notes:

  • Keep IDs stable (use canonical product or offer URLs) so agents can correlate offers with later confirmations.
  • If you expose multiple variants or dynamic pricing, consider multiple Offer objects or PriceSpecification substructures.

Pattern 2 — Reservations and bookings (confirmation pages and emails)

Use Reservation (and its specializations like LodgingReservation, FlightReservation, FoodEstablishmentReservation) to represent an actual booked item. Important properties: reservationId, reservationStatus, reservationFor, underName, bookingTime, and totalPrice. Reservations are for confirmed/actual bookings (not pre‑transaction offers).

Example JSON‑LD (reservation confirmation):

{
  "@context": "https://schema.org",
  "@type": "LodgingReservation",
  "reservationId": "RES-123456",
  "reservationStatus": "https://schema.org/ReservationConfirmed",
  "reservationFor": {
    "@type": "LodgingBusiness",
    "name": "Seaside Hotel"
  },
  "underName": {
    "@type": "Person",
    "name": "Alex Customer"
  },
  "totalPrice": "299.00",
  "priceCurrency": "USD",
  "bookingTime": "2026-03-01T14:35:00-08:00"
}

Design tips:

  • Include a machine‑readable reservationId and reservationStatus so agents can assert confirmation or cancellation.
  • If your booking system supports pending holds, use ReservationHold or ReservationStatusType values to signal temporary states.

Pattern 3 — Orders, confirmations and linking offers → acceptedOffer → refunds

Use Order to model a receipt/confirmation containing one or more accepted offers. The acceptedOffer and referencesOrder properties are especially useful to tie a prior Offer to the actual Order that resulted from accepting it. An order can carry confirmationNumber, payment and billing details, and paymentStatus.

Example Order JSON‑LD linking an accepted offer:

{
  "@context": "https://schema.org",
  "@type": "Order",
  "orderNumber": "ORDER-7890",
  "acceptedOffer": [
    {
      "@type": "Offer",
      "name": "Acme Concert Ticket",
      "price": "49.00",
      "priceCurrency": "USD"
    }
  ],
  "confirmationNumber": "CONF-5555",
  "orderDate": "2026-03-02T10:12:00-08:00",
  "paymentStatus": "https://schema.org/PaymentComplete"
}

Linking guidance:

  • Keep consistent identifiers: the url or an explicit @id for the original offer/product helps agents reconcile pre‑transaction pages with confirmations.
  • When an order references multiple offers (bundles), use the acceptedOffer array and optionally referencesOrder for nested orders or fulfillment steps.

Pattern 4 — Returns and refunds (policy + refund types)

Model return and refund policies using MerchantReturnPolicy and the hasMerchantReturnPolicy property on Offer, Product or Organization. Use the refundType property with values from RefundTypeEnumeration (e.g., FullRefund, StoreCreditRefund) to state refund behavior explicitly. Google Search Central also documents return‑policy structured data that maps to these schema.org constructs.

Example MerchantReturnPolicy snippet inside an Offer:

{
  "@context": "https://schema.org",
  "@type": "Offer",
  "price": "120.00",
  "priceCurrency": "USD",
  "hasMerchantReturnPolicy": {
    "@type": "MerchantReturnPolicy",
    "merchantReturnLink": "https://example.com/returns",
    "refundType": "https://schema.org/FullRefund",
    "merchantReturnDays": 30
  }
}

Practical notes:

  • Providing a nested MerchantReturnPolicy reduces ambiguity for agents and marketplaces that check returnability before completing an action.
  • Keep human‑readable policy pages linked via merchantReturnLink for full legal text; structured fields are for machine decisioning.

Agent integration, email highlights and platform hooks

To maximize the likelihood assistants will surface confirmations and actions, follow platform-specific guidelines: Gmail Highlights supports reservation and order types (hotel, flight, restaurant, order receipts) when markup follows Google's email markup specs. For enabling bookings in Maps/Search you may integrate with the Maps Booking API or specific Assistant/Actions integrations — both require structured, stable payloads and callback endpoints for leases, cancellations and notifications. Including the schema.org reservation/order/offer markup on both the confirmation page and in the confirmation email improves discoverability and actionability by agents.

Implementation checklist & troubleshooting

  • Stable identifiers: use consistent @id or canonical URLs across offer, reservation and order artifacts.
  • Clear state properties: publish reservationStatus, paymentStatus, and refundType so assistants can reason about next steps.
  • Return policy markup: include hasMerchantReturnPolicy / MerchantReturnPolicy with refundType and merchantReturnDays.
  • Email + page parity: include the same machine‑readable confirmation in the web confirmation page and the transactional email (Gmail Highlights supports this pattern).
  • Test & monitor: validate with schema validators and platform test tools; monitor Search Console / Merchant Center for new warnings (e.g., missing nested return policy fields) and iterate.

If you run into platform warnings about nested properties (for example, missing hasMerchantReturnPolicy), verify that your JSON‑LD nests the policy as a typed object rather than a plain URL or text; many platforms now expect the structured object.

Conclusion: Model the end‑to‑end flow as a chain of typed objects (Offer → Reservation/Booking → Order/Confirmation → MerchantReturnPolicy/Refund) with stable IDs and explicit state properties. This makes flows agent‑readable and reduces friction when assistants attempt to complete or manage transactions on behalf of users.

Related Articles