# 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](/types/#scalars) `ID!` | The record’s id — a UUID the platform assigned when the record was created; every reference to this record uses it. |
| `sysId` | [String](/types/#scalars) `String!` | The group-scoped human-facing system id (AG-…). |
| `type` | [String](/types/#scalars) `String!` | The kind of record — always `AgentChannel` here. |
| `caption` | [String](/types/#scalars) `String!` | The record’s display name — what people see it called. |
| `status` | [String](/types/#scalars) `String!` | The FSM state: draft \| live \| paused \| doomed. |
| `parentId` | [ID](/types/#scalars) `ID!` | The parent Organization; rootId = the org group; parentId!== rootId always. |
| `rootId` | [ID](/types/#scalars) `ID!` | The org-group family root. |
| `createdAt` | [String](/types/#scalars) `String!` | When the record was created, as a UTC timestamp. |
| `updatedAt` | [String](/types/#scalars) `String!` | When the record last changed, as a UTC timestamp. |
| `revisionNum` | [Int](/types/#scalars) `Int!` | How many times this record has been edited; the first save is 0. |
| `revision` | [ID](/types/#scalars) `ID!` | The OCC revision token — supply it on every mutation of this record; rotates on every write. |
| `refCaptions` | [RefCaption](/types/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](/types/#scalars) `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](/types/#scalars) `[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](/types/#scalars) `[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](/types/#scalars) `[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](/types/#scalars) | WHAT — an optional CHANNEL-type Division framing the agent channel; null = unframed. |
| `showStockLevels` | [Boolean](/types/#scalars) `Boolean!` | WHAT — whether agents read stock FIGURES (true) or only in/out of stock (false — the strict default). |
| `excludedVariantIds` | [ID](/types/#scalars) `[ID!]!` | WHAT — the hand veto list: Variants never listed whatever their Collections say (0..200, distinct, each in-tenant); replaces WHOLESALE. |
| `priceListId` | [ID](/types/#scalars) | 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](/types/#scalars) `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](/types/#scalars) | 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](/types/AgentChannelFulfillmentMethod/) `[AgentChannelFulfillmentMethod!]!` | FULFILLMENT — the offered methods (ship · pickup_instore · pickup_curbside; distinct); EMPTY = the channel cannot complete a checkout (publish refuses). |
| `shippingOptions` | [AgentChannelShippingOption](/types/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](/types/#scalars) `Int!` | FULFILLMENT — handling days before a shipment leaves (0..30; default 0). |
| `requireBuyerEmail` | [Boolean](/types/#scalars) `Boolean!` | PAYMENTS — the buyer must give an email before completing (strict default true). |
| `requireBuyerPhone` | [Boolean](/types/#scalars) `Boolean!` | PAYMENTS — the buyer must give a phone number before completing (default false). |
| `allowedPlatforms` | [AgentChannelPlatform](/types/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](/types/AgentChannelRateClass/) `AgentChannelRateClass!` | PLATFORMS — the canned request-rate class granted to platforms (low · normal · high; default normal). |
| `consentDefaults` | [AgentChannelConsentDefaults](/types/AgentChannelConsentDefaults/) `AgentChannelConsentDefaults!` | CONSENT — the UCP buyer_consent defaults the channel proposes (marketing · analytics · preferences · sale_or_sharing); strict default all false. |
| `returnPolicy` | [String](/types/#scalars) | POLICIES — the return policy text (at most 2000 characters), published in the profile’s policies; null = none published. |
| `warrantyPolicy` | [String](/types/#scalars) | POLICIES — the warranty policy text (at most 2000 characters), published in the profile’s policies; null = none published. |
| `checkoutTtlMinutes` | [Int](/types/#scalars) `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](/types/#scalars) `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](/types/#scalars) `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](/types/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. |

## Used by

- [agentChannel](/reference/agent-channel/agentChannel/)
- [createAgentChannel](/reference/agent-channel/createAgentChannel/)
- [doomAgentChannel](/reference/agent-channel/doomAgentChannel/)
- [pauseAgentChannel](/reference/agent-channel/pauseAgentChannel/)
- [publishAgentChannel](/reference/agent-channel/publishAgentChannel/)
- [resumeAgentChannel](/reference/agent-channel/resumeAgentChannel/)
- [rotateAgentChannelKey](/reference/system-and-integration-setup/rotateAgentChannelKey/)
- [updateAgentChannel](/reference/agent-channel/updateAgentChannel/)