Skip to main content

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 unless orderBy says otherwise. To list the events overlapping a window, pass its start as endsAfter and its end as startsBefore. Read calendarEventCatalog for what each event type and agenda item kind does.
  • commerceAgentConfig (Experimental) — One version of every Commerce Agent Playbook setting, with a revision that identifies its content. Read DRAFT and PUBLISHED separately and compare them to see what changed. Null means the store has not published yet, when asking for PUBLISHED. Reading never changes anything.
  • commerceAgentConfigChanges (Experimental) — Edits and publishes of the store’s Commerce Agent config, newest first, and who made each. Pass strategyId for 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 with first.

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 the DRAFT version with its new revision; null when nothing is configured yet and nothing changed. Pass the revision you read as expectedRevision to refuse the change (409 REVISION_STALE) when the draft changed since. NO_UPDATE_FIELDS when you pass no setting to change (expectedRevision alone is not one); LIVE_ONLY_FIELD for brandName, brandBio or excludeSmsProviderUnsubscribers; 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 changes returnWindowGrace with an API key or without Set returns and claims settings, or names SHOP_PAY in capabilityGuidance for a store that does not have Shop Pay; with 404 NOT_FOUND when an escalation guideline’s knowledgeId is not one of the store’s; with 409 when discount is 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 new PUBLISHED version. 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 pass enabled true, and the persona gets the store’s default name unless you pass personaName; the draft’s other edits stay pending. NO_UPDATE_FIELDS when you pass no setting. brandName, brandBio and excludeSmsProviderUnsubscribers are saved too; brandName and excludeSmsProviderUnsubscribers need 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 the PUBLISHED version with its revision; null when the store still has nothing published, because the call created no first version (the draft is left as it was; brandBio and excludeSmsProviderUnsubscribers are 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 changes returnWindowGrace with an API key or without Set returns and claims settings, or names SHOP_PAY in capabilityGuidance for a store that does not have Shop Pay; with 404 NOT_FOUND when an escalation guideline’s knowledgeId is not one of the store’s; with 409 when discount is 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; the status you send is staged in its draft and applies when you publish it with knowledgeArticlePublish. 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 until knowledgeArticlePublish publishes the removal; a later updateKnowledgeArticle cancels 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. ids must 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 with KNOWLEDGE_ARTICLE_REVISION_STALE when the draft changed since expectedRevision, and with KNOWLEDGE_ARTICLE_DRAFT_STALE when the live article changed after the draft was staged: stage the change again with updateKnowledgeArticle, or deleteKnowledgeArticle for a removal, then publish the draft.revision it 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, until knowledgeArticlePublish publishes 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 carry detection and 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 a remove agenda operation.
  • CommerceAgentConfig — One version of the Commerce Agent’s Playbook settings. brandBio, excludeSmsProviderUnsubscribers and capabilities are 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. min is at most max.
  • 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 in draft until knowledgeArticlePublish makes them live. Retrieval eligibility lives on status and 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 by createKnowledgeArticle, updateKnowledgeArticle or deleteKnowledgeArticle. Commerce Agent does not use them until you publish them with knowledgeArticlePublish.

Interfaces

  • CalendarEventAgendaItem — Something attached to a calendar event that gives it behavior, such as a promotion. Each kind is its own type; kind says which. An event can carry several, including several of one kind.

Input objects

Enums