Skip to content

Get sitemap data

GET
/public/stores/{ref}/sitemap-data
curl --request GET \
--url https://apibase.ecomweb.app/api/v1/public/stores/example/sitemap-data \
--header 'x-storefront-api-key: <x-storefront-api-key>'

Returns everything a sitemap lists in one response: published content pages, published blog posts, blog categories and tags, active collections and active products on the online store. Every list is empty while the store is coming soon. The lists currently use the merchant-side shapes of products, collections, pages and blog posts, including fields such as author_id and view_count.

ref
required
string

The store’s reference.

Media typeapplication/json
object
content_pages
required

Published content pages.

Array<object>
object
content

HTML content of the page. Null when the page has no content.

string
nullable
page_type
required

What kind of page this is.

string
Allowed values: about privacy terms faq contact shopping_guide return_policy shipping_policy warranty home_page default
deleted_at

When the page was deleted. Always null on pages you can read.

string
nullable
seo_metadata

Search engine metadata. Present only when include_seo_metadata is passed; null when the page has none.

object
meta_title
required

Page title for search engines, or null when none is set.

string
nullable
meta_description
required

Page description for search engines, or null when none is set.

string
nullable
id
required

Page ID.

number
title
required

Title of the page.

string
slug
required

URL slug, unique within the store.

string
is_published
required

Whether the page is visible on the storefront.

boolean
sort_order

Manual position among the store’s pages.

number
created_at

When the page was created, as an ISO 8601 timestamp.

string
updated_at

When the page was last updated, as an ISO 8601 timestamp.

string
is_template_content

True while the page still holds the unedited text the store was created with.

boolean
blog_posts
required

Published blog posts, newest first.

Array<object>
object
content

Post body as HTML, or null when empty.

string
nullable
toc

Table of contents generated from the headings in content.

Array<object>
nullable
object
id
required

Anchor ID of the heading.

string
level
required

Heading level, from 1 to 6.

number
textContent
required

Text of the heading.

string
pos
required

Position of the heading in the post content.

number
excerpt

Short summary shown in listings, or null.

string
nullable
featured_image_url

URL of the featured image, or null.

string
nullable
seo_metadata

SEO title and description. Present only when requested with include_seo_metadata.

object
meta_title
required

Page title for search engines, or null.

string
nullable
meta_description
required

Page description for search engines, or null.

string
nullable
status
required

Publication status. Only published posts are visible on the storefront list; unlisted posts are reachable by their link.

string
Allowed values: draft published scheduled unlisted
categories

Categories of the post.

Array<object>
object
id
required

ID.

number
name
required

Display name.

string
slug
required

URL slug, unique within the store.

string
description

Description. Present on categories only; null when none is set.

string
nullable
color

Hex colour such as #ff6600. Present on categories only; null when none is set.

string
nullable
sort_order

Manual position in the category list. Present on categories only.

number
nullable
created_at

When it was created, as an ISO 8601 timestamp.

string
nullable
updated_at

When it was last updated, as an ISO 8601 timestamp. Present on categories only.

string
nullable
tags

Tags of the post.

Array<object>
object
id
required

ID.

number
name
required

Display name.

string
slug
required

URL slug, unique within the store.

string
description

Description. Present on categories only; null when none is set.

string
nullable
color

Hex colour such as #ff6600. Present on categories only; null when none is set.

string
nullable
sort_order

Manual position in the category list. Present on categories only.

number
nullable
created_at

When it was created, as an ISO 8601 timestamp.

string
nullable
updated_at

When it was last updated, as an ISO 8601 timestamp. Present on categories only.

string
nullable
product_ids

IDs of the products recommended in the post, in display order. Present on single-post responses.

Array<number>
id
required

Post ID.

number
title
required

Title.

string
slug
required

URL slug, unique within the store.

string
is_featured

Whether the post is marked as featured.

boolean
scheduled_at

When a scheduled post will be published, as an ISO 8601 timestamp, or null.

string
nullable
published_at

When the post was published, as an ISO 8601 timestamp, or null while unpublished.

string
nullable
author_id

ID of the user who created the post, or null (for example when created with an API key).

string
nullable
author_name

Name or email of the author. Present when the author is known and, on lists, when include_author is set.

string
view_count

Number of storefront views.

number
nullable
reading_time

Estimated reading time in minutes.

number
nullable
created_at

When the post was created, as an ISO 8601 timestamp.

string
updated_at

When the post was last updated, as an ISO 8601 timestamp.

string
deleted_at

When the post was deleted, or null. Deleted posts are not returned.

string
nullable
blog_categories
required

Blog categories.

Array<object>
object
description

Description, or null.

string
nullable
color

Hex colour such as #ff6600, or null.

string
nullable
sort_order

Manual position in the category list; lower comes first.

number
nullable
id
required

Category ID.

number
name
required

Display name.

string
slug
required

URL slug, unique within the store.

string
post_count

Number of posts in the category. Present when post counts are included; always present on the paginated list.

number
created_at

When the category was created, as an ISO 8601 timestamp.

string
nullable
updated_at

When the category was last updated, as an ISO 8601 timestamp.

string
nullable
blog_tags
required

Blog tags.

Array<object>
object
id
required

Tag ID.

number
name
required

Display name.

string
slug
required

URL slug, unique within the store.

string
post_count

Number of posts with the tag. Present when post counts are included; always present on the paginated list.

number
created_at

When the tag was created, as an ISO 8601 timestamp.

string
nullable
collections
required

Active collections.

Array<object>
object
type
required

manual collections list products you choose; smart collections select products with search_criteria.

string
Allowed values: manual smart
status
required

Publication status.

string
Allowed values: draft active archived unlisted
search_criteria
required

The rules a smart collection selects products with, or null for a manual collection.

object
key
additional properties
any
facet_config
required

The facets shoppers can filter the collection by, computed by the store, or null when not yet computed.

object
key
additional properties
any
collection_sort
required

How products are ordered within the collection.

string
Allowed values: manual product_name_asc product_name_desc best_selling highest_price lowest_price newest oldest
product_ids

Product IDs of a manual collection, in display order. Not present on smart collections.

Array<number>
seo_metadata

SEO fields. Present only when include_seo_metadata is true.

object
meta_title
required

Page title for search engines, or null.

string
nullable
meta_description
required

Page description for search engines, or null.

string
nullable
id
required

Collection ID.

number
name
required

Collection name.

string
description
required

Collection description, or null.

string
nullable
image_url
required

URL of the collection image, or null.

string
nullable
slug
required

URL-friendly identifier, unique within the store.

string
generated_from_category_id
required

ID of the category this collection was generated from, or null for a collection created by hand.

number
nullable
created_at
required

When the collection was created, as an ISO 8601 timestamp.

string
updated_at
required

When the collection was last updated, as an ISO 8601 timestamp.

string
deleted_at
required

Always null; deleted collections are not returned.

string
nullable
product_count

Number of products in the collection. Present only when include_product_count is true.

number
products
required

Active products that are listed on the online store.

Array<object>
object
images
required

Product images, in display order.

Array<object>
object
id

Asset ID of the image. Omit it to have the asset looked up from url, which must then be a URL of an asset uploaded to this store.

string
url
required

Image URL: the asset’s public_url or cdn_url

string
design_id

Canva design ID

string
design_edit_url

Canva design edit URL

string
canva_asset_id

Canva asset ID

string
alt

Image alt text

string
caption

Image caption

string
sort_order

Sort order for image display

number
is_primary

Whether this is the primary image

boolean
videos
required

Product videos. Always empty unless videos are requested.

Array<object>
object
id
required

ID of the uploaded video asset

string
url
required

Video URL

string
thumbnail_url

Thumbnail URL

string
duration
required

Duration in seconds (1-300 seconds)

number
>= 1 <= 300
width

Video width in pixels

number
height

Video height in pixels

number
status

Processing status

string
Allowed values: processing active failed
sort_order

Sort order for multiple videos (future use)

number
variants

Variants. Present only when include_variants is true.

Array<object>
object
inventory_policy
required

deny rejects checkout when stock is short; continue lets stock go negative.

string
Allowed values: deny continue
dimensions
required

Package dimensions, or null.

object
key
additional properties
any
images
required

Images for this variant.

Array<object>
object
id

Asset ID of the image. Omit it to have the asset looked up from url, which must then be a URL of an asset uploaded to this store.

string
url
required

Image URL: the asset’s public_url or cdn_url

string
design_id

Canva design ID

string
design_edit_url

Canva design edit URL

string
canva_asset_id

Canva asset ID

string
alt

Image alt text

string
caption

Image caption

string
sort_order

Sort order for image display

number
is_primary

Whether this is the primary image

boolean
combinations

Attribute values that define this variant. Present only when combinations are requested.

Array<object>
object
attributes
required

The attribute (axis), or null when it no longer exists.

object
id
required

Attribute ID.

number
name
required

Attribute name, such as “Color”.

string
slug
required

URL-safe identifier of the attribute, unique within the store.

string
type
required

How values are chosen, such as select.

string
order_by
required

How the values are ordered, such as manual.

string
sort_order
required

Position of the attribute among the store’s attributes.

number
nullable
created_at
required

When the attribute was created, as an ISO 8601 timestamp.

string
updated_at
required

When the attribute was last updated, as an ISO 8601 timestamp.

string
taxonomy_attribute_code
required

Code of the global taxonomy attribute this one maps to, or null for a local attribute.

string
nullable
attribute_values
required

The chosen value, or null when it no longer exists.

object
id
required

Attribute value ID.

number
attribute_id
required

ID of the attribute this value belongs to.

number
value
required

Stored value, such as “red”.

string
display_value
required

Value as shown to shoppers, such as “Red”.

string
swatch_type
required

Swatch kind: none, color or image.

string
swatch_value
required

Swatch content: a color code or an image URL. Empty when there is no swatch.

string
sort_order
required

Position of the value within its attribute.

number
nullable
created_at
required

When the value was created, as an ISO 8601 timestamp.

string
updated_at
required

When the value was last updated, as an ISO 8601 timestamp.

string
taxonomy_value_code
required

Code of the global taxonomy value this one maps to, or null.

string
nullable
promotions

Active promotions on this variant. Present only when promotions are requested on a single product.

Array<object>
object
id
required

Promotion ID.

number
name
required

Promotion name.

string
description

Promotion description.

string
mode
required

How the promotion is applied, such as automatic or code.

string
code

Discount code, for code promotions.

string
type
required

Promotion type.

string
condition_type
required

What the promotion targets, such as product or variant.

string
discount_method

How the discount is computed, such as PERCENTAGE or FIXED_AMOUNT.

string
discount_value

Discount amount or percentage.

number
max_discount_amount

Upper bound on the discount amount.

number
fixed_price

Fixed price the item is sold at, for fixed-price promotions.

number
min_amount

Minimum order amount for the promotion to apply.

number
min_quantity

Minimum quantity for the promotion to apply.

number
start_at
required

When the promotion starts, as an ISO 8601 timestamp.

string
end_at

When the promotion ends, as an ISO 8601 timestamp.

string
promotion_price
required

Price after the promotion.

number
original_price
required

Price before the promotion.

number
discount_amount
required

Amount taken off the original price.

number
best_promotion

The promotion giving the lowest price, or null. Present only when promotions are requested on a single product.

object
id
required

Promotion ID.

number
name
required

Promotion name.

string
description

Promotion description.

string
mode
required

How the promotion is applied, such as automatic or code.

string
code

Discount code, for code promotions.

string
type
required

Promotion type.

string
condition_type
required

What the promotion targets, such as product or variant.

string
discount_method

How the discount is computed, such as PERCENTAGE or FIXED_AMOUNT.

string
discount_value

Discount amount or percentage.

number
max_discount_amount

Upper bound on the discount amount.

number
fixed_price

Fixed price the item is sold at, for fixed-price promotions.

number
min_amount

Minimum order amount for the promotion to apply.

number
min_quantity

Minimum quantity for the promotion to apply.

number
start_at
required

When the promotion starts, as an ISO 8601 timestamp.

string
end_at

When the promotion ends, as an ISO 8601 timestamp.

string
promotion_price
required

Price after the promotion.

number
original_price
required

Price before the promotion.

number
discount_amount
required

Amount taken off the original price.

number
id
required

Variant ID.

number
product_id
required

ID of the product this variant belongs to.

number
sku_id
required

Store-wide numeric SKU identifier, assigned automatically.

number
seller_sku
required

Merchant-assigned SKU, or null.

string
nullable
external_id
required

The variant’s ID in an external system, or null.

string
nullable
price
required

Selling price in the store’s currency.

number
inventory
required

Units available across all locations.

number
nullable
inventory_version
required

Counter that increases on every stock change.

number
min_stock_alert
required

Stock level at or below which the variant counts as low stock.

number
nullable
track_inventory
required

Whether stock is tracked. When false the variant never runs out.

boolean
cost_per_item

Unit cost to the store. Present only when the key holds the read:inventory scope. Null when no cost is recorded.

number
nullable
weight
required

Weight, in the store’s weight unit, or null.

number
nullable
is_default
required

Whether this is the product’s default variant.

boolean
nullable
status
required

Variant status, such as active or inactive.

string
nullable
created_at
required

When the variant was created, as an ISO 8601 timestamp.

string
updated_at
required

When the variant was last updated, as an ISO 8601 timestamp.

string
promotion_price

Price after the best active promotion. Present only when promotions are requested; null when none applies.

number
nullable
_count

Related counts. Present only when include_counts is true.

object
variants
required

Number of variants.

number
seo_metadata

SEO metadata, or null when none is set. Present only when include_seo_metadata is true.

object
meta_title
required

Page title for search engines, or null.

string
nullable
meta_description
required

Page description for search engines, or null.

string
nullable
product_attributes

Attributes linked to the product, with their selected values. Present only when include_attributes is true.

Array<object>
object
key
additional properties
any
tags

Tags on the product. Present only when include_tags is true.

Array<object>
object
id
required

Tag ID.

number
name
required

Tag name.

string
slug
required

URL-safe tag identifier.

string
created_at
required

When the tag was created, as an ISO 8601 timestamp.

string
updated_at
required

When the tag was last updated, as an ISO 8601 timestamp.

string
channels

Sales channels the product is published to. Present only when include_channels is true.

Array<object>
object
code
required

Channel code, such as online_store.

string
is_listed
required

Whether the product is listed (visible in listings) on this channel.

boolean
published_at
required

When the product was published to the channel, as an ISO 8601 timestamp, or null.

string
nullable
promotions

Active promotions on the product. Present only when include_promotion is true on a single product.

Array<object>
object
id
required

Promotion ID.

number
name
required

Promotion name.

string
description

Promotion description.

string
mode
required

How the promotion is applied, such as automatic or code.

string
code

Discount code, for code promotions.

string
type
required

Promotion type.

string
condition_type
required

What the promotion targets, such as product or variant.

string
discount_method

How the discount is computed, such as PERCENTAGE or FIXED_AMOUNT.

string
discount_value

Discount amount or percentage.

number
max_discount_amount

Upper bound on the discount amount.

number
fixed_price

Fixed price the item is sold at, for fixed-price promotions.

number
min_amount

Minimum order amount for the promotion to apply.

number
min_quantity

Minimum quantity for the promotion to apply.

number
start_at
required

When the promotion starts, as an ISO 8601 timestamp.

string
end_at

When the promotion ends, as an ISO 8601 timestamp.

string
promotion_price
required

Price after the promotion.

number
original_price
required

Price before the promotion.

number
discount_amount
required

Amount taken off the original price.

number
best_promotion

The promotion giving the lowest price, or null. Present only when include_promotion is true on a single product.

object
id
required

Promotion ID.

number
name
required

Promotion name.

string
description

Promotion description.

string
mode
required

How the promotion is applied, such as automatic or code.

string
code

Discount code, for code promotions.

string
type
required

Promotion type.

string
condition_type
required

What the promotion targets, such as product or variant.

string
discount_method

How the discount is computed, such as PERCENTAGE or FIXED_AMOUNT.

string
discount_value

Discount amount or percentage.

number
max_discount_amount

Upper bound on the discount amount.

number
fixed_price

Fixed price the item is sold at, for fixed-price promotions.

number
min_amount

Minimum order amount for the promotion to apply.

number
min_quantity

Minimum quantity for the promotion to apply.

number
start_at
required

When the promotion starts, as an ISO 8601 timestamp.

string
end_at

When the promotion ends, as an ISO 8601 timestamp.

string
promotion_price
required

Price after the promotion.

number
original_price
required

Price before the promotion.

number
discount_amount
required

Amount taken off the original price.

number
review_stats

Review statistics. Present only when include_review_stats is true.

object
key
additional properties
any
services

Services attached to the product. Present only when include_services is true.

Array<object>
object
key
additional properties
any
id
required

Product ID.

number
name
required

Product name.

string
slug
required

URL slug, unique within the store.

string
nullable
description
required

Product description, or null.

string
nullable
status
required

Lifecycle status: draft, active or unlisted.

string
nullable
published_at
required

When the product was published, as an ISO 8601 timestamp, or null.

string
nullable
created_at
required

When the product was created, as an ISO 8601 timestamp.

string
updated_at
required

When the product was last updated, as an ISO 8601 timestamp.

string
deleted_at
required

When the product was soft-deleted, as an ISO 8601 timestamp. Null for live products.

string
nullable
category_code
required

Code of the global taxonomy category, or null.

string
nullable
taxonomy_release
required

Taxonomy release the category was assigned from, or null.

string
nullable
product_type
required

Free-text product type, or null.

string
nullable
is_featured
required

Whether the product is featured.

boolean
nullable
min_price
required

Lowest variant price.

number
nullable
max_price
required

Highest variant price.

number
nullable
variant_mode
required

simple for a single-variant product, variant when it has options.

string
external_id
required

The product’s ID in an external system, or null.

string
nullable
total_inventory

Total stock across all variants. Present on reads.

number
min_promotion_price

Lowest price after promotions, or null. Present only when include_promotion is true on a single product.

number
nullable
max_promotion_price

Highest price after promotions, or null. Present only when include_promotion is true on a single product.

number
nullable

Example

{
"content_pages": [
{
"page_type": "about"
}
],
"blog_posts": [
{
"status": "draft"
}
],
"collections": [
{
"type": "manual",
"status": "draft",
"collection_sort": "manual"
}
],
"products": [
{
"images": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/image.jpg",
"design_id": "DABCdefg123",
"design_edit_url": "https://canva.com/design/edit/123",
"canva_asset_id": "asset123",
"alt": "Product image",
"caption": "Main product view",
"sort_order": 1,
"is_primary": true
}
],
"videos": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://cdn.example.com/videos/product-demo.mp4",
"thumbnail_url": "https://cdn.example.com/thumbnails/product-demo-thumb.jpg",
"duration": 30,
"width": 1280,
"height": 720,
"status": "processing",
"sort_order": 0
}
],
"variants": [
{
"inventory_policy": "deny",
"images": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/image.jpg",
"design_id": "DABCdefg123",
"design_edit_url": "https://canva.com/design/edit/123",
"canva_asset_id": "asset123",
"alt": "Product image",
"caption": "Main product view",
"sort_order": 1,
"is_primary": true
}
]
}
]
}
]
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The resource does not exist in this store.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}