AgentChannel

object type

An AgentChannel — the merchant’s CONTROLS over the agentic-commerce channel: exactly ONE record per Organization that says WHAT an AI shopping agent may sell over the open Universal Commerce Protocol and HOW — the selling location (prices · stock · tax origin), the listed Collections (EMPTY = nothing listed), an optional agent price plane (a PriceList), discount codes on/off, a checkout cap, the fulfillment methods + flat-rate shipping cards + ship-to countries + pickup locations, the buyer facts required, the pre-approved agent platforms (EMPTY = every platform refused), the buyer-consent defaults, the return/warranty policy texts, the checkout session TTL, and the engine-minted ES256 signing keys (the PUBLIC halves — the private halves live in the credential store, never on the wire). Lifecycle draft → live → paused → live | doomed: publish and resume run the completeness rule record-aware (the channel must be able to sell); pause withholds the channel (agents read unavailable + Retry-After); a LIVE channel never dooms in one step (pause first); doom releases the one-per-org marker so the organization may start over. The protocol doors (the profile, the catalog, the checkout — onward) READ this record; the adapter adds no business rule of its own. Payment handlers are NEVER typed here — the profile derives them from the organization’s connected-account facts.

Fields

Field	Type	Notes
`id`	ID `ID!`	The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it.
`sysId`	String `String!`	The group-scoped human-facing system id (AG-…).
`type`	String `String!`	The kind of record — always `AgentChannel` here.
`caption`	String `String!`	The record’s display name — what people see it called.
`status`	String `String!`	The FSM state: draft \| live \| paused \| doomed.
`parentId`	ID `ID!`	The parent Organization; rootId = the org group; parentId!== rootId always.
`rootId`	ID `ID!`	The org-group family root.
`createdAt`	String `String!`	When the record was created, as a UTC timestamp.
`updatedAt`	String `String!`	When the record last changed, as a UTC timestamp.
`revisionNum`	Int `Int!`	How many times this record has been edited; the first save is 0.
`revision`	ID `ID!`	The OCC revision token — supply it on every mutation of this record; rotates on every write.
`refCaptions`	RefCaption `[RefCaption!]!`	The server-composed captions of this record's declared references (the referenced-caption rule) — one row per referenced id; see RefCaption.
`logicalFacilityId`	ID `ID!`	WHERE — the selling location: the LogicalFacility whose stock, prices and tax origin the channel sells from; in-tenant + ACTIVE at every write and at publish/resume.
`pickupLogicalFacilityIds`	ID `[ID!]!`	WHERE — the business locations offered for pickup (0..16, distinct, each in-tenant + ACTIVE); REQUIRED non-empty when a pickup method is offered; edits replace the set WHOLESALE.
`shipToCountries`	String `[String!]!`	WHERE — the ISO 3166-1 alpha-2 countries (UPPERCASE) the channel ships to (0..64, distinct); EMPTY = no shipping (an address outside answers address_undeliverable); REQUIRED non-empty when ship is offered; replaces WHOLESALE.
`collectionIds`	ID `[ID!]!`	WHAT — the listed Collections: the ONLY listing lever — EMPTY = nothing is listed (publish refuses); replaces WHOLESALE. A non-doomed channel blocks a listed collection’s doom.
`divisionId`	ID	WHAT — an optional CHANNEL-type Division framing the agent channel; null = unframed.
`showStockLevels`	Boolean `Boolean!`	WHAT — whether agents read stock FIGURES (true) or only in/out of stock (false — the strict default).
`excludedVariantIds`	ID `[ID!]!`	WHAT — the hand veto list: Variants never listed whatever their Collections say (0..200, distinct, each in-tenant); replaces WHOLESALE.
`priceListId`	ID	PRICES — an optional PriceList as the agent price plane (in-tenant + ACTIVE + selected for the owning organization + unscoped — a customer-scoped contract list refuses); null = the standing sale prices apply. Explicit prices, never blanket percentages.
`allowDiscountCodes`	Boolean `Boolean!`	PRICES — whether agents may present discount codes (the UCP discount extension is advertised only when true; the engine’s own coupon gates still apply). Strict default false.
`maxCheckoutTotalMinor`	Int	PRICES — an optional cap on a single agent checkout in the organization’s currency minor units (1..2147483647); a checkout over it answers eligibility_invalid; null = no cap.
`fulfillmentMethods`	AgentChannelFulfillmentMethod `[AgentChannelFulfillmentMethod!]!`	FULFILLMENT — the offered methods (ship · pickup_instore · pickup_curbside; distinct); EMPTY = the channel cannot complete a checkout (publish refuses).
`shippingOptions`	AgentChannelShippingOption `[AgentChannelShippingOption!]!`	FULFILLMENT — the flat-rate shipping cards (0..16, ids unique): the merchant’s own words and prices; every card’s countries must be ship-to countries; REQUIRED non-empty when ship is offered; replaces WHOLESALE.
`handlingDays`	Int `Int!`	FULFILLMENT — handling days before a shipment leaves (0..30; default 0).
`requireBuyerEmail`	Boolean `Boolean!`	PAYMENTS — the buyer must give an email before completing (strict default true).
`requireBuyerPhone`	Boolean `Boolean!`	PAYMENTS — the buyer must give a phone number before completing (default false).
`allowedPlatforms`	AgentChannelPlatform `[AgentChannelPlatform!]!`	PLATFORMS — the pre-approved agent platform registry (0..16, profile URLs unique): a platform is verified against ITS profile’s signing keys and refused (profile_not_trusted) unless listed and active — EMPTY = every platform refused; publish requires at least one active; replaces WHOLESALE.
`rateClass`	AgentChannelRateClass `AgentChannelRateClass!`	PLATFORMS — the canned request-rate class granted to platforms (low · normal · high; default normal).
`consentDefaults`	AgentChannelConsentDefaults `AgentChannelConsentDefaults!`	CONSENT — the UCP buyer_consent defaults the channel proposes (marketing · analytics · preferences · sale_or_sharing); strict default all false.
`returnPolicy`	String	POLICIES — the return policy text (at most 2000 characters), published in the profile’s policies; null = none published.
`warrantyPolicy`	String	POLICIES — the warranty policy text (at most 2000 characters), published in the profile’s policies; null = none published.
`checkoutTtlMinutes`	Int `Int!`	SESSION — how long an agent checkout stays open (15..1440 minutes; default 360 — the spec’s 6 h); the draft order’s validUntil derives from it.
`identityLinking`	Boolean `Boolean!`	SESSION — whether buyer account linking (the UCP identity_linking capability) is advertised: the shop host serves its own OAuth 2.0 endpoints and buyers sign in on the shop’s address to link an assistant; default false.
`requireLinkedBuyer`	Boolean `Boolean!`	SESSION: whether every checkout and order operation requires a LINKED buyer (the standard’s members-only posture — an unlinked call answers 401 identity_required); default false = guest checkout stands.
`signingKeys`	AgentChannelSigningKey `[AgentChannelSigningKey!]!`	ENGINE-STAMPED — the public ES256 signing keys (1..4: the current key + the outgoing keys inside their 7-day grace), published as the profile’s keys; minted at birth, grown by rotateAgentChannelKey, never caller-typed. The private halves live in the credential store.

AgentChannel

Fields

Used by