Skip to main content
POST
/
dashboard
/
api
/
v1
/
trade-items
/
{organization_id}
/
{gtin}
/
images
Upload product image
curl --request POST \
  --url https://www.closient.com/dashboard/api/v1/trade-items/{organization_id}/{gtin}/images \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form image='@example-file' \
  --form title= \
  --form is_primary=false
{
  "id": "<string>",
  "title": "<string>",
  "is_primary": true,
  "priority": 1,
  "created": "2023-11-07T05:31:56Z",
  "image_url": "https://cdn.closient.com/products/00012345678905/hero.jpg"
}

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-Key
string
header
required

Path Parameters

​
organization_id
string<shortuuid>
required

UUID of the organization that owns the product.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
​
gtin
string
required

GTIN-8/12/13/14 of the target product. Normalized to GTIN-14 by zero-padding before lookup.

Pattern: ^\d{8,14}$

Body

multipart/form-data
​
image
file
required

Image file to upload (JPEG, PNG, GIF, WebP, SVG, or BMP).

​
title
string
default:""

Caption / role label for the image (e.g. "Front of package"). Empty string when not specified.

Maximum string length: 255
​
is_primary
boolean
default:false

When true, this image becomes the product's hero image and the previous primary image is automatically unmarked. Defaults to false.

Response

201 - application/json

Created

Single image attached to a product.

​
id
string<shortuuid>
required

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
​
title
string
required

Caption / role label for the image (e.g. "Front of package", "Nutrition facts"). Empty string when not set.

Maximum string length: 255
Example:

"Front of package"

​
is_primary
boolean
required

True for the single image surfaced as the product's hero. At most one image per product has this set; uploading a new primary unsets the previous one.

​
priority
integer
required

Display order within a product's image gallery. Lower numbers appear first; ties break on -created. Primary image always sorts first regardless of priority.

Required range: x >= 0
​
created
string<date-time>
required

ISO-8601 UTC timestamp of when the image was uploaded.

​
image_url
string<uri>

Absolute URL of the original (non-resized) image asset on the configured storage backend. null only when the underlying ImageField is empty, which should not occur for persisted rows.

Example:

"https://cdn.closient.com/products/00012345678905/hero.jpg"