> ## Documentation Index
> Fetch the complete documentation index at: https://developers.redo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# commerceAgentConfigDraftUpdate

> 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; with 409 when `discount` is set for a store whose support discount has not moved to the Commerce Agent yet.

**Required scopes:** [`commerce_agent_settings_write`](https://developers.redo.com/docs/api-reference/v3/reference/scopes#scope-commerce_agent_settings_write)

## Arguments

**expectedRevision** `String`

The draft's `revision` as you read it. The change is refused (409 REVISION\_STALE) when the draft has changed since. Omit it, or pass null, to apply the change to whatever the draft is now.

**input** `[CommerceAgentConfigInput!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-input)` *required*

The settings to change.

**fields**

**brandBio** `String`

Not accepted in a draft: it goes live at once, so passing it is refused (LIVE\_ONLY\_FIELD).

**brandName** `String`

Not accepted in a draft: it goes live at once, so passing it is refused (LIVE\_ONLY\_FIELD).

**channels** `[CommerceAgentConfigChannelsInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channels-input)`

Outreach channels.

**fields**

**email** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

Email.

**extendedOutreach** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

Extended outreach. Turning the agent on (`enabled` true while the draft's agent is off) also switches it on, unless you set this too.

**iMessage** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

iMessage.

**rcs** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

Rich text messages (RCS).

**sms** `[CommerceAgentConfigChannelInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-input)`

Text messages.

**discount** `[CommerceAgentConfigDiscountInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-discount-input)`

The discount the agent may offer.

**fields**

**discountCodeId** `ID`

The DiscountCode the agent may offer: an id from `discountCodes`. Leave it out to keep the stored value. Null unlinks it.

**offered** `Boolean`

Whether the agent offers the discount. False keeps the link and stops the offers. Leave it out to keep the stored value. Not null.

**proclivity** `[CommerceAgentDiscountProclivity](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-discount-proclivity)`

How readily the agent offers the discount. Leave it out to keep the stored value. Not null.

**enabled** `Boolean`

Whether the Commerce Agent is on. Turning it on (true while the draft's agent is off) also switches extended outreach on, unless `channels.extendedOutreach` is set or the store's plan has none; true for an agent already on changes nothing. Leave it out to keep the stored value. Not null.

**escalation** `[CommerceAgentConfigEscalationInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-escalation-input)`

Handing conversations to the support team.

**fields**

**contactEmail** `String`

The email address the agent tells shoppers to write to, at most 254 characters. Leave it out to keep the stored value. Not null: an empty string clears it. Left out of the developer log.

**escalateToSupport** `Boolean`

Whether the agent may hand a conversation to support. Leave it out to keep the stored value. Not null.

**excludeSmsProviderUnsubscribers** `Boolean`

Not accepted in a draft: it goes live at once, so passing it is refused (LIVE\_ONLY\_FIELD).

**guidelines** `[String!]`

The whole list of guidelines, in order: at most 20, each at most 500 characters. It replaces the stored list; an empty list clears it. Leave it out to keep the stored value. Not null.

**personaName** `String`

The name the agent goes by, at most 64 characters. Leave it out to keep the stored value. Not null: an empty string clears it.

**recontactCooldownHours** `Int`

Hours before the agent contacts the same shopper again, from 1 to 8760. Leave it out to keep the stored value. Null goes back to the default.

**repliesEnabled** `Boolean`

Whether the agent replies to shoppers who write back. Leave it out to keep the stored value. Not null.

**returnWindowGrace** `[CommerceAgentConfigReturnWindowGraceInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-return-window-grace-input)`

Late-return cutoffs.

**fields**

**agentDays** `Int`

Days past the window the agent may accept a return on its own. Leave it out to keep the stored value. Not null.

**teamReviewDays** `Int`

Days past the window a return goes to the team for review. At least `agentDays`. Leave it out to keep the stored value. Not null.

**tone** `[CommerceAgentConfigToneInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-tone-input)`

Tone and voice.

**fields**

**formalityCasualness** `[CommerceAgentToneRangeInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range-input)`

From formal (1) to casual (5).

**matterOfFactEnthusiasm** `[CommerceAgentToneRangeInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range-input)`

From matter-of-fact (1) to enthusiastic (5).

**respectfulnessIrreverence** `[CommerceAgentToneRangeInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range-input)`

From respectful (1) to irreverent (5).

**seriousnessHumor** `[CommerceAgentToneRangeInput](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range-input)`

From serious (1) to humorous (5).

**voiceInstructions** `String`

Free-text voice instructions, at most 500 characters. Leave it out to keep the stored value. Not null: an empty string clears them.

## Returns

**commerceAgentConfigDraftUpdate** `[CommerceAgentConfig](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config)`

One version of the Commerce Agent's Playbook settings. `brandBio`, `excludeSmsProviderUnsubscribers` and `capabilities` are live: the same in both versions.

**fields**

**brandBio** `String`

A short description of the brand. Live: one value for both versions, outside `revision`. Null when none is set.

**brandName** `String`

What the agent calls the store. Null means it uses the store name.

**capabilities** `[CommerceAgentConfigCapabilities!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-capabilities)` *required*

What the agent can do today. Read only.

**fields**

**discount** `Boolean!` *required*

Whether the agent has a discount to offer now.

**replies** `Boolean!` *required*

Whether the agent replies to shoppers now. False while the agent is off.

**returns** `Boolean!` *required*

Whether the agent can start returns for shoppers. This follows the store's returns setting, so it can be true while the agent is off.

**channels** `[CommerceAgentConfigChannels!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channels)` *required*

Outreach channels.

**fields**

**email** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

Email. Off until the merchant switches it on.

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**extendedOutreach** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

Extended outreach: Commerce Agent's messages beyond replies, such as cart recovery.

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**iMessage** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

iMessage.

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**rcs** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

Rich text messages (RCS).

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**sms** `[CommerceAgentConfigChannel!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel)` *required*

Text messages. On until the merchant switches it off.

**fields**

**enabled** `Boolean!` *required*

Whether the channel is switched on in this version. Not reduced by `status`: a channel the store cannot use yet still shows what was chosen.

**status** `[CommerceAgentConfigChannelStatus!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-channel-status)` *required*

Whether the channel can send, from this version's switch plus the store's live access. Access is the same in both versions.

**discount** `[CommerceAgentConfigDiscount!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-discount)` *required*

The discount the agent may offer.

**fields**

**discountCodeId** `ID`

The DiscountCode the agent may offer. Null when none is linked, or when the discount code was deleted.

**offered** `Boolean!` *required*

Whether the agent offers the discount. False keeps the link and stops the offers.

**proclivity** `[CommerceAgentDiscountProclivity](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-discount-proclivity)`

How readily the agent offers the discount. Null when it was never set.

**enabled** `Boolean!` *required*

Whether the Commerce Agent is on.

**escalation** `[CommerceAgentConfigEscalation!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-escalation)` *required*

Handing conversations to the support team.

**fields**

**contactEmail** `String`

The email address the agent tells shoppers to write to. Null when none is set. Left out of the developer log.

**escalateToSupport** `Boolean!` *required*

Whether the agent may hand a conversation to support.

**excludeSmsProviderUnsubscribers** `Boolean!` *required*

Whether texts skip shoppers who unsubscribed through another SMS provider. Live: one value for both versions, outside `revision`.

**guidelines** `[String!]!` *required*

The merchant's guidelines for the agent, in order.

**personaName** `String`

The name the agent goes by. Null when none is set.

**recontactCooldownHours** `Int`

Hours before the agent contacts the same shopper again. Null means the default.

**repliesEnabled** `Boolean!` *required*

Whether the agent replies to shoppers who write back. A version with no stored choice reads true, as the agent does.

**returnWindowGrace** `[CommerceAgentConfigReturnWindowGrace](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-return-window-grace)`

Late-return cutoffs. Null when none are set.

**fields**

**agentDays** `Int!` *required*

Days past the window the agent may accept a return on its own.

**teamReviewDays** `Int!` *required*

Days past the window a return goes to the team for review. At least `agentDays`.

**revision** `String!` *required*

Identifies this version's content. It changes when any setting in the version changes, including settings this type does not show: instant exchanges, knowledge auto-apply, email replies, Shop Pay, guideline rules, escalation guidelines and capability guidance. It identifies what is stored, so saving a setting again with the same effective value, such as switching off a channel that was already off, can change it too. A fresh draft has the published revision. Live fields are not part of it.

**tone** `[CommerceAgentConfigTone!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-config-tone)` *required*

Tone and voice. A version with no stored choice reads the default sliders.

**fields**

**formalityCasualness** `[CommerceAgentToneRange!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range)` *required*

From formal (1) to casual (5).

**fields**

**max** `Int!` *required*

The high end, from 1 to 5.

**min** `Int!` *required*

The low end, from 1 to 5.

**matterOfFactEnthusiasm** `[CommerceAgentToneRange!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range)` *required*

From matter-of-fact (1) to enthusiastic (5).

**fields**

**max** `Int!` *required*

The high end, from 1 to 5.

**min** `Int!` *required*

The low end, from 1 to 5.

**respectfulnessIrreverence** `[CommerceAgentToneRange!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range)` *required*

From respectful (1) to irreverent (5).

**fields**

**max** `Int!` *required*

The high end, from 1 to 5.

**min** `Int!` *required*

The low end, from 1 to 5.

**seriousnessHumor** `[CommerceAgentToneRange!](/docs/api-reference/v3/reference/commerce-agent/commerce-agent-tone-range)` *required*

From serious (1) to humorous (5).

**fields**

**max** `Int!` *required*

The high end, from 1 to 5.

**min** `Int!` *required*

The low end, from 1 to 5.

**voiceInstructions** `String`

Free-text voice instructions. Null when none are set.

## Example

```graphql theme={null}
mutation {
  commerceAgentConfigDraftUpdate(expectedRevision: "...", input: { ... }) {
    brandBio
    brandName
    enabled
    excludeSmsProviderUnsubscribers
    guidelines
    personaName
    recontactCooldownHours
    repliesEnabled
    # ...
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.