Storefront API URL Resolution

The URL Resolution API translates between addresses and shop resources, in both directions. urls/identify answers the question of which page should be displayed for a requested address and is therefore the entry point for the routing of your own storefront. urls/product and urls/category go the opposite way and return the matching address for a known ID, for example to generate links in lists and navigations. A typical flow is: the storefront passes the requested address to urls/identify, receives the page type and ID in return, and then loads the contents via the Catalog API. Which subshop responds is determined by the domain the calls are made against. More on this under Storefront API Basics. Since SEO URLs are maintained per subshop, the same address returns different results in different subshops.

The endpoints on this page do not require an x-session header. Sending the header anyway does no harm.

Supported methods

List of all supported methods.

Command	Endpoints	GET	PUT	POST	DELETE
Map an address to a page type	`urls/identify`
Determine the URL of a product	`urls/product`
Determine the URL of a category	`urls/category`

The endpoints respond to all other HTTP methods with 404 Not Found.

Methods for URL resolution

GET urls/identify

The following call maps an incoming address to a shop resource. The response tells you which page type to render, which resource to load for it, and whether a redirect should happen instead. The endpoint is intended for storefronts that handle routing themselves. The storefront passes in the address requested by the visitor and, based on the response, decides whether to deliver a product page, a category page, a redirect, or a 404 page. Example request

GET https://<your-shop>.de/api/v1/urls/identify?url=/herren/schuhe/sneaker

Parameter overview

Parameter	Type	Description
`url`	string	Required field The requested path, URL-encoded. The start page is passed as `/`. Additional query parameters are rejected with `invalidParameters`.

The matching is done character by character against the stored SEO URLs. A differing trailing slash or differing upper / lower case therefore leads to 404 Not Found. A query string included in the value of url also leads to 404 Not Found. Additional query parameters on the endpoint itself, in contrast, are rejected with 400 invalidParameters. Pass only the path, with a leading slash and without a query string.

Response fields

Field	Type	Description
`found`	bool	`true` if the address could be mapped to a resource. `false` means the address is known to the shop but the resource no longer exists. In this case, `redirect` contains the redirect target.
`type`	string	Page type, see the following table.
`id`	string	Optional Identifier of the resource used to load the page data afterwards. For `Startpage`, the field is omitted.
`redirect`	string	Optional Path to redirect to. The field is only present if a redirect should happen.

Page types

Type	Content of `id`	Description
`Product`	Product ID	Product page. The data is loaded via `catalog/product/load`.
`Category`	Category ID	Category page. The data is loaded via `catalog/category/load`.
`View`	Template path	Template page with its own SEO URL, for example `content/gtc.htm`. This is not a catalog ID; the page is not loaded via the Catalog API.
`Startpage`	omitted	Start page of the shop. Only returned for `url=/`.

The value of type is the identifier of the responsible view controller. If the shop uses additional page types with their own SEO URLs, their identifiers can also appear. Therefore, catch unknown values and output your own 404 page in that case.

Responses at a glance

Situation	HTTP	`found`	`redirect`	Recommended reaction
Address is the current address of an existing resource	200	`true`	omitted	Build the page as usual
Address is an old address of the same resource	200	`true`	current address	301 to `redirect`
Resource deleted, a redirect target is stored in the shop	200	`false`	redirect target	301 to `redirect`
Resource deleted or deactivated, no redirect target stored	200	`true`	omitted	Loading fails, output your own 404 page
Address is unknown to the shop	404	omitted	omitted	Output your own 404 page

Example response: existing resource

{
  "found": true,
  "type": "Product",
  "id": "146-78608"
}

Example response: start page

{
  "found": true,
  "type": "Startpage"
}

Example response: template page

{
  "found": true,
  "id": "content/gtc.htm",
  "type": "View"
}

Example response: old address of the same resource

{
  "found": true,
  "type": "Product",
  "id": "146-78608",
  "redirect": "/herren/schuhe/sneaker-air-146-78608"
}

The shop keeps multiple SEO URLs for a resource. If the generated path changes, for example due to a renaming, a category change, or a manually set URL, the new address becomes the current address. The previous one remains as an old address and is not deleted, so that bookmarks and search engine hits keep working. To prevent both addresses from permanently delivering the same content, the storefront should redirect to the current address here. The resource itself still exists unchanged; type and id describe it correctly.

Example response: deleted resource with redirect target

{
  "found": false,
  "type": "Product",
  "id": "146-78608",
  "redirect": "/herren/schuhe"
}

In this case, type and id describe the resource that no longer exists. They must not be used to load page data; only redirect can be evaluated here.

Example response: unknown address

HTTP/1.1 404 Not Found

The response body is empty.

Evaluation in the storefront

Evaluate the response in this order:

HTTP status 404: The address is unknown to the shop. Output your own 404 page.
Field redirect present: Redirect to this value, recommended with status 301. This applies both to old addresses and to deleted resources. Therefore, check redirect before found.
No redirect, found is true: Build the page as usual. type determines the page type, id is the resource for the subsequent call to catalog/product/load or catalog/category/load.
The load call comes back empty: The resource is deactivated or deleted without a redirect target being stored. Output your own 404 page.

If a visitor requests an old address of a resource that has since been deleted, the redirect to the current address takes effect first. Only the follow-up call returns found: false with the stored redirect target. In this case, two redirects happen in succession.

found: true means that the address can be resolved, not that the resource can be delivered. A deactivated product without a stored redirect target returns found: true. The storefront must detect this case itself by checking the result of the subsequent load call.

Structure of the `redirect` field

redirect is always a path and starts with /; it is not an absolute URL. The value can be set directly as the Location header. Two forms are possible:

an SEO URL of the target, for example /herren/schuhe
a technical shop URL if no SEO URL exists for the target, for example /?wsvc=Category&id=135-98530

Both forms are resolved by the shop and can be used unchanged.

Prerequisite for redirects of deleted resources

A redirect target for a deleted resource is only output if redirectToParentCategory is active in the shop. The default is active, see urls.redirects. If the option is deactivated, a deleted resource behaves like a resource without a stored target.

Error codes

Code	HTTP	Description
`invalidParameters`	400	`url` is missing, is not a string, or additional query parameters were passed. The body contains the list of rejected parameters.

GET urls/product

The following call returns the address of a product. Use it to generate links to product pages in lists, search results, or recommendations without having to replicate the shop’s URL scheme in the storefront. Example request

GET https://<your-shop>.de/api/v1/urls/product?productId=146-78608

Parameter overview

Parameter	Type	Description
`productId`	string	Required field ID of the product. Additional query parameters are rejected with `invalidParameters`.

Example response

{
  "url": "/herren/schuhe/sneaker-air-146-78608"
}

The current SEO URL of the product is returned as a path. If no SEO URL exists for the product, it is the technical shop URL.

Status codes

If the product cannot be loaded, the endpoint responds with 404 Not Found and an empty body. If productId is missing or additional query parameters were passed, the endpoint responds with 400 Bad Request and the error code invalidParameters.

GET urls/category

The following call returns the address of a category, for example for building the navigation or breadcrumbs. Example request

GET https://<your-shop>.de/api/v1/urls/category?categoryId=135-98530

Parameter overview

Parameter	Type	Description
`categoryId`	string	Required field ID of the category. Additional query parameters are rejected with `invalidParameters`.

Example response

{
  "url": "/herren/schuhe"
}

The current SEO URL of the category is returned as a path. If no SEO URL exists, it is the technical shop URL.

Status codes

If the category cannot be loaded, the endpoint responds with 404 Not Found and an empty body. If categoryId is missing or additional query parameters were passed, the endpoint responds with 400 Bad Request and the error code invalidParameters.

Further links

Storefront API Basics - Base URL, subshop selection via the domain, session handling, and error format.
Storefront API Catalog - Load product and category data for the determined ID.
urls - URL (web addresses) - Structure of the SEO URLs and behavior for addresses that are no longer valid.
Storefront API Session Handling - Handing the session over to a template page.

Interfaces

Admin Interface API

Storefront API

More

Supported methods

Methods for URL resolution

GET urls/identify

Parameter overview

Response fields

Page types

Responses at a glance

Example response: existing resource

Example response: start page

Example response: template page

Example response: old address of the same resource

Example response: deleted resource with redirect target

Example response: unknown address

Evaluation in the storefront

Structure of the `redirect` field

Prerequisite for redirects of deleted resources

Error codes

GET urls/product

Parameter overview

Example response

Status codes

GET urls/category

Parameter overview

Example response

Status codes

Further links

​Supported methods

​Methods for URL resolution

​GET urls/identify

​Parameter overview

​Response fields

​Page types

​Responses at a glance

​Example response: existing resource

​Example response: start page

​Example response: template page

​Example response: old address of the same resource

​Example response: deleted resource with redirect target

​Example response: unknown address

​Evaluation in the storefront

​Structure of the redirect field

​Prerequisite for redirects of deleted resources

​Error codes

​GET urls/product

​Parameter overview

​Example response

​Status codes

​GET urls/category

​Parameter overview

​Example response

​Status codes

​Further links

Supported methods

Methods for URL resolution

GET urls/identify

Parameter overview

Response fields

Page types

Responses at a glance

Example response: existing resource

Example response: start page

Example response: template page

Example response: old address of the same resource

Example response: deleted resource with redirect target

Example response: unknown address

Evaluation in the storefront

Structure of the `redirect` field

Prerequisite for redirects of deleted resources

Error codes

GET urls/product

Parameter overview

Example response

Status codes

GET urls/category

Parameter overview

Example response

Status codes

Further links