About the Items API

The Items API lets you create, publish, schedule, and manage social media posts on a site's connected channels. In this API, a post is called an item. Items you create through the API appear on the site's Social Media Marketing page in the dashboard, alongside posts created there manually.

With the Items API, you can:

• Create draft items and publish or schedule them for a future date.
• Publish a fully-formed item in a single call.
• Retrieve, update, and delete items.
• Query items to find drafts, scheduled posts, or published posts.
• Reschedule or cancel scheduled items.
• Publish multiple items in bulk.
• Publish a multi-frame story draft as a sequence of stories.

Before publishing or scheduling, check that the target channel is connected with the Accounts API and that the site has remaining quota with the Premium Features API. You can optionally generate post content with the Generated Content API before creating a draft.

Item lifecycle

An item moves through statuses as you work with it:

• Draft: Created with Create Draft Item and not yet published or scheduled.
• Scheduled: Published with a future scheduledDate. The post is published automatically at that time unless you cancel or reschedule it.
• Published: Live on the connected channel.

The recommended flow is to create a draft first, then publish or schedule it with Publish Item By ID. You can also call Publish Item with a complete item in one step.

Multi-frame stories

A story item holds one media item per frame. A story draft with more than one media item can only be published with Publish Multi Story Draft, which splits the draft into one story item per frame and publishes them in media order, stopping at the first failure. Publishing such a draft with any other method fails with MULTI_STORY_PUBLISH_NOT_SUPPORTED, because the channel would publish only its first frame. Frames already published by an earlier call are skipped, so the call can be safely retried after a partial failure, and the draft is deleted only once all of its frames are published. Each published frame carries the original draft's ID in originItemId, so you can match the new items to whatever you recorded against the draft.

Multi-frame story drafts are typically generated for a site by the Marketing Plan API, which decides which of a plan's activities carry a story and how many frames each one has.

Filtering and sorting items

Query Items supports a fixed set of filterable and sortable fields, listed in that method's description. Two behaviors are worth knowing before you rely on a query:

• A field that isn't supported is ignored rather than rejected. A filter naming the wrong field returns the same items as no filter at all, so check the field names when a query returns more items than you expect.
• A value the API doesn't define matches no items, rather than returning an error. Enum values themselves are case insensitive, so SCHEDULED and scheduled are equivalent.

Deleted items are never returned, with or without a filter. Sorting on one of the analytics fields requires the site to have post insights. Without them, the items are sorted by date instead, in whichever direction you asked for.

Identifying what created an item

Every item records what created it, in consumerInfo.name. Specify it whenever you create or publish an item, using one stable name for whatever is making the call, whether that's an app, an AI agent, or a service of your own. The name is stored with the item and returned every time the item is read, so the items your integration created can be told apart from items created in the site's dashboard or by something else.

Set it at creation. Create Draft Item, Publish Item, and Bulk Publish Items accept it. Update Item doesn't change it, so an item created without a name can't be identified later.

Before you begin

It's important to note the following points before starting to code:

• A site owner must connect their social channels in the site's dashboard before you can publish to them. See Connecting to your social media accounts.
• Each item targets a single connected channel. Its type and content must match a combination that channel supports.
• Post media: Media Manager URLs (static.wixstatic.com for images, video.wixstatic.com for videos) are the supported option and are what the site's dashboard produces. The API doesn't validate the URL's host, so a non-Media-Manager URL is accepted, but it must be publicly reachable by the target channel, and channels differ in how they handle such a URL. To use an image or video that isn't in the Media Manager yet, add it first with the Media Manager.
• Publishing and scheduling can fail if the site has reached its plan quota. Call Get Feature Data with PUBLISH_POST or SCHEDULE_POST before you publish or schedule.
• Posts created natively on a channel rather than through Wix are imported once a day for sites on a paid social media marketing plan. They appear as items with external set to true and may take up to a day to show up.

Use cases

• Create and publish a post.
• Schedule a post for a future date.
• Reschedule or cancel a scheduled post.
• Generate post content and publish it.
• Generate a caption for a post.
• Find a site's scheduled posts.
• Publish a multi-frame story.

Terminology

• Item: A social media post managed through the Publisher API. An item can be a draft, scheduled, or published post and targets a single connected channel.
• Channel: A social network that a post is published to, such as Instagram or TikTok.
• Account: A connected social channel, such as an Instagram business account or a Facebook page, that an item is published to.
• Status: Indicates whether an item is a draft, scheduled, or published.
• Story: A full-screen vertical post that a channel shows for a limited time. A story draft can hold several media items, one per frame, and each frame is published as its own story item.