Update a Flow action

After you've deployed your Shopify Flow action extension, subsequent deploys that update your extension can affect live workflows that use it. This guide explains how those updates affect existing workflows, and gives recommendations for making changes safely.

Anchor to Adding or removing fieldsAdding or removing fields

When you add or remove a field on your Flow action extension, that change isn't immediately propagated to workflows that already use your extension when you deploy. Merchants need to update their existing uses to configure the new set of fields. Until they do, those existing instances keep sending requests to your endpoint using their previously configured fields, so a payload might omit a field you've added or include a field you've removed. This is intentional, so you can decide how to handle outdated uses of their extensions.

Adding or removing fields doesn't break these workflows: Flow still sends the request, so your endpoint always receives it. Make your endpoint tolerant of both the old and new sets of fields:

• Ignore any field that you've removed and no longer use.
• Provide default values for any required field that you've added, in case it's missing.
• If a request is missing data that your action can't run without, then return an error so the merchant knows to reconfigure the step.

If a backward-compatible change isn't feasible, then create a new Flow action extension instead.

Anchor to Changing field typesChanging field types

Changing the type of an existing field is a breaking change. A field's type determines the format of its value in the payload. For example, a text field sends a string, a number field sends a number, a checkbox sends a boolean, and a reference field sends a GraphQL Admin API GID, such as gid://shopify/Customer/1234567.

Unlike adding or removing fields, changing a field's type breaks any workflow that already uses that field. The value that a merchant configured under the old type isn't valid for the new type, so those workflow runs fail before Flow sends a request to your endpoint, and they stay broken until the merchant reconfigures the step.

Because these runs fail before your endpoint is called, you can't detect or recover from a field type change at your endpoint. Avoid changing field types in place:

• Add a new field with the new type and deprecate the old one, rather than repurposing an existing field.
• If a backward-compatible change isn't feasible, then create a new Flow action extension instead.

Anchor to Updating endpointsUpdating endpoints

All of your Flow action endpoint URLs (the runtime_url, validation_url, config_page_url, and config_page_preview_url) are resolved dynamically. When you deploy a new version of your extension that adds or updates any of these endpoints, the change propagates immediately to all active uses of your extension, without the merchant needing to reactivate the workflow. Each URL is called at its own point in the extension's lifecycle. For example, the validation_url when a merchant configures a step and the runtime_url when the action runs, so an updated URL takes effect the next time Flow needs to call that particular endpoint.

Keep this in mind whenever adding or updating a Flow action endpoint URL.