encode_uri

Encodes a URI by replacing special characters with their UTF-8 percent-encoded equivalents. Preserves characters that are valid in URIs (like :, /, ?, #, &, =).

{% assign url = "https://example.com/search?q=hello world&category=shoes" %}
{% log url | encode_uri %}

Output:

https://example.com/search?q=hello%20world&category=shoes

Syntax

{{ url | encode_uri }}
{{ string | encode_uri }}

Parameter	Description
url	The URL or string to encode

Characters Preserved vs Encoded

Preserved (not encoded)	Encoded
A-Z a-z 0-9	Spaces → %20
- _ . ! ~ * ' ( )	" → %22
; , / ? : @ & = + $ #	< > → %3C %3E
	{ } → %7B %7D
	Non-ASCII → %XX

Examples

Encode URL with spaces:

{% assign product_name = "Blue Running Shoes" %}
{% assign search_url = "https://store.com/search?q=" | append: product_name | encode_uri %}

{% log search_url %}

Output:

https://store.com/search?q=Blue%20Running%20Shoes

Build API URL with parameters:

{% assign base_url = "https://api.example.com/products" %}
{% assign query = "summer collection 2024" %}
{% assign full_url = base_url | append: "?search=" | append: query | encode_uri %}

{% http url: full_url as response %}

Encode redirect URL:

{% assign return_url = shop.url | append: "/pages/thank-you?order=" | append: order.name %}
{% assign encoded_return = return_url | encode_uri %}
{% assign checkout_url = "https://checkout.example.com?return=" | append: encoded_return %}

{% log checkout_url %}

Handle international characters:

{% assign city = "München" %}
{% assign url = "https://store.com/locations/" | append: city | encode_uri %}

{% log url %}

Output:

https://store.com/locations/M%C3%BCnchen

Encode tracking URL:

{% assign tracking_url = "https://carrier.com/track?id=" | append: fulfillment.tracking_number | append: "&name=" | append: customer.name | encode_uri %}

{% log "Tracking URL: " | append: tracking_url %}

Build webhook callback URL:

{% assign callback_data = order.id | append: "|" | append: order.email %}
{% assign callback_url = "https://myapp.com/webhook?data=" | append: callback_data | encode_uri %}

{% json webhook_payload %}
  {
    "callback_url": "{{ callback_url }}"
  }
{% endjson %}

Encode file path in URL:

{% assign file_name = "Report Q1 2024 (Final).pdf" %}
{% assign download_url = "https://cdn.example.com/files/" | append: file_name | encode_uri %}

{% log download_url %}

Output:

https://cdn.example.com/files/Report%20Q1%202024%20(Final).pdf

Create mailto link:

{% assign subject = "Order Inquiry: " | append: order.name %}
{% assign body = "Hi, I have a question about my order " | append: order.name %}
{% assign mailto = "mailto:[e-mail]?subject=" | append: subject | append: "&body=" | append: body | encode_uri %}

<a href="{{ mailto }}">Contact Support</a>

encode_uri vs url_encode

Filter	Use Case	Encodes
encode_uri	Full URLs	Preserves : / ? # & =
url_encode	Query parameter values	Encodes everything including & =

Example difference:

{% assign value = "hello&world=test" %}

{{ value | encode_uri }}
{% comment %} Output: hello&world=test (& and = preserved) {% endcomment %}

{{ value | url_encode }}
{% comment %} Output: hello%26world%3Dtest (& and = encoded) {% endcomment %}

When to use which:

{% comment %} Use encode_uri for complete URLs {% endcomment %}
{% assign full_url = "https://api.com/search?q=hello world" | encode_uri %}

{% comment %} Use url_encode for individual parameter values {% endcomment %}
{% assign param_value = "hello&world" | url_encode %}
{% assign url = "https://api.com/search?q=" | append: param_value %}

Common Use Cases

Use Case	Example
Search URLs	`"/search?q="
Redirect URLs	Encode return URLs for OAuth flows
API requests	Encode URLs with dynamic parameters
Tracking links	Encode customer/order data in URLs
File downloads	Encode file names with spaces/special chars

Notes

• Uses JavaScript's native encodeURI() function

• Preserves URI structure characters (:, /, ?, #, &, =, etc.)

• For encoding individual query parameter values, consider url_encode instead

• Handles UTF-8 characters (international text) correctly

• Safe to call multiple times (already-encoded characters won't be double-encoded)

• See also: url_encode for encoding query parameter values