HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

URL Encoding

How to encode URLs to avoid errors with SKUs.

What is URL encoding?

A URL consists of only ASCII characters. Some ASCII characters have special meanings in URLs, and some others are forbidden. If you want a URL with forbidden ASCII characters or non-ASCII characters, or a URL that uses special characters without invoking their special meaning, you must encode the URL.

How do I encode a URL?

To encode a URL, convert each byte of the UTF-8 encoding of each special, forbidden, and non-ASCII character to a two-digit hexadecimal number, and place a percent sign before each of these two-digit hexadecimal numbers.

Example:

URLs do not allow the backslash (\) character. If you want to use the URI /products/pricing/v0/listings/Item\1/offers, you must escape the backslash. The hexadecimal value of \ in UTF-8 is 5C, so \ is replaced by %5C in the URI, making /products/pricing/v0/listings/Item%5C1/offers the encoded URI.

In practice, this is most often done programmatically with built-in functions available in many programming languages. Here is an example in Java:

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.io.UnsupportedEncodingException*;*

 // Method to encode a SKU using `UTF-8` encoding scheme
  private static String encodeSKU(String sSKU) {
    try {
      return URLEncoder.encode(sSKU, StandardCharsets.UTF_8.toString());
    } catch (UnsupportedEncodingException ex) {
      e*.*printStackTrace*();*
    }
  }

For more information about URL encoding, refer to RFC 3986, Section 2.1. Percent Encoding.

❗️

SKUs with commas

SP-API is unable to distinguish encoded comma (%2C) values from literal comma (,) values. This prevents SKUs with commas from being used in comma-delimited query parameters, as the commas in those SKUs cannot be distinguished from commas separating arguments.

When a comma is present in a SKU, you must search for the SKU individually.