Skip to content
Figur

Create a product from an uploaded image

POST
/v1/products
curl --request POST \
  --url https://example.com/v1/products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "upload_asset_public_id": "example", "title": "example", "external_ref": "example", "description": "example", "garment_category_public_id": "example" }'

Turn an image from POST /v1/uploads into a product you can sell.

Free: creating a product runs no generation, so no credits move.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Shopify-Hmac-Sha256
Any of:
string

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
ProductCreateRequest

Create a product from an image you have already uploaded.

Ownership is taken from your credential — there is no owner field to send. Supplying external_ref makes the call idempotent: re-posting the same reference updates that product instead of creating a duplicate.

object
upload_asset_public_id
required
Upload Asset Public Id

asset_id from POST /v1/uploads.

string
>= 26 characters <= 26 characters
title
required
Title
string
>= 1 characters <= 256 characters
external_ref
Any of:
string
>= 1 characters <= 256 characters
description
Any of:
string
>= 1 characters <= 2000 characters
garment_category_public_id
Any of:
string
>= 26 characters <= 26 characters
Examplegenerated
{
  "upload_asset_public_id": "example",
  "title": "example",
  "external_ref": "example",
  "description": "example",
  "garment_category_public_id": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

Successful Response

Media typeapplication/json
ProductResponse

One product owned by the authenticated client.

object
public_id
required
Public Id
string
title
required
Title
string
external_ref
Any of:
string
category
Any of:
ProductCategoryResponse

The garment category a product sits in, resolved for display.

object
public_id
required
Public Id
string
key
required
Key

Canonical taxonomy key, e.g. ethnic_top.

string
display_label
required
Display Label
string
status
required
Status

active | archived.

string
description
Any of:
string
primary_image_url
Any of:
string
source_pdp_image_url
Any of:
string
images
Images
Array<object>
ProductImageResponse

One image on a product.

object
asset_public_id
required
Asset Public Id
string
role
required
Role

primary | gallery | source_pdp.

string
position
required
Position
integer
image_url
required
Image Url

Short-lived presigned URL; not an input handle.

string
created_at
required
Created At
string format: date-time
Examplegenerated
{
  "public_id": "example",
  "title": "example",
  "external_ref": "example",
  "category": {
    "public_id": "example",
    "key": "example",
    "display_label": "example"
  },
  "status": "example",
  "description": "example",
  "primary_image_url": "example",
  "source_pdp_image_url": "example",
  "images": [
    {
      "asset_public_id": "example",
      "role": "example",
      "position": 1,
      "image_url": "example"
    }
  ],
  "created_at": "2026-04-15T12:00:00Z"
}

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}