Blog Categories

Blog Categories require blog scopes. Reads use read_blog; writes use write_blog. Blog Categories support name, slug, description, seo_title, seo_description, and template_handle fields. slug is optional on create and generated from the name when omitted; on update, a supplied slug must be non-empty and valid. On create, omitting template_handle assigns default_blog_category. Use default_blog_category for the default Blog Category template, or pass an alternate Blog Category template handle configured for the store. Omit template_handle on update to leave the current assignment unchanged; an empty string is invalid. Deleting a blog category assigned to blog posts is blocked until those posts are moved or unassigned. AI translation is not exposed through the Store API.

Endpoints#

Blog Category limits

GET read_blog

Fetch Blog Category limits and per-field constraints.

Returns the per-field maximum lengths and request caps that apply to Blog Category endpoints. Useful for clients to validate inputs before sending them and to size UIs.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

List blog categories

GET read_blog

List blog categories for the store.

Returns paginated Blog Categories. Use search to filter by name or slug. Invalid page or limit values are rejected; unsupported sort values fall back to the service's stable default ordering.

Query parameters

Name Type Description
page integer

Page number.

Example: 1
limit integer

Page size.

Example: 20
search string

Search Blog Categories by name or slug.

Example: company-news
sort_by string

Sort field from the Blog Category list contract.

Allowed values
namepost_countcreated_atupdated_at
Example: name
sort_direction string

Sort direction from the Blog Category list contract.

Allowed values
ascdesc
Example: asc

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 VALIDATION_LIST_INVALID_PAGE

    page must be a positive integer.

  • 400 VALIDATION_LIST_INVALID_LIMIT

    limit must be a positive integer within the contract cap.

  • 400 BLOG_CATEGORY_SEARCH_TOO_LONG

    Search exceeds the Blog Category contract max length.

Get a blog category

GET read_blog

Fetch one blog category by id.

Returns the Blog Category if it belongs to the token's store.

Path parameters

Name Type Description
id required uuid

Blog Category id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_CATEGORY_ID

    Blog Category id is not a valid UUID.

  • 404 NOT_FOUND

    Blog Category does not exist in this store.

Create a blog category

POST write_blog

Create a blog category.

Creates a Blog Category. name is required. slug is optional on create; when omitted or empty, the backend generates it from the name. Optional SEO and template fields follow the Blog Category resource contract.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name required string

Blog Category name.

Example: Company News
slug string

Optional slug. Omit to generate from name.

Example: company-news
description string

Optional plain-text description.

Example: Updates and announcements from the company.
seo_title string

Optional SEO title.

Example: Company News
seo_description string

Optional SEO description.

Example: Read company updates, product notes, and announcements.
template_handle string

Template assignment. On create, omitting this field or sending an empty string assigns default_blog_category. Use default_blog_category for the default Blog Category template, or pass an alternate Blog Category template handle configured for the store. On update, omit template_handle to leave the assignment unchanged, use default_blog_category to reset it to default, and do not send an empty string.

Example: default_blog_category

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.

  • 400 BLOG_CATEGORY_NAME_REQUIRED

    Name is empty after normalization.

  • 400 BLOG_CATEGORY_NAME_EMPTY

    A provided update name is empty after normalization.

  • 400 BLOG_CATEGORY_NAME_TOO_LONG

    Name exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_SLUG_REQUIRED

    Slug is empty on update. Blank slug auto-generation is only available on create.

  • 400 BLOG_CATEGORY_SLUG_FORMAT

    Slug is not valid for Blog Category URLs.

  • 400 BLOG_CATEGORY_SLUG_TOO_LONG

    Slug exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_SLUG_GENERATION_FAILED

    A slug could not be generated from the supplied name.

  • 400 BLOG_CATEGORY_UNIQUE_SLUG_GENERATION_FAILED

    A unique generated slug could not be found; supply a slug explicitly.

  • 400 BLOG_CATEGORY_DESCRIPTION_TOO_LONG

    Description exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_SEO_TITLE_TOO_LONG

    SEO title exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_SEO_DESCRIPTION_TOO_LONG

    SEO description exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_LIMIT_REACHED

    Store Blog Category cap has been reached.

  • 400 TEMPLATE_HANDLE_INVALID

    Template handle is not valid for Blog Category templates.

  • 400 TEMPLATE_HANDLE_NOT_FOUND

    Template handle does not exist on the store's primary active theme for Blog Category.

  • 409 BLOG_CATEGORY_DUPLICATE

    Name or slug already exists in this store.

Update a blog category

PUT write_blog

Update a blog category.

Updates provided Blog Category fields. Omitted fields are left unchanged. When slug is provided it must be non-empty and valid; create is the only path that auto-generates a blank slug from the name.

Path parameters

Name Type Description
id required uuid

Blog Category id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
name string

Blog Category name.

Example: Company News
slug string

New slug. Omit to leave the current slug unchanged; an empty value is invalid.

Example: company-news
description string

Optional plain-text description.

Example: Updates and announcements from the company.
seo_title string

Optional SEO title.

Example: Company News
seo_description string

Optional SEO description.

Example: Read company updates, product notes, and announcements.
template_handle string

Template assignment. On create, omitting this field or sending an empty string assigns default_blog_category. Use default_blog_category for the default Blog Category template, or pass an alternate Blog Category template handle configured for the store. On update, omit template_handle to leave the assignment unchanged, use default_blog_category to reset it to default, and do not send an empty string.

Example: default_blog_category
create_redirect boolean

When slug changes, create a redirect from the previous slug.

Example: true

Errors

  • 400 STORE_API_INVALID_CATEGORY_ID

    Blog Category id is not a valid UUID.

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.

  • 400 TRANSLATION_SOURCE_FIELD_HAS_TRANSLATIONS

    Clearing a source field is blocked while translated values exist.

  • 404 NOT_FOUND

    Blog Category does not exist in this store.

  • 400 BLOG_CATEGORY_NAME_REQUIRED

    Name is empty after normalization.

  • 400 BLOG_CATEGORY_NAME_EMPTY

    A provided update name is empty after normalization.

  • 400 BLOG_CATEGORY_NAME_TOO_LONG

    Name exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_SLUG_REQUIRED

    Slug is empty on update. Blank slug auto-generation is only available on create.

  • 400 BLOG_CATEGORY_SLUG_FORMAT

    Slug is not valid for Blog Category URLs.

  • 400 BLOG_CATEGORY_SLUG_TOO_LONG

    Slug exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_SLUG_GENERATION_FAILED

    A slug could not be generated from the supplied name.

  • 400 BLOG_CATEGORY_UNIQUE_SLUG_GENERATION_FAILED

    A unique generated slug could not be found; supply a slug explicitly.

  • 400 BLOG_CATEGORY_DESCRIPTION_TOO_LONG

    Description exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_SEO_TITLE_TOO_LONG

    SEO title exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_SEO_DESCRIPTION_TOO_LONG

    SEO description exceeds the Blog Category contract max length.

  • 400 BLOG_CATEGORY_LIMIT_REACHED

    Store Blog Category cap has been reached.

  • 400 TEMPLATE_HANDLE_INVALID

    Template handle is not valid for Blog Category templates.

  • 400 TEMPLATE_HANDLE_NOT_FOUND

    Template handle does not exist on the store's primary active theme for Blog Category.

  • 409 BLOG_CATEGORY_DUPLICATE

    Name or slug already exists in this store.

Delete a blog category

DELETE write_blog

Delete a blog category.

Deletes a Blog Category only when no blog posts are assigned to it. Assigned posts block deletion.

Path parameters

Name Type Description
id required uuid

Blog Category id.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 STORE_API_INVALID_CATEGORY_ID

    Blog Category id is not a valid UUID.

  • 404 NOT_FOUND

    Blog Category does not exist in this store.

  • 409 BLOG_CATEGORY_HAS_POSTS

    Blog Category is assigned to blog posts and cannot be deleted until posts are removed from it.

Bulk delete blog categories

POST write_blog

Delete multiple blog categories.

Deletes unassigned Blog Categories together. Any that are missing, or still assigned to blog posts, are reported as failures and left in place.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
category_ids required array<uuid>

Blog Category ids to delete.

Example: 5ff7d4ea-3250-4a4d-9d26-07f64d917d31

Errors

  • 400 STORE_API_INVALID_REQUEST_BODY

    Request body is not valid JSON.

  • 400 STORE_API_INVALID_CATEGORY_ID

    One category id is not a valid UUID.

  • 400 BLOG_CATEGORY_BULK_NO_IDS

    No Blog Category ids were provided.

  • 400 BLOG_CATEGORY_BULK_DELETE_TOO_MANY

    Batch exceeds the Blog Category bulk delete cap.

  • 409 BLOG_CATEGORY_BULK_RACED

    Blog Category changed during deletion. Retry with fresh data.

  • 400 STORE_API_INVALID_CATEGORY_ID

    Blog Category id is not a valid UUID.

  • 404 NOT_FOUND

    Blog Category does not exist in this store.

  • 409 BLOG_CATEGORY_HAS_POSTS

    Blog Category is assigned to blog posts and cannot be deleted until posts are removed from it.

Fields#

Field

Kind

Create

Update

Required

Translatable

name

text

Yes

Yes

create

Yes

slug

slug

Yes

Yes

Yes

description

textarea

Yes

Yes

Yes

seo_title

text

Yes

Yes

Yes

seo_description

textarea

Yes

Yes

Yes

template_handle

template

Yes

Yes

No

create_redirect

boolean

No

Yes

No

post_count

integer

No

No

No

created_at

datetime

No

No

No

updated_at

datetime

No

No

No

storefront_url

url

No

No

No

No

Webhook events#

Blog Category webhook events are declared by the Blog Category resource contract. The event cards below include the topic, subscription scope, store permission, payload schema, and sample payload.

Blog category created

EVENT blog_categories/create write_blog blog:write

Fired when a blog category is created.

Payload fields

Field Type Description
blog_category.id string Always present
blog_category.name string Can be removed/added via the Payload builder
blog_category.slug string Can be removed/added via the Payload builder
blog_category.description string Can be removed/added via the Payload builder
blog_category.seo_title string Can be removed/added via the Payload builder
blog_category.seo_description string Can be removed/added via the Payload builder
blog_category.template_handle string Can be removed/added via the Payload builder
blog_category.post_count integer Can be removed/added via the Payload builder
blog_category.created_at string Can be removed/added via the Payload builder
blog_category.updated_at string Can be removed/added via the Payload builder

Blog category updated

EVENT blog_categories/update write_blog blog:write

Fired when a blog category is updated.

Payload fields

Field Type Description
blog_category.id string Always present
blog_category.name string Can be removed/added via the Payload builder
blog_category.slug string Can be removed/added via the Payload builder
blog_category.description string Can be removed/added via the Payload builder
blog_category.seo_title string Can be removed/added via the Payload builder
blog_category.seo_description string Can be removed/added via the Payload builder
blog_category.template_handle string Can be removed/added via the Payload builder
blog_category.post_count integer Can be removed/added via the Payload builder
blog_category.created_at string Can be removed/added via the Payload builder
blog_category.updated_at string Can be removed/added via the Payload builder

Blog category deleted

EVENT blog_categories/delete write_blog blog:write

Fired when a blog category is deleted.

Payload fields

Field Type Description
blog_category.id string Always present
blog_category.name string Can be removed/added via the Payload builder
blog_category.slug string Can be removed/added via the Payload builder