Queries
calendarEvent— Fetch a calendar event by id. Returns null when this store has no event with that id.calendarEventCatalog— The calendar’s grammar: event types, the agenda item kinds each accepts, the input key that writes each kind, and how the Commerce Agent uses them. Read it before creating or editing calendar events.calendarEvents— Calendar events on this store, earliest start first unlessorderBysays otherwise. To list the events overlapping a window, pass its start asendsAfterand its end asstartsBefore. ReadcalendarEventCatalogfor what each event type and agenda item kind does.commerceAgentConfig(Experimental) — One version of every Commerce Agent Playbook setting, with arevisionthat identifies its content. ReadDRAFTandPUBLISHEDseparately and compare them to see what changed. Null means the store has not published yet, when asking forPUBLISHED. Reading never changes anything.commerceAgentConfigChanges(Experimental) — Edits and publishes of the store’s Commerce Agent config, newest first, and who made each. PassstrategyIdfor one strategy’s changes instead. Publishes are listed from November 2026.commerceAgentConversation— Fetch a single Commerce Agent conversation by its id.commerceAgentConversations— List Commerce Agent conversations, the same set the Commerce Agent conversations page shows: conversations with at least one outreach. Filter by reply status, who started them, the campaign or automation behind them, or search shopper names, emails, phones, and message text.discountOffer(Experimental) — Fetch one of the store’s discount offers by its id.discountOffers(Experimental) — The store’s discount offers, in the order the Commerce Agent tries them.knowledgeArticle— Fetch a single Commerce Agent knowledge article by its id.knowledgeArticles— List Commerce Agent knowledge articles, optionally filtered by title/body substring, status, or origin.searchKnowledgeArticles— Ranked text search over Commerce Agent knowledge articles, including drafts and disabled articles. Ranking is not keyset-paginated; cap results withfirst.
Mutations
commerceAgentConfigDraftUpdate(Experimental) — Stage Playbook settings in the shared draft, the one the Playbook page edits. Only the fields you pass change, and the published version never does: the settings go live when the draft is published. A draft left equal to the published version is deleted. Returns theDRAFTversion with its newrevision; null when nothing is configured yet and nothing changed. Pass therevisionyou read asexpectedRevisionto refuse the change (409 REVISION_STALE) when the draft changed since. NO_UPDATE_FIELDS when you pass no setting to change (expectedRevisionalone is not one); LIVE_ONLY_FIELD forbrandName,brandBioorexcludeSmsProviderUnsubscribers; BAD_USER_INPUT for a null or a value outside its limits. Refused with 403 when it turns on iMessage, RCS or extended outreach the store cannot use, or changesreturnWindowGracewith an API key or without Set returns and claims settings, or namesSHOP_PAYincapabilityGuidancefor a store that does not have Shop Pay; with 404 NOT_FOUND when an escalation guideline’sknowledgeIdis not one of the store’s; with 409 whendiscountis set for a store that still has an enabled support discount not yet moved to the Commerce Agent.commerceAgentConfigPublish(Experimental) — Publish the Playbook settings you pass, not the rest of the draft: a copy of the published version with these values becomes the newPUBLISHEDversion. The values are also written into the shared draft, the one the Playbook page edits, so the merchant’s next Save & Publish keeps them; so is extended outreach when turning the agent on switches it on. The draft’s other pending edits stay pending, except a value paired with one you pass (escalation and its support email, or the two late-return cutoffs) when the draft’s would no longer be valid with yours. A draft left equal to the published version is deleted. There is no revision check: the latest publish wins. Values that already equal the published ones create no version, but are still written into the draft. When the store has nothing published yet, a first version goes live with these values and the draft’s tone, which the agent already uses; the agent stays off unless you passenabledtrue, and the persona gets the store’s default name unless you passpersonaName; the draft’s other edits stay pending. NO_UPDATE_FIELDS when you pass no setting.brandName,brandBioandexcludeSmsProviderUnsubscribersare saved too;brandNameandexcludeSmsProviderUnsubscribersneed a user with Set marketing settings, so an API key is refused (403). If the bio or the SMS option cannot be saved, the settings are still published and the call fails with 503 LIVE_FIELDS_NOT_SAVED naming them; repeat the call with only those fields. Returns thePUBLISHEDversion with itsrevision; null when the store still has nothing published, because the call created no first version (the draft is left as it was;brandBioandexcludeSmsProviderUnsubscribersare still saved) or the store has no Commerce Agent account (nothing is saved). BAD_USER_INPUT for a null or a value outside its limits. Refused with 403 when it turns on iMessage, RCS or extended outreach the store cannot use, or changesreturnWindowGracewith an API key or without Set returns and claims settings, or namesSHOP_PAYincapabilityGuidancefor a store that does not have Shop Pay; with 404 NOT_FOUND when an escalation guideline’sknowledgeIdis not one of the store’s; with 409 whendiscountis set for a store that still has an enabled support discount not yet moved to the Commerce Agent.createCalendarEvent— Create a calendar event. The Commerce Agent reads MARKETING events near the current date as context when it answers shoppers and writes outbound marketing messages. Upcoming events stay out of its context until they start, unless the merchant allows early mentions on the event in Redo. Read calendarEventCatalog for the agenda item kinds each type accepts.createKnowledgeArticle— Create a Commerce Agent knowledge article. The article is created not retrievable; thestatusyou send is staged in itsdraftand applies when you publish it withknowledgeArticlePublish. Sending neither a status nor an effective window stages nothing.deleteCalendarEvent— Delete a calendar event. Returns true if an owned event was deleted, false if none matched. An event Redo found on the brand’s homepage is dismissed rather than erased, so Redo does not add it again; either way it stops appearing.deleteKnowledgeArticle— Stage the removal of a Commerce Agent knowledge article. The article stays live untilknowledgeArticlePublishpublishes the removal; a laterupdateKnowledgeArticlecancels it. Returns true if an owned article’s removal was staged, false if none matched.discountOfferCreate(Experimental) — Add an offer at the bottom of the store’s discount offer list.discountOfferDelete(Experimental) — Delete an offer from the store’s list. Codes it already gave stop counting as the shopper’s. Returns false if the store has no offer with that id.discountOfferPause(Experimental) — Pause an offer, so the Commerce Agent skips it. Returns null if the store has no offer with that id.discountOffersReorder(Experimental) — Set the order the Commerce Agent tries the store’s offers in, top first.idsmust name every offer on the list exactly once, else BAD_USER_INPUT. Returns the list in its new order.discountOfferUnpause(Experimental) — Turn a paused offer back on. Returns null if the store has no offer with that id.discountOfferUpdate(Experimental) — Save new terms for an offer as its next version. Texts already sent keep the version they were picked under; its place and whether it’s paused don’t change. Returns null if the store has no offer with that id.knowledgeArticlePublish(Experimental) — Publish the changes staged on a Commerce Agent knowledge article, so Commerce Agent uses them. Fails withKNOWLEDGE_ARTICLE_REVISION_STALEwhen the draft changed sinceexpectedRevision, and withKNOWLEDGE_ARTICLE_DRAFT_STALEwhen the live article changed after the draft was staged: stage the change again withupdateKnowledgeArticle, ordeleteKnowledgeArticlefor a removal, then publish thedraft.revisionit returns. Repeating a publish that already went live returns the article unchanged. Returns null when this store has no article with that id.updateCalendarEvent— Change a calendar event’s fields and agenda in one step. Returns null when this store has no event with that id. Editing an event Redo found on the brand’s homepage stops Redo from updating it.updateKnowledgeArticle— Stage changes to a Commerce Agent knowledge article. Commerce Agent keeps using the live article, which the top-level fields show, untilknowledgeArticlePublishpublishes the draft. If the live article changed after you staged, the draft restarts from the live article and staged fields you do not send again are dropped. Returns null if no owned article matches the id.
Objects
CalendarDetectedPromotion— How Redo found a promotion on the brand’s homepage. Set by Redo, not writable through this API. Redo stops updating the event once it is edited.CalendarEvent— Something happening for the brand on a known date, such as a sale, launch, or holiday, with an agenda of typed items that give it behavior. The Commerce Agent reads MARKETING events near the current date as context, both when it answers shoppers and when it writes outbound marketing messages, and may repeat what they say to shoppers.CalendarEventCatalog— What a calendar event can be: its types, the agenda item kinds that give it behavior, and the limits writes enforce. New kinds are added here as they ship, so read it before creating or editing events.CalendarEventCatalogAgendaItemKind— An agenda item kind this API reads and writes field by field, and the input key that carries its fields.CalendarEventCatalogEventType— An event type createCalendarEvent accepts.CalendarPromotionAgendaItem— A sale or offer running during the event, described in free text: what is discounted, for whom, and any code shoppers should use. The Commerce Agent reads it as merchant-provided context and may share it with shoppers. It does not create a discount, so a code it mentions must already exist. Promotions found on the brand’s homepage carrydetectionand are kept up to date until the event is edited.CalendarUnknownAgendaItem— An agenda item this API version cannot read field by field, such as a kind newer than the API. Remove it with aremoveagenda operation.CommerceAgentConfig— One version of the Commerce Agent’s Playbook settings.brandBio,excludeSmsProviderUnsubscribersandcapabilitiesare live: the same in both versions.CommerceAgentConfigCapabilities— What the Commerce Agent can do today, as the Playbook’s Capabilities page shows it. Read only, from the published version, and the same in both versions.CommerceAgentConfigCapabilityGuidance— The merchant’s guidance for one capability.CommerceAgentConfigChange(Experimental) — One change to the Commerce Agent config or a strategy, and who made it.CommerceAgentConfigChannel— One outreach channel.CommerceAgentConfigChannels— Where the Commerce Agent can reach shoppers.CommerceAgentConfigDiscount— The discount the Commerce Agent may offer.CommerceAgentConfigEscalation— Whether the agent hands a conversation to the support team.CommerceAgentConfigEscalationGuideline— A rule for when the agent keeps a conversation instead of handing it to the support team.CommerceAgentConfigReturnWindowGrace— How many days past the return window the agent, and then the team, may still accept a return.CommerceAgentConfigTone— How the agent sounds.CommerceAgentConversation— A conversation between a shopper and Commerce Agent, as listed on the Commerce Agent conversations page.CommerceAgentMessage— One message in a Commerce Agent conversation.CommerceAgentOutreach— An outbound message that opened or continued a conversation, and what sent it.CommerceAgentToneRange— The span the agent keeps to on a one-to-five slider.minis at mostmax.DiscountOffer(Experimental) — One row of the store’s discount offer list. The Commerce Agent offers a shopper the first offer, top to bottom, whose audience, cart conditions and window they match.DiscountOfferCartCollectionsCondition(Experimental) — Matches on cart products in the listed collections.DiscountOfferCartConditionBlock(Experimental) — A group of cart conditions combined by one conjunction.DiscountOfferCartConditions(Experimental) — Which carts the offer is for: blocks of conditions, combined by one conjunction.DiscountOfferCartDiscountCodeCondition(Experimental) — Matches on the discount codes already applied to the cart.DiscountOfferCartDiscountPercentageCondition(Experimental) — Compares the percentage the cart’s applied discounts take off with a number.DiscountOfferCartOutOfStockCondition(Experimental) — Matches when any cart item is out of stock.DiscountOfferCartProduct(Experimental) — A product a products condition lists.DiscountOfferCartProductsCondition(Experimental) — Matches on the listed products in the cart.DiscountOfferCartProductTagsCondition(Experimental) — Matches on the tags of the cart’s products.DiscountOfferCartQuantityCondition(Experimental) — Compares how many items the cart holds, counting each item’s quantity, with a number.DiscountOfferCartSubtotalCondition(Experimental) — Compares the cart’s subtotal with an amount.DiscountOfferConditionsAudience(Experimental) — The offer is for shoppers who match inline segment rules.DiscountOfferDiscount(Experimental) — One of the discounts an offer gives, with its share of the shoppers the offer matches.DiscountOfferEveryoneAudience(Experimental) — The offer is for every shopper.DiscountOfferSegmentsAudience(Experimental) — The offer is for members of any of these saved segments.KnowledgeArticle— A Commerce Agent knowledge article the merchant authored or imported. The top-level fields are the live article that Commerce Agent uses; changes staged through the API wait indraftuntilknowledgeArticlePublishmakes them live. Retrieval eligibility lives onstatusand the effective window, not on the body.KnowledgeArticleChange(Experimental) — One change to a knowledge article, what it changed and who made it. The before and after fields are null where the change did not touch them.KnowledgeArticleDraft(Experimental) — Changes staged on a knowledge article bycreateKnowledgeArticle,updateKnowledgeArticleordeleteKnowledgeArticle. Commerce Agent does not use them until you publish them withknowledgeArticlePublish.
Interfaces
CalendarEventAgendaItem— Something attached to a calendar event that gives it behavior, such as a promotion. Each kind is its own type;kindsays which. An event can carry several, including several of one kind.
Input objects
CalendarAgendaItemInput— One agenda item’s fields under its kind’s key. Set exactly one key;calendarEventCatalog.agendaItemKindslists each kind’spayloadKey.CalendarAgendaItemRemoveInput— An agenda item to remove.CalendarAgendaItemUpdateInput— Changes to one existing agenda item.CalendarAgendaOperationInput— One change to an event’s agenda. Set exactly one ofadd,update, orremove.CalendarPromotionAgendaItemInput— The fields of a PROMOTION agenda item.CommerceAgentConfigCapabilityGuidanceInput— The guidance to save for one capability.CommerceAgentConfigChannelInput— Changes to one outreach channel.CommerceAgentConfigChannelsInput— Changes to the outreach channels. A channel you leave out keeps its stored value. Turning on iMessage, RCS or extended outreach is refused (403) when the store cannot use it.CommerceAgentConfigDiscountInput— Changes to the discount the Commerce Agent may offer. Refused (409) for a store that still has an enabled support discount not yet moved to the Commerce Agent.CommerceAgentConfigEscalationGuidelineInput— One rule for keeping a conversation with the agent.CommerceAgentConfigEscalationInput— Changes to handing conversations to the support team.CommerceAgentConfigInput— Playbook settings to stage in the draft or to publish. Only the fields you pass change: a field you leave out keeps its stored value, and a group must set at least one field. Null is accepted only forrecontactCooldownHours,discount.discountCodeId,escalationGuidelines[].knowledgeIdandcapabilityGuidance[].guidance; everywhere else it is refused, so leave the field out.brandName,brandBioandexcludeSmsProviderUnsubscribersgo live at once, so only commerceAgentConfigPublish takes them; a draft update refuses them.CommerceAgentConfigReturnWindowGraceInput— Changes to the late-return cutoffs. Needs a team member who holds Set returns and claims settings, so an API key is refused (403). With no cutoffs stored yet, pass both fields.CommerceAgentConfigToneInput— Changes to how the agent sounds. A field you leave out keeps its stored value.CommerceAgentToneRangeInput— The span the agent keeps to on a one-to-five slider.minis at mostmax.CreateCalendarEventInput— A new calendar event.CreateKnowledgeArticleInput— Fields for a new Commerce Agent knowledge article. The article is created not retrievable (DRAFT);statusand the effective window are staged and apply when you publish.DiscountOfferAudienceInput(Experimental) — Who the offer is for. Pass exactly one of everyone, segmentIds or conditions.DiscountOfferCartCollectionsConditionInput(Experimental) — Match on cart products in the listed collections.DiscountOfferCartConditionBlockInput(Experimental) — A group of cart conditions combined by one conjunction.DiscountOfferCartConditionInput(Experimental) — Pass exactly one of subtotal, quantity, products, collections, productTags, discountCode, discountPercentage or anyItemOutOfStock.DiscountOfferCartConditionsInput(Experimental) — Which carts the offer is for, at least one block.DiscountOfferCartDiscountCodeConditionInput(Experimental) — Match on the discount codes already applied to the cart.DiscountOfferCartDiscountPercentageConditionInput(Experimental) — Compare the percentage the cart’s applied discounts take off with a number.DiscountOfferCartProductInput(Experimental) — A product to list.DiscountOfferCartProductsConditionInput(Experimental) — Match on the listed products in the cart.DiscountOfferCartProductTagsConditionInput(Experimental) — Match on the tags of the cart’s products.DiscountOfferCartQuantityConditionInput(Experimental) — Compare how many items the cart holds with a number.DiscountOfferCartSubtotalConditionInput(Experimental) — Compare the cart’s subtotal with an amount.DiscountOfferDiscountInput(Experimental) — A discount the offer gives, and its share of the offer’s shoppers.DiscountOfferInput(Experimental) — What an offer says. An update sends all of it again, and it becomes the offer’s next version.UpdateCalendarEventInput— Changes to a calendar event. Omitted or null fields are unchanged, exceptdescription, which null clears. Field changes andagendaOperationsapply together or not at all.UpdateKnowledgeArticleInput— Fields to stage on the article. Omit a field to leave it unchanged. SendingreferencedProductFamilyIdsorreferencedArticleIdsreplaces that set. Nothing is live until you publish.
Enums
CalendarAgendaItemKind— What an agenda item adds to its calendar event.calendarEventCatalog.agendaItemKindsdescribes each kind and the input key that writes it.CalendarDetectedPromotionStatus— Whether the brand’s homepage still showed the promotion on Redo’s last check.CalendarEventSortKey— A field this list can be ordered by; pass to the list’sorderByargument and pair withreverseto flip direction.CalendarEventStatus— Where an event falls relative to the current time, worked out fromstartAtandendAton every read.CalendarEventType— The part of the business an event belongs to.calendarEventCatalog.eventTypeslists the agenda item kinds each type accepts and whether the Commerce Agent reads it.CommerceAgentAuthor— Who started a conversation, in the terms the Commerce Agent conversations page uses.CommerceAgentAutomationKind— Which kind of automation sent an outreach. Set only when the origin isAUTOMATION.CommerceAgentCapability— A thing the Commerce Agent can do that takes the merchant’s own guidance.CommerceAgentChangeActor(Experimental) — Who made a Commerce Agent change.CommerceAgentChannel— The channel a Commerce Agent conversation takes place on.CommerceAgentConfigChangeKind(Experimental) — What a Commerce Agent config or strategy change did.CommerceAgentConfigChannelStatus— Whether a channel can send, as the Playbook’s Channels page shows it.CommerceAgentConfigVersion— Which version of the Commerce Agent settings to read.CommerceAgentConversationSentiment— The shopper’s sentiment in the latest conversation analysis.CommerceAgentConversationSortKey— A fieldcommerceAgentConversationscan be ordered by; pair withreverseto flip direction. Conversations missing the value sort last either way.CommerceAgentConversationStatus— Reply state of a conversation.CommerceAgentDiscountProclivity— How readily the Commerce Agent offers its discount.CommerceAgentGenerationMode— How an outreach message was written.CommerceAgentMessageSender— Who wrote a message in a Commerce Agent conversation.CommerceAgentOutreachOrigin— What started an outreach.KnowledgeArticleChangeAction(Experimental) — What a knowledge article change did.KnowledgeArticleOrigin— How this article was created. Immutable after create.KnowledgeArticleSortKey— A field this list can be ordered by; pass to the list’sorderByargument and pair withreverseto flip direction.KnowledgeArticleStatus— Whether Commerce Agent may retrieve this article, independent of its schedule.