LogoLogo
Build appsContact API support
  • Build apps
  • Site Templates
  • API Reference
  • Changelog
  • REST API
    • REST API overview
    • Store Profile
      • Get store profile
      • Update store profile
      • Upload store logo image
      • Delete store logo image
      • Store reports
        • Get store reports
        • Get latest store update stats
        • Get deleted items history
    • Orders
      • Search orders
      • Get order
      • Get last order
      • Calculate order details
      • Update order
      • Create order
      • Delete order
      • Get repeat order URL
      • Order invoices
        • Get order receipt PDF
        • Get tax invoices for order
        • Generate tax invoice for order
      • Order statuses
        • Search order statuses
        • Get order status
        • Update custom order status
      • Order extra fields
        • Search order extra fields
        • Update order extra field
        • Add extra fields to order
        • Delete order extra field
      • Abandonned carts
        • Search abandoned carts
        • Get abandoned cart
        • Update abandoned cart
        • Convert abandoned cart to order
      • Recurring subscriptions
        • Search recurring subscriptions
        • Get recurring subscription
        • Update recurring subscription
    • Products
      • Search products
      • Get product
      • Update product
      • Create product
      • Delete product
      • Delete all products
      • Adjust product stock
      • Get product filters
      • Get recently used product swatches
      • Search product brands
      • Product images and videos
        • Upload main product image
        • Upload main product image (async)
        • Upload gallery product image
        • Upload gallery product image (async)
        • Delete main product image
        • Delete gallery product image
        • Delete all gallery product images
        • Upload main product video
        • Upload gallery product video
        • Upload cover for gallery video
        • Delete main product video
        • Delete gallery product video
        • Download gallery product video
        • Bulk update product images and videos
      • Product files
        • Upload product file
        • Download product file
        • Delete product file
        • Delete all product files
        • Change product file description
      • Product variations
        • Search product variations
        • Get product variation
        • Update product variation
        • Create product variation
        • Delete product variation
        • Delete all product variations
        • Adjust product variation stock
        • Upload product variation image
        • Upload product variation image (async)
        • Delete product variation image
      • Product types and attributes
        • Search product types
        • Get product type
        • Update product type and attributes
        • Create product type
        • Delete product type
      • Product reviews
        • Search product reviews
        • Get product reviews stats
        • Update product review status
        • Bulk update/delete product reviews
        • Delete product review
    • Categories
      • Search categories
      • Search categories by path
      • Get category
      • Update category
      • Create category
      • Delete category
      • Category images
        • Upload category image
        • Upload category image (async)
        • Delete category image
      • Manage order of categories in the store
        • Get order of categories
        • Update order of categories
      • Manage order of products in the category
        • Get order of products
        • Update order of products
        • Assign products to the category
        • Unassign products from the category
    • Customers
      • Search customers
      • Get customer
      • Update customer
      • Create customer
      • Delete customer
      • Customer groups
        • Search customer groups
        • Get customer group
        • Update customer group name
        • Create customer group
        • Delete customer group
      • Customer contacts
        • Search customer contacts
        • Get customer contact
        • Update customer contact
        • Create customer contact
        • Delete customer contact
      • Customer extra fields
        • Search customer extra fields
        • Get customer extra field
        • Update customer extra field
        • Create customer extra field
        • Delete customer extra field
    • Discounts
      • Promotions
        • Search promotions
        • Update promotion
        • Create promotion
        • Delete promotion
      • Discount coupons
        • Search discount coupons
        • Get discount coupon
        • Update discount coupon
        • Create discount coupon
        • Delete discount coupon
    • Domains
      • Search store domains
      • Update store domains
      • Search domains for purchase
      • Purchase domain
      • Send domain verification email
      • Reset domain password
    • Dictionaries
      • Country codes
      • Currency codes
      • Currency codes by country
      • State codes by country
      • Tax classes by country
    • Staff accounts
      • Search staff accounts
      • Get staff account
      • Get staff account scopes
      • Update staff account
      • Create staff account
      • Delete staff account
      • Resend staff account invite
      • Cancel staff account invite
    • Application
      • Get app subscription status
      • Cancel app subscription
      • Get all app storage data
      • Get specific app storage data
      • Update specific app storage data
      • Delete specific app storage data
      • Add app storage data
      • Custom charge with Ecwid billing
    • Batch requests
      • Create batch request
      • Get batch status
      • Search batch requests by status
      • Stop batch request
      • Stop and delete batch request
    • Shipping options
      • Search shipping options
      • Update shipping option
      • Create shipping option
      • Delete shipping option
    • Payment options
      • Search payment options
      • Get payment option
      • Update payment option
      • Create payment option
      • Delete payment option
    • Checkout extra fields
      • Add checkout extra fields with JavaScript
      • Manage checkout extra fields with REST API
        • Search checkout extra fields
        • Get checkout extra field
        • Update checkout extra field
        • Create checkout extra field
        • Delete checkout extra field
    • Storefront widget details
      • Get page slug and static code
      • Set base URL for storefront widgets
      • Optimize custom website SEO with better URLs
        • Enable Clean Store URLs on a custom website
        • Set Custom Page Slugs on a custom website
      • Dynamic loading for storefront widget
      • SSO (Single-Sign-On) for websites
        • Add SSO to the website
        • Customize SSO on the website
        • SSO code examples
      • Static store pages
        • Static code for home page
        • Static code for category page
        • Static code for product page

Lightspeed® 2025

On this page
  • Requirements for Custom Page Slugs
  • Step 1. Enable Clean Store URLs.
  • Step 2. Set custom slugs with REST API
  • How to find products and categories by their slugs
  • Still have questions?

Was this helpful?

  1. REST API
  2. Storefront widget details
  3. Optimize custom website SEO with better URLs

Set Custom Page Slugs on a custom website

Last updated 5 days ago

Was this helpful?

Custom Page Slugs feature allows you to set custom URLs for product and category pages to enhance website SEO and make the customer experience more engaging. For example, you can simplify a product named "BRAND Football ball R15 New" with a product URL from https://example-shop.com/store/brand-football-ball-r15-new to a URL like https://example-foolball-shop.com/store/ball-r15 instead of it containing a full product name.

Read more about

Requirements for Custom Page Slugs

Custom Page Slugs are automatically enabled if:

  • Your store is on the .

  • Your website has .

Step 1. Enable Clean Store URLs.

To set custom slugs, Clean Store URLs must be enabled on your custom website.

If you use Ecwid Instant Site, you can skip this step as the Clean Store URLs feature is enabled out of the box.

Once Clean Store URLs are enabled, set custom slugs for product and category pages in the Ecwid admin panel (supported for Instant Site only) or via the REST API. Learn about

Step 2. Set custom slugs with REST API

With the Ecwid REST API, you can set custom slugs for both new and existing products or categories:

  • Existing Products/Categories: Use the Update product and Update category endpoints.

  • New Products/Categories: Use the Create product and Create category endpoints.

Each request requires the product or category ID. If you do not know it, you can find it by the slug itself using REST API. Learn more about

In all endpoints listed above, information related to product/category page slugs is stored in the following fields:

{
	"url": "https://example.com/store/Shoes-p123",
	"autogeneratedSlug": "shoes-p123",
	"customSlug": ""
}

Where:

  • url is the actual storefront URL for the product/category. It is generated from the main store URL and a page slug. If a custom slug exists for the product/category, Ecwid will always use it to generate url field value.

  • autogeneratedSlug is a default page slug Ecwid generates automatically when the product/category is created or its name is updated.

  • customSlug is a user-defined custom page slug for the product or category page. It has a higher priority than the autogeneratedSlug field and therefore overrides it if not empty.

Custom slugs are not updated automatically. If you change the name of a product or category, Ecwid will not update the customSlug field automatically. Table with logic for slug-related fields in products and categories:

Field

Automatically updated when the product name is changed (customSlug is empty)

Automatically updated when the product name is changed (customSlug has value)

Automatically updated when customSlug is changed

url

Yes

No

Yes

autogeneratedSlug

Yes

Yes

No

customSlug

n/a

No

Yes (manual update)

Find update request examples below.

Example: update product name and its custom page slug

PUT /api/v3/STOREID/products/689454040 HTTP/1.1
Host: app.ecwid.com
Authorization: Bearer SECRET_TOKEN
Content-Type: application/json

{
    "name": "Best Pizza",
    "customSlug": "best-pizza"
}
{
    "updateCount": 1
}

It is possible to update the custom slug without updating the name and vice versa. However, we recommend updating custom slug value when the name is changed.

The "updateCount": 1 in the response body means that Ecwid successfully updated 1 product. You'll see an error message otherwise.

Example: update category name and its custom page slug

PUT /api/v3/STOREID/category/10038652 HTTP/1.1
Host: app.ecwid.com
Authorization: Bearer SECRET_TOKEN
Content-Type: application/json

{
    "name": "Fresh vegetables",
    "customSlug": "vegetables"
}
{
    "updateCount": 1
}

It is possible to update the custom slug without updating the name and vice versa. However, we recommend updating custom slug value when the name is changed.

The "updateCount": 1 in the response means that Ecwid successfully updated 1 category. You'll see an error message otherwise.

How to find products and categories by their slugs

This request accepts page slug as a search parameter and responds with product or category ID, page slug details, and static code data for the page. The method works with any slug value that ever worked on the storefront including partial URLs, and the history of slug changes.

Let's take a look at the following example of a product example where the product name remains the same (Pizza), but the default page slug has been changed two times:

/products/Pizza-p689454040 -> /products/best-pizza -> /products/pizza

/products/Pizza-p689454040 was the default page slug, generated by Ecwid upon product creation. /products/best-pizza was the first custom page slug that was changed later to another custom slug. /products/pizza is the actual custom slug, currently working on the storefront. Both previous slugs do not work on the storefront now.

  • Search by partial URL with only product ID: ?slug=-p689454040

GET /api/v3/STOREID/storefront-widget-pages?slug=-p689454040 HTTP/1.1
Host: app.ecwid.com
Authorization: Bearer SECRET_TOKEN
{
    "status": "NONCANONICAL",
    "type": "PRODUCT",
    "canonicalSlug": "pizza",
    "storeEntityData": {
        "id": "689454040"
    }
}
  • Search by partial URL with only product name: ?slug=Pizza

GET /api/v3/STOREID/storefront-widget-pages?slug=Pizza HTTP/1.1
Host: app.ecwid.com
Authorization: Bearer SECRET_TOKEN
{
    "status": "NONCANONICAL",
    "type": "PRODUCT",
    "canonicalSlug": "pizza",
    "storeEntityData": {
        "id": "689454040"
    }
}
  • Search by default page slug: ?slug=Pizza-p689454040

GET /api/v3/STOREID/storefront-widget-pages?slug=Pizza-p689454040 HTTP/1.1
Host: app.ecwid.com
Authorization: Bearer SECRET_TOKEN
{
    "status": "NONCANONICAL",
    "type": "PRODUCT",
    "canonicalSlug": "pizza",
    "storeEntityData": {
        "id": "689454040"
    }
}
  • Search by partial URL of a custom slug (and the actual custom slug): ?slug=pizza

GET /api/v3/STOREID/storefront-widget-pages?slug=pizza HTTP/1.1
Host: app.ecwid.com
Authorization: Bearer SECRET_TOKEN
{
    "status": "OK",
    "type": "PRODUCT",
    "canonicalSlug": "pizza",
    "storeEntityData": {
        "id": "689454040"
    }
}
  • Search by slug history: ?slug=pizza-test

GET /api/v3/STOREID/storefront-widget-pages?slug=best-pizza HTTP/1.1
Host: app.ecwid.com
Authorization: Bearer SECRET_TOKEN
{
    "status": "NONCANONICAL",
    "type": "PRODUCT",
    "canonicalSlug": "pizza",
    "storeEntityData": {
        "id": "689454040"
    }
}

Still have questions?

You can update the product name and its custom page slug using request:

You can update the category name and its custom page slug using request:

The default approach to finding a product or category ID requires knowing the name, description, or SKU of said product or category. However, you can get these IDs much easier by using page slug as a search term with a dedicated .

Let's find the page with different slug values using :

All these options respond with the product ID allowing you to change its slug. However, you can use the same request to also receive static page code.

with all the details that might help: your store ID, website URL and platform, server rewrite rules, and product/category ID with custom slugs. We are here to assist!

Update product
Update category
GET request
Get page slug
Learn more
Email us
URL features for custom websites
Business or Unlimited plan
Clean URLs enabled
setting custom slugs through Ecwid admin
finding products and categories by slugs