Update tenant function

An update tenant function updates a tenant stored in Knock as a step in your workflow. Use it when you need to change a tenant's properties based on workflow context so that downstream steps or other workflows see the updated data.

Common use cases include syncing tenant state from your trigger (for example, approval status or feature flags), updating tenant-level preference defaults, or storing data on the tenant that you reference later in the same workflow or in another workflow.

By default, Knock updates the tenant associated with the current workflow run (the tenant you passed in the trigger). You can leave this default, or select a property that resolves to a tenant ID (or use a literal tenant ID) to update a different tenant.

The update tenant step supports upserting. If you specify a tenant ID that does not yet exist in Knock, the tenant will be created with the properties you set.

You can update a tenant's default preferences from within a workflow. Use the preference_set key nested under settings (not preferences) when setting tenant preferences. The value should follow the structure of a PreferenceSet. For more information on how tenant preferences work and how to structure them, see tenant preferences.

Tenant preference defaults are deep-merged into the tenant's existing preference set. This means you can set individual preference keys across multiple update tenant steps without overwriting previously set values. For example, two sequential update tenant steps can each target a different part of the preference set and the results will be combined:

For more details on updating tenant default preferences and how to modify the merge behavior, see the tenant preferences FAQ.

You can set any number of properties on the tenant. Each property has a key and a value. Properties can be configured as a JSON blob or as key-value pairs.

• Key. The property name. You can use an existing tenant property or define a new property.
• Value. The value to set. You can use Liquid (for example, {{ data.tenant_name }} or {{ tenant.id }}) to resolve a dynamic value from workflow data, the recipient, the actor, or variables. You can also use a static value (for example, "Acme Corp" or true).

When an update tenant step executes, Knock deep-merges the configured properties into the existing tenant. This means:

• Top-level keys are merged into the existing tenant, adding new keys and replacing existing ones.
• Nested objects are recursively merged rather than replaced. If the existing tenant has a nested object and the update step sets a key inside it, only that key is updated — the rest of the nested object is preserved.

Update tenant steps do not support updating channel data. You cannot set or change channel data on a tenant via this step.

In addition, channel_data is not rendered in the workflow event success or error logging for these recipients, even when channel data is present on the tenant.

You can use the workflow run logs to debug update tenant steps. The logs render the full before/after diff view of the tenant so that you can verify the pre-state, the properties that were set, and the post-state.

Update tenant steps are also available in the management API.