Skip to content

Create a blog post

POST
/stores/{storeRef}/blog/posts
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/blog/posts \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "title": "example", "slug": "example", "content": "example", "toc": [ { "id": "example", "level": 1, "textContent": "example", "pos": 1 } ], "excerpt": "example", "featured_image_url": "example", "status": "draft", "is_featured": true, "scheduled_at": "example", "published_at": "example", "category_ids": [ 1 ], "tag_ids": [ 1 ], "product_ids": [ 1 ] }'

Creates a post, as a draft unless status says otherwise. Categories, tags and recommended products are attached by ID and must belong to this store. A scheduled post needs a scheduled_at in the future. Publishing a post notifies the store team in the dashboard.

Required scopes: write:blog

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
title
required

Title of the post.

string
slug
required

URL slug, unique within the store.

string
content

Post body as HTML.

string
toc

Table of contents generated from the headings in content.

Array<object>
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 content.

number
excerpt

Short summary shown in listings.

string
featured_image_url

URL of the featured image.

string
status

Publication status. Defaults to draft. A scheduled post needs a scheduled_at in the future.

string
Allowed values: draft published scheduled unlisted
is_featured

Whether to mark the post as featured.

boolean
scheduled_at

When to publish a scheduled post, as an ISO 8601 timestamp in the future.

string
published_at

Publication time, as an ISO 8601 timestamp.

string
category_ids

IDs of the categories to attach. When given on update, replaces the current categories.

Array<number>
tag_ids

IDs of the tags to attach. When given on update, replaces the current tags.

Array<number>
product_ids

Array of product IDs to recommend in this blog post

Array<number>
Media typeapplication/json
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

Example

{
"status": "draft"
}

The request is malformed or failed validation.

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 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"
}