Shopify Publishing API
Push AI-generated fashion visuals straight onto the product pages of the Shopify store connected to your account — images and videos, through the exact pipeline the app's own publish button uses. List the catalogue, pick a product, publish with one POST.
Needs a key with the publish scope and an active plan; create keys and connect the store from your profile. Generate the visuals first with any workflow of the API.
/v1/shopify/productsThe connected store's catalogue (read scope) — up to 500 products, title-ordered. No store connected answers { "store": null, "products": [] } with 200: an answer, not an error, so an integration can poll it to know when the merchant has connected.
Request
curl https://thenewblack.ai/api/v1/shopify/products \ -H "Authorization: Bearer tnb_live_XXXXXXXXXXXX"
Response · 200
{ "store": "yourbrand.myshopify.com",
"products": [
{ "id": "gid://shopify/Product/8790123456789",
"title": "Boxy tweed jacket",
"image_url": "https://cdn.shopify.com/...",
"handle": "boxy-tweed-jacket" } ] }/v1/shopify/publishPublishes one creation onto one product page. The creation's own type picks the road: an image is fetched by Shopify from its URL, a video goes through Shopify's staged upload (96 MB max). Alt text defaults to the generation's prompt.
media_idstringoptionalThe creation to publish — the id a generation returned. Either this or url.urlstringoptionalAlternative to media_id: the generation's file url. It must be a creation of this account — arbitrary URLs are refused.product_idstringrequiredThe product's gid from /v1/shopify/products, or its bare number.altstringoptionalAlt text on the product page. Defaults to the generation's prompt; capped at 512 characters.Request
curl -X POST https://thenewblack.ai/api/v1/shopify/publish \
-H "Authorization: Bearer tnb_live_XXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{ "media_id": "9f2c1e2a-...", "product_id": "8790123456789",
"alt": "Boxy tweed jacket on model" }'Response · 200
{ "published": true,
"store": "yourbrand.myshopify.com",
"product_id": "gid://shopify/Product/8790123456789",
"media_id": "9f2c1e2a-...",
"preview_url": "https://yourbrand.myshopify.com/products/boxy-tweed-jacket" }Errors
403statusrequiredpremium_required — publishing needs an active plan on the account.404statusrequiredmedia_not_found — no creation of this account matches the media_id or url.409statusrequiredno_store — no Shopify store connected · already_published — this creation is on a page already.413statusrequiredfile_too_large — the file exceeds Shopify's 96 MB media limit.502statusrequiredshopify_unreachable · shopify_refused — Shopify's side failed; nothing was published.Frequently asked questions
What can I publish to Shopify through the API?
Any creation of your account — AI-generated images and videos alike. One route handles both: an image lands as a product-page image, a video travels through Shopify's staged upload (96 MB max) and appears in the product's media.
Do I need anything besides an API key?
Three things: a key carrying the publish scope (and read to list products), an active plan on the account, and the Shopify store connected once from your profile. The store belongs to the paying account — on a team, that is the leader's store.
Can I publish the same creation to two product pages?
No — one product page per creation, by design. A second publish answers 409 already_published; unpublish it from the studio's Shopify view first. This keeps every published image manageable from the app.
Can I publish an arbitrary image URL?
No. The route publishes creations of your account, named by media_id (the id a generation returned) or by url (that generation's file url). An unknown URL answers 404 media_not_found — publishing rowless files would create orphans nothing could unpublish.
Does this use a different pipeline than the app?
No — it is the same corridor the studio's publish modal walks, gate for gate. A creation published by API shows LIVE in the studio's Shopify view, and Unpublish there works on it exactly as if it had been published in-app.
Instagram, TikTok and the other connected platforms publish from the app today; their API endpoints open later and will each get a page like this one. Back to the API reference.