Partners

URL Redirects

Manage dead storefront paths without shadowing live routes.

A URL redirect is considered only after the requested storefront route or resource returns not found, so it cannot replace a live product, page, policy, collection, or other route. Merchant-managed rows use manual for one path or prefix for a /* path family. auto_slug and system_prefix rows are generated by catalog and permalink changes; reads expose them for diagnosis, but write endpoints do not change or delete them.

Store logical paths whenever one redirect should apply across public addresses. Shared domains use /{locale}-{country} for non-primary countries; country-pinned domains use only /{locale} for secondary languages. Resolution checks the addressed path first and then the logical path with that recognized address prefix removed. External targets must use HTTPS.

Endpoints#

URL Redirect limits

GET read_redirects

Get redirect limits and current usage.

Returns live list, search, bulk-delete, merchant redirect, and prefix-rule limits. Automatic redirects are reported separately and do not consume the merchant redirect limit.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.

List URL redirects

GET read_redirects

List URL redirects for the store.

Search paths and targets or filter by kind. manual and prefix rows are merchant-managed. auto_slug and system_prefix rows explain platform-generated routing history and are read-only.

Query parameters

Name Type Description
page integer

Page number.

Default: 1
Example: 1
limit integer

Page size, bounded by the limits response.

Example: 50
search string

Search path or target.

Example: old-page
kind string

Filter by manual, prefix, auto_slug, or system_prefix.

Example: manual

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 REDIRECT_SEARCH_TOO_LONG

    The search exceeds the live maximum.
  • 400 REDIRECT_KIND_INVALID

    The kind filter is not recognized.

Get a URL redirect

GET read_redirects

Get one store-scoped URL redirect.

Returns the redirect only when it belongs to the token's store.

Path parameters

Name Type Description
redirectId required string

Redirect id.

Example: 9a7e4a90-9ac4-4aa6-aeb8-baad66d9fc37

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 404 REDIRECT_NOT_FOUND

    The redirect does not exist in this store.
  • 400 REDIRECT_ID_INVALID

    The redirect id is malformed.

Create a URL redirect

POST write_redirects

Create a manual redirect or prefix rule.

Redirects are evaluated only after a storefront route returns not found, so they cannot shadow live content. Paths use the logical storefront path. On shared domains, regional addresses use /{locale}-{country}; country-pinned domains use /{locale} for non-default languages. The runtime checks both the addressed path and its logical path. External targets must use HTTPS without URL credentials. Internal targets start with a single slash; network-path URLs and backslashes are rejected. Exact redirect chains are collapsed to their final target when saved, and cycles are rejected. Prefix rules may use a fixed target or a trailing /* target that preserves the unmatched suffix. Exact addressed and logical matches are checked before prefixes; the longest matching prefix wins and includes its base path. Paths are lowercased, repeated slashes collapsed, trailing slash removed, and query/fragment ignored. Source limits count UTF-8 bytes. Incoming query parameters survive only when the target does not specify a query; they precede any target fragment. Prefix and mixed exact/prefix loops are checked on writes, including CSV imports. The separate prefix usage count includes system prefixes.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
kind string

manual (default) or prefix.

Example: manual
path required string

Dead logical path. Prefix rules must end in /*.

Example: /old-page
target required string

Internal path or full HTTPS URL. Prefix targets may end in /*.

Example: /new-page
redirect_type integer

301 for permanent or 302 for temporary.

Example: 301

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    The request body or pagination values are invalid.
  • 400 REDIRECT_PATH_REQUIRED

    A non-empty path is required.
  • 400 REDIRECT_PATH_TOO_LONG

    The path exceeds path_max_length from the limits response.
  • 400 REDIRECT_TARGET_REQUIRED

    A non-empty target is required.
  • 400 REDIRECT_TARGET_TOO_LONG

    The target exceeds target_max_length from the limits response.
  • 400 REDIRECT_TYPE_INVALID

    redirect_type must be 301 or 302.
  • 400 REDIRECT_KIND_INVALID

    Only manual and prefix redirects can be created.
  • 400 REDIRECT_PREFIX_INVALID

    A prefix path must end with /* and contain no other wildcards.
  • 400 REDIRECT_PATH_INVALID

    The path is empty, root, contains unsupported characters, or has an invalid wildcard.
  • 400 REDIRECT_TARGET_INVALID

    The target is not an internal path or full HTTPS URL.
  • 400 REDIRECT_SELF_TARGET

    The redirect points to itself.
  • 400 REDIRECT_LOOP_DETECTED

    The change would create a redirect loop.
  • 400 REDIRECT_LIMIT_REACHED

    The merchant redirect or bulk request limit was reached.
  • 400 REDIRECT_PREFIX_LIMIT_REACHED

    The prefix-rule limit was reached.
  • 409 REDIRECT_DUPLICATE_PATH

    The store already has a redirect for this locale and path.

Update a URL redirect

PUT write_redirects

Update a merchant-managed redirect.

Omitted fields stay unchanged. Platform-generated auto_slug and system_prefix rows cannot be changed.

Path parameters

Name Type Description
redirectId required string

Redirect id.

Example: 9a7e4a90-9ac4-4aa6-aeb8-baad66d9fc37

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
path string

Dead logical path. Prefix rules must end in /*.

Example: /old-page
target string

Internal path or full HTTPS URL. Prefix targets may end in /*.

Example: /new-page
redirect_type integer

301 for permanent or 302 for temporary.

Example: 301

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 404 REDIRECT_NOT_FOUND

    The redirect does not exist in this store.
  • 400 REDIRECT_ID_INVALID

    The redirect id is malformed.
  • 400 REDIRECT_GENERATED_IMMUTABLE

    A platform-generated redirect was selected for mutation.
  • 400 INVALID_INPUT

    The request body or pagination values are invalid.
  • 400 REDIRECT_PATH_REQUIRED

    A non-empty path is required.
  • 400 REDIRECT_PATH_TOO_LONG

    The path exceeds path_max_length from the limits response.
  • 400 REDIRECT_TARGET_REQUIRED

    A non-empty target is required.
  • 400 REDIRECT_TARGET_TOO_LONG

    The target exceeds target_max_length from the limits response.
  • 400 REDIRECT_TYPE_INVALID

    redirect_type must be 301 or 302.
  • 400 REDIRECT_KIND_INVALID

    Only manual and prefix redirects can be created.
  • 400 REDIRECT_PREFIX_INVALID

    A prefix path must end with /* and contain no other wildcards.
  • 400 REDIRECT_PATH_INVALID

    The path is empty, root, contains unsupported characters, or has an invalid wildcard.
  • 400 REDIRECT_TARGET_INVALID

    The target is not an internal path or full HTTPS URL.
  • 400 REDIRECT_SELF_TARGET

    The redirect points to itself.
  • 400 REDIRECT_LOOP_DETECTED

    The change would create a redirect loop.
  • 409 REDIRECT_DUPLICATE_PATH

    The store already has a redirect for this locale and path.

Delete a URL redirect

DELETE write_redirects

Delete a merchant-managed redirect.

Platform-generated auto_slug and system_prefix rows cannot be deleted.

Path parameters

Name Type Description
redirectId required string

Redirect id.

Example: 9a7e4a90-9ac4-4aa6-aeb8-baad66d9fc37

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 404 REDIRECT_NOT_FOUND

    The redirect does not exist in this store.
  • 400 REDIRECT_ID_INVALID

    The redirect id is malformed.
  • 400 REDIRECT_GENERATED_IMMUTABLE

    A platform-generated redirect was selected for mutation.

Bulk delete URL redirects

POST write_redirects

Delete several merchant-managed redirects in one request.

The configured bulk cap is returned by the limits endpoint. The request is atomic: an invalid or platform-generated id rejects the selection without deleting the other rows. Unknown ids are ignored, duplicate ids are deleted once, and deleted reports the actual count.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
ids required array<string>

Redirect ids to delete.

Example: ["9a7e4a90-9ac4-4aa6-aeb8-baad66d9fc37"]

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 404 REDIRECT_NOT_FOUND

    The redirect does not exist in this store.
  • 400 REDIRECT_ID_INVALID

    The redirect id is malformed.
  • 400 REDIRECT_GENERATED_IMMUTABLE

    A platform-generated redirect was selected for mutation.
  • 400 INVALID_INPUT

    Send a non-empty ids array in a valid JSON body.
  • 400 REDIRECT_LIMIT_REACHED

    The request exceeds the bulk-delete limit.

Webhook events#

Subscribe to redirect events to mirror every committed create, update, and delete, including automatic chain-collapse side effects.

Redirect created

EVENT redirects/create App scope: read_redirects Staff permission: online_store.redirects:write

Fired when a URL redirect is created — manually, by a slug change, or by a permalink rename.

Payload fields

Field Type Description
redirect.id string Always present
redirect.kind string Selectable in the Payload builder
redirect.locale string Selectable in the Payload builder
redirect.path string Selectable in the Payload builder
redirect.target string Selectable in the Payload builder
redirect.redirect_type integer Selectable in the Payload builder
redirect.created_at string Selectable in the Payload builder
redirect.updated_at string Selectable in the Payload builder

Redirect updated

EVENT redirects/update App scope: read_redirects Staff permission: online_store.redirects:write

Fired when a URL redirect is updated.

Payload fields

Field Type Description
redirect.id string Always present
redirect.kind string Selectable in the Payload builder
redirect.locale string Selectable in the Payload builder
redirect.path string Selectable in the Payload builder
redirect.target string Selectable in the Payload builder
redirect.redirect_type integer Selectable in the Payload builder
redirect.created_at string Selectable in the Payload builder
redirect.updated_at string Selectable in the Payload builder

Redirect deleted

EVENT redirects/delete App scope: read_redirects Staff permission: online_store.redirects:write

Fired when a URL redirect is deleted.

Payload fields

Field Type Description
redirect.id string Always present
redirect.path string Selectable in the Payload builder

Last updated Oct 21, 2026