On this page
createAgentChannel
mutation · in the family Agent channel
What it does
Set up the agent channel for one of your organizations — the controls AI shopping agents buy under: the selling location, which collections are listed, an optional agent price list, fulfillment methods and shipping rates, ship-to countries and pickup locations, the platforms you allow, consent defaults, policy texts and the checkout window.
Create the AgentChannel of an Organization; requires the unrestricted capability. The tenant is stamped server-side; organizationId (the parent) is tenant-scoped server-side and must be ACTIVE; the selling location, pickup locations, collections, division, price list and excluded variants gate record-aware in the kit (each in-tenant; the LF/collections/division/price list ACTIVE; the division channel-kind; the price list selected for the owning organization and unscoped).
What happens
Born as a draft — nothing is served to agents until you publish; the engine mints the channel’s signing key at birth. One channel per organization: a second create is refused.
Who may call it
Capability area: System and integration setup — Registers, connections and the settings your systems run on.
- Owner
- System Administrator
- An API key whose scope allows
api:createAgentChannel
Arguments
| Name | Type | Required | Notes |
|---|---|---|---|
input | NewAgentChannelInput NewAgentChannelInput! | yes | No further notes. |
Returns
AgentChannel AgentChannel! — 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.
Example request
mutation ExampleCreateAgentChannel($input: NewAgentChannelInput!) {
createAgentChannel(input: $input) {
id
sysId
type
caption
status
parentId
rootId
createdAt
updatedAt
revisionNum
revision
logicalFacilityId
pickupLogicalFacilityIds
shipToCountries
collectionIds
divisionId
showStockLevels
excludedVariantIds
priceListId
allowDiscountCodes
maxCheckoutTotalMinor
fulfillmentMethods
handlingDays
requireBuyerEmail
requireBuyerPhone
rateClass
returnPolicy
warrantyPolicy
checkoutTtlMinutes
identityLinking
requireLinkedBuyer
}
}Variables:
{
"input": {
"caption": "Blue jeans",
"organizationId": "01900000-0000-7000-8000-44b781470000",
"logicalFacilityId": "01900000-0000-7000-8000-8026f71c0000"
}
}Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.
Example response
{
"data": {
"createAgentChannel": {
"id": "01900000-0000-7000-8000-37386ae00000",
"sysId": "AG-EXMP-0000-000F",
"type": "AgentChannel",
"caption": "Blue jeans",
"status": "draft",
"parentId": "01900000-0000-7000-8000-065235280000",
"rootId": "01900000-0000-7000-8000-a093dd800000",
"createdAt": "2027-01-31T00:00:00.000Z",
"updatedAt": "2027-01-31T00:00:00.000Z",
"revisionNum": 1,
"revision": "01900000-0000-7000-8000-b7960e180000",
"logicalFacilityId": "01900000-0000-7000-8000-8026f71c0000",
"pickupLogicalFacilityIds": [
"01900000-0000-7000-8000-095d4a1d0000"
],
"shipToCountries": [
"<ship to countries>"
],
"collectionIds": [
"01900000-0000-7000-8000-b1c179550000"
],
"divisionId": "01900000-0000-7000-8000-25bd925b0000",
"showStockLevels": true,
"excludedVariantIds": [
"01900000-0000-7000-8000-6ad77b420000"
],
"priceListId": "01900000-0000-7000-8000-7844e9fb0000",
"allowDiscountCodes": true,
"maxCheckoutTotalMinor": 1,
"fulfillmentMethods": [
"ship"
],
"handlingDays": 1,
"requireBuyerEmail": true,
"requireBuyerPhone": true,
"rateClass": "low",
"returnPolicy": "<return policy>",
"warrantyPolicy": "<warranty policy>",
"checkoutTtlMinutes": 1,
"identityLinking": true,
"requireLinkedBuyer": true
}
},
"extensions": {
"at": {
"callId": "01EXAMPLE-CALL-ID",
"version": {
"requested": {
"name": "genesis",
"number": 0
},
"serviced": {
"name": "genesis",
"number": 0
}
}
}
}
}Errors this call can answer
VALIDATION/INVALID— Something in the request is not valid. (VALIDATION)AUTHN/REQUIRED— Sign in to do this. (AUTHN)AUTHZ/FORBIDDEN— Your role does not allow this action. (AUTHZ)RATE_LIMIT/THROTTLED— Too many requests in a short time. (RATE_LIMIT)NOT_FOUND/*— That record could not be found. (NOT_FOUND)CONFLICT/*— The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. (CONFLICT)VALIDATION/VERSION_REQUIRED— The request did not say which app version it came from. (VALIDATION)
Dry run
Add dryRun: true to the request envelope (extensions.at) to rehearse this call: every check runs, the write is rehearsed against the current records and nothing is stored; the answer is the refusal a real call would give, or the record it would create. Every response to a rehearsal carries dryRun: true, so a rehearsed record is never mistaken for a saved one.