Commands › Exchange Online

Set-RetentionCompliancePolicy

Exchange Online ExchangeOnlineManagement Set-*

For more information, see Security & Compliance PowerShell. Use the Set-RetentionCompliancePolicy cmdlet to modify existing retention policies in the Microsoft Purview compliance portal. **Note**: Running this cmdlet causes a full synchronization across your organization, which is a significant operation. If you need to update multiple policies, wait until the policy distribution is successful before running the cmdlet again for the next policy. For information about the distribution status, see Get-RetentionCompliancePolicy.

Quick start script

# Set-RetentionCompliancePolicy — quick start (serv365.ai)
# 1. Connect (app-only shown; interactive: omit the certificate parameters)
Connect-ExchangeOnline -CertificateThumbprint $thumb -AppId $appId -Organization $org

# 2. Capture the current state first — you cannot roll back what you never recorded
$before = Get-RetentionCompliancePolicy
$before | Format-List

# 3. Make the change (dry run first)
Set-RetentionCompliancePolicy -Identity <PolicyIdParameter> -RetryDistribution <SwitchParameter> -WhatIf
Set-RetentionCompliancePolicy -Identity <PolicyIdParameter> -RetryDistribution <SwitchParameter>

# 4. Verify and diff
$after = Get-RetentionCompliancePolicy
Compare-Object ($before | Out-String) ($after | Out-String)

Syntax — 4 parameter sets

Identity

Set-RetentionCompliancePolicy [-Identity] <PolicyIdParameter>
 [-AddExchangeLocation <MultiValuedProperty>]
 [-AddExchangeLocationException <MultiValuedProperty>]
 [-AddModernGroupLocation <MultiValuedProperty>]
 [-AddModernGroupLocationException <MultiValuedProperty>]
 [-AddOneDriveLocation <MultiValuedProperty>]
 [-AddOneDriveLocationException <MultiValuedProperty>]
 [-AddPublicFolderLocation <MultiValuedProperty>]
 [-AddSharePointLocation <MultiValuedProperty>]
 [-AddSharePointLocationException <MultiValuedProperty>]
 [-AddSkypeLocation <MultiValuedProperty>]
 [-AddSkypeLocationException <MultiValuedProperty>]
 [-Applications <MultiValuedProperty>]
 [-Comment <String>]
 [-Confirm]
 [-DeletedResources <String>]
 [-Enabled <Boolean>]
 [-EnforceSimulationPolicy <Boolean>]
 [-Force]
 [-PolicyTemplateInfo <PswsHashtable>]
 [-PolicyRBACScopes <MultiValuedProperty>]
 [-PriorityCleanup]
 [-RemoveExchangeLocation <MultiValuedProperty>]
 [-RemoveExchangeLocationException <MultiValuedProperty>]
 [-RemoveModernGroupLocation <MultiValuedProperty>]
 [-RemoveModernGroupLocationException <MultiValuedProperty>]
 [-RemoveOneDriveLocation <MultiValuedProperty>]
 [-RemoveOneDriveLocationException <MultiValuedProperty>]
 [-RemovePublicFolderLocation <MultiValuedProperty>]
 [-RemoveSharePointLocation <MultiValuedProperty>]
 [-RemoveSharePointLocationException <MultiValuedProperty>]
 [-RemoveSkypeLocation <MultiValuedProperty>]
 [-RemoveSkypeLocationException <MultiValuedProperty>]
 [-RestrictiveRetention <Boolean>]
 [-StartSimulation <Boolean>]
 [-WhatIf]
 [<CommonParameters>]

AdaptiveScopeLocation

Set-RetentionCompliancePolicy [-Identity] <PolicyIdParameter> [-AddAdaptiveScopeLocation <MultiValuedProperty>]
 [-Applications <MultiValuedProperty>]
 [-Comment <String>]
 [-Confirm]
 [-DeletedResources <String>]
 [-Enabled <Boolean>]
 [-EnforceSimulationPolicy <Boolean>]
 [-Force]
 [-PriorityCleanup]
 [-RemoveAdaptiveScopeLocation <MultiValuedProperty>]
 [-StartSimulation <Boolean>]
 [-WhatIf]
 [<CommonParameters>]

RetryDistribution

Set-RetentionCompliancePolicy [-Identity] <PolicyIdParameter> [-RetryDistribution]
 [-Confirm]
 [-DeletedResources <String>]
 [-EnforceSimulationPolicy <Boolean>]
 [-PriorityCleanup]
 [-StartSimulation <Boolean>]
 [-WhatIf]
 [<CommonParameters>]

TeamLocation

Set-RetentionCompliancePolicy [-Identity] <PolicyIdParameter>
 [-AddTeamsChannelLocation <MultiValuedProperty>]
 [-AddTeamsChannelLocationException <MultiValuedProperty>]
 [-AddTeamsChatLocation <MultiValuedProperty>]
 [-AddTeamsChatLocationException <MultiValuedProperty>]
 [-Comment <String>]
 [-Confirm]
 [-DeletedResources <String>]
 [-Enabled <Boolean>]
 [-EnforceSimulationPolicy <Boolean>]
 [-Force]
 [-PriorityCleanup]
 [-RemoveTeamsChannelLocation <MultiValuedProperty>]
 [-RemoveTeamsChannelLocationException <MultiValuedProperty>]
 [-RemoveTeamsChatLocation <MultiValuedProperty>]
 [-RemoveTeamsChatLocationException <MultiValuedProperty>]
 [-StartSimulation <Boolean>]
 [-WhatIf]
 [<CommonParameters>]

Parameters (47)

Parameter	Type	Required	What it controls
-Identity	PolicyIdParameter	yes	The Identity parameter specifies the retention policy that you want to modify. You can use any value that uniquely identifies the policy. For example:
-RetryDistribution	SwitchParameter	yes	The RetryDistribution switch specifies whether to redistribute the policy to all Exchange Online and SharePoint locations. You don't need to specify a value with this switch.
-AddAdaptiveScopeLocation	MultiValuedProperty		The AddAdaptiveScopeLocation parameter specifies the adaptive scope location to add to the policy. You create adaptive scopes by using the New-AdaptiveScope cmdlet. You can use any value that uniquely identifies the...
-AddExchangeLocation	MultiValuedProperty		The AddExchangeLocation parameter specifies the mailboxes to add to the list of included mailboxes when you aren't using the value All for the ExchangeLocation parameter. Valid values are:
-AddExchangeLocationException	MultiValuedProperty		This parameter specifies the mailboxes to add to the list of excluded mailboxes when you use the value All for the ExchangeLocation parameter. Valid values are:
-AddModernGroupLocation	MultiValuedProperty		The AddModernGroupLocation parameter specifies the Microsoft 365 Groups to add to the list of included Microsoft 365 Groups when you aren't using the value All for the ModernGroupLocation parameter.
-AddModernGroupLocationException	MultiValuedProperty		The AddModernGroupLocationException parameter specifies the Microsoft 365 Groups to add to the list of excluded Microsoft 365 Groups when you're using the value All for the ModernGroupLocation parameter.
-AddOneDriveLocation	MultiValuedProperty		The AddOneDriveLocation parameter specifies the OneDrive sites to add to the list of included sites when you aren't using the value All for the OneDriveLocation parameter. You identify the site by its URL value.
-AddOneDriveLocationException	MultiValuedProperty		This parameter specifies the OneDrive sites to add to the list of excluded sites when you use the value All for the OneDriveLocation parameter. You identify the site by its URL value.
-AddPublicFolderLocation	MultiValuedProperty		The AddPublicFolderLocation parameter specifies that you want to add all public folders to the retention policy. You use the value All for this parameter.
-AddSharePointLocation	MultiValuedProperty		The AddSharePointLocation parameter specifies the SharePoint sites to add to the list of included sites when you aren't using the value All for the SharePointLocation parameter. You identify the site by its URL value.
-AddSharePointLocationException	MultiValuedProperty		This parameter specifies the SharePoint sites to add to the list of excluded sites when you use the value All for the SharePointLocation parameter. You identify the site by its URL value.
-AddSkypeLocation	MultiValuedProperty		The AddSkypeLocation parameter specifies the Skype for Business Online users to add from the list of included Skype for Business Online users.
-AddSkypeLocationException	MultiValuedProperty		This parameter is reserved for internal Microsoft use.
-AddTeamsChannelLocation	MultiValuedProperty		The AddTeamsChannelLocation parameter specifies the Teams to add to the policy.
-AddTeamsChannelLocationException	MultiValuedProperty		The AddTeamsChannelLocationException parameter specifies the Teams to add to the exclusion list when you use the value All for the TeamsChannelLocation parameter. You can use any value that uniquely identifies the...
-AddTeamsChatLocation	MultiValuedProperty		The AddTeamsChatLocation parameter specifies the Teams users to add to the policy.
-AddTeamsChatLocationException	MultiValuedProperty		The AddTeamsChatLocationException parameter specifies the Teams users to add to the exclusion list when you use the value All for the TeamsChatLocation parameter. You can use any value that uniquely identifies the...
-Applications	MultiValuedProperty		The Applications parameter specifies the target when Microsoft 365 Groups are included in the policy (the ModernGroups parameter is set). Valid values are:
-Comment	String		The Comment parameter specifies an optional comment. If you specify a value that contains spaces, enclose the value in quotation marks ("), for example: "This is an admin note".
-Confirm	SwitchParameter		The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on whether the cmdlet requires confirmation before proceeding.
-DeletedResources	String		The DeletedResources parameter specifies the deleted Microsoft 365 Group, mailbox, or mail user to be removed or added as an exclusion to the respective location list. Use this parameter with the...
-Enabled	Boolean		The Enabled parameter specifies whether the policy is enabled. Valid values are:
-EnforceSimulationPolicy	Boolean		The EnforceSimulationPolicy parameter specifies whether to enforce a simulation policy as an active policy. Valid values are:
-Force	SwitchParameter		The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch.
-PolicyRBACScopes	MultiValuedProperty		Note: Admin units aren't currently supported, so this parameter isn't functional. The information presented here is for informational purposes when support for admin units is released.
-PolicyTemplateInfo	PswsHashtable		This parameter is reserved for internal Microsoft use.
-PriorityCleanup	SwitchParameter		The PriorityCleanup switch specifies whether to update a Priority cleanup policy. You don't need to specify a value with this switch.
-RemoveAdaptiveScopeLocation	MultiValuedProperty		The RemoveAdaptiveScopeLocation parameter specifies the adaptive scope location to remove from the policy. You create adaptive scopes by using the New-AdaptiveScope cmdlet. You can use any value that uniquely...
-RemoveExchangeLocation	MultiValuedProperty		The RemoveExchangeLocation parameter specifies the mailboxes to remove from the list of included mailboxes when you aren't using the value All for the ExchangeLocation parameter.
-RemoveExchangeLocationException	MultiValuedProperty		The RemoveExchangeLocationException parameter specifies the mailboxes to remove from the list of excluded mailboxes when you use the value All for the ExchangeLocation parameter.
-RemoveModernGroupLocation	MultiValuedProperty		The RemoveModernGroupLocation parameter specifies the Microsoft 365 Groups to remove from the list of included groups when you aren't using the value All for the ModernGroupLocation parameter.
-RemoveModernGroupLocationException	MultiValuedProperty		The RemoveModernGroupLocationException parameter specifies the Microsoft 365 Groups to remove from the list of excluded groups when you're using the value All for the ModernGroupLocation parameter.
-RemoveOneDriveLocation	MultiValuedProperty		The RemoveOneDriveLocation parameter specifies the OneDrive sites to remove from the list of included sites when you aren't using the value All for the OneDriveLocation parameter. You identify the site by its URL value.
-RemoveOneDriveLocationException	MultiValuedProperty		This parameter specifies the OneDrive sites to remove from the list of excluded sites when you use the value All for the OneDriveLocation parameter. You identify the site by its URL value.
-RemovePublicFolderLocation	MultiValuedProperty		The RemovePublicFolderLocation parameter specifies that you want to remove all public folders from the retention policy. You use the value All for this parameter.
-RemoveSharePointLocation	MultiValuedProperty		The RemoveSharePointLocation parameter specifies the SharePoint sites to remove from the list of included sites when you aren't using the value All for the SharePointLocation parameter. You identify the site by its URL value.
-RemoveSharePointLocationException	MultiValuedProperty		This parameter specifies the SharePoint sites to remove from the list of excluded sites when you use the value All for the SharePointLocation parameter. You identify the site by its URL value.
-RemoveSkypeLocation	MultiValuedProperty		The RemoveSkypeLocation parameter specifies the Skype for Business Online users to remove from the list of included Skype for Business Online users.
-RemoveSkypeLocationException	MultiValuedProperty		This parameter is reserved for internal Microsoft use.
-RestrictiveRetention	Boolean		The RestrictiveRetention parameter specifies whether Preservation Lock is enabled for a retention policy or retention label policy. Valid values are:
-RemoveTeamsChannelLocation	MultiValuedProperty		The RemoveTeamsChannelLocation parameter specifies the Teams to remove from the policy.
-RemoveTeamsChannelLocationException	MultiValuedProperty		The RemoveTeamsChannelLocationException parameter specifies the Teams to remove from the exclusion list when you use the value All for the TeamsChannelLocation parameter. You can use any value that uniquely...
-RemoveTeamsChatLocation	MultiValuedProperty		The RemoveTeamsChatLocation parameter specifies the Teams users to remove from the policy.
-RemoveTeamsChatLocationException	MultiValuedProperty		The RemoveTeamsChatLocationException parameter specifies the Teams users to remove from the exclusion list when you use the value All for the TeamsChatLocation parameter. You can use any value that uniquely...
-StartSimulation	Boolean		The StartSimulation parameter specifies whether to start the simulation for a policy that was created in simulation mode. Valid values are:
-WhatIf	SwitchParameter		The WhatIf switch doesn't work in Security & Compliance PowerShell.

Reference facts derived from Microsoft documentation, © Microsoft, licensed CC BY 4.0; restructured with original guidance by serv365.ai.