The Create Product Image API allows users to upload and associate a new image with a specific product by providing the product's ID and image details. This API ensures efficient management of product images, enabling users to specify image attributes like dimensions, position, and alternative text.
This API is especially useful for:
- Upload new images for products to enhance their display and marketing.
- Specify image attributes such as width, height, position, and alternative text for better presentation.
- Verifying shop details through its unique domain prefix (shopdomain).
Example: If the shop’s domain is https://store123.myshoplazza.com
, the shopdomain
would be store123
.
Requires
product
access scope. For more info , refer to:
Public Request Parameters
Parameter Name | Type | Required | Parameter Location | Parameter Value | Description |
---|---|---|---|---|---|
Access-Token | String | Yes | Header | Bx-_5aV eXNwl-4AB98s5xLV yg0fNzGf MuTpqtlBA | Used to authenticate API requests. Obtain an access token from the Access Token Guide. Pass it in the Authorization header for every request. |
Content-Type | String | Yes | Header | application /json | Indicates the media type of the request body. It tells the server how to parse the request and the client how to interpret the response. For more details, visit Content-Type. |
Public Response Parameters
Parameter Name | Type | Mandatory | Parameter Location | Example Value | Description |
---|---|---|---|---|---|
error | String | No | Response Body | { "error": "store is not active" } | Indicates an error encountered during the process. This field typically appears when the Access Token is missing or invalid. Example: { "error": "store is not active" } . |
errors | Array | No | Response Body | { "errors"["No Context"] } | A list of errors that occurred during the request processing. Example: { "errors": [ "No Context" ] } . |
Request-Id | String | Yes | Header | Bx-_5aV eXNwl-4AB98s5xLV yg0fNzGf MuTpqtlBA | A unique identifier for each request. It helps in identifying and debugging specific requests. |
Error and Errors Clarification:
Added explanation that the error and errors fields are currently dependent on the API implementation, with plans for future unification.
Request Parameters
Path Parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
product_id | string | Yes | 9fb9f3c6-2300-42c1-8593-d9008d7cfc09 | The unique identifier for the product. |
Body Parameters
Parameter | Type | Required | Example | Description |
---|---|---|---|---|
image | object | Yes | Image Object | |
image.src | string | Yes | "http://cdn.shoplazza.com/1.jpg" | The URL of the image. Must be a valid URL. |
image.position | string | No | "1" | The position of the image relative to other images. Must be greater than 0. |
image.alt | string | No | "Product front view" | Alternative text for the image (used for accessibility or descriptions). |
image.width | int | No | 300 | The width of the image in pixels. Must be greater than 0. |
image.height | int | No | 300 | The height of the image in pixels. Must be greater than 0. |
Response Explanation
Successful Response
Field | Type | Example | Description |
---|---|---|---|
image.id | string | 91d032e7-bbc8-47e4-8668-9ba6fe714de6 | The unique identifier for the image. |
image.product_id | string | 636a07da-39eb-4829-bde9-b65fae1c28b0 | The unique identifier for the product associated with the image. |
image.position | integer | 1 | The position of the image relative to other images in the product gallery. |
image.src | string | //cdn.shoplazza.com/efd33b921cacd5311a32dd03a9bc8740.png | The URL of the image. |
image.width | integer | 1588 | The width of the image in pixels. |
image.height | integer | 2246 | The height of the image in pixels. |
image.alt | string | "" | Alternative text for the image (used for accessibility or descriptions). |
image.created_at | string | 2024-04-08T07:13:28Z | The timestamp indicating when the image was created. |
image.updated_at | string | 2024-04-08T07:13:28Z | The timestamp indicating when the image was last updated. |
error Response
Error responses in the API can be represented using two different fields: errors
and error
. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
Field | Type | Example | Description |
---|---|---|---|
errors | Array | ["Context"] | A list of errors encountered during the request processing. |
Field | Type | Example | Description |
---|---|---|---|
error | Array | "store is not active" | Indicates an error encountered during the process. |
Request Examples
curl --request POST \
--url https://{shopdomain}.myshoplaza.com/openapi/2022-01/products/{product_id}/images \
--header 'accept: application/json' \
--header 'access-token: {your-access-token}' \
--header 'content-type: application/json' \
--data '{
"image": {
"src": "http://cdn.shoplazza.com/1.jpg",
"position": 1,
"alt": "Product image alt text",
"width": 300,
"height": 300
}
}'
Success Response Example
{
"image": {
"id": "91d032e7-bbc8-47e4-8668-9ba6fe714de6",
"product_id": "636a07da-39eb-4829-bde9-b65fae1c28b0",
"position": 1,
"src": "//cdn.shoplazza.com/efd33b921cacd5311a32dd03a9bc8740.png",
"width": 1588,
"height": 2246,
"alt": "",
"created_at": "2024-04-08T07:13:28Z",
"updated_at": "2024-04-08T07:13:28Z"
}
}
Error Response Example
{
"errors": [
"Product not found"
]
}
{
"error": "store is not active"
}
Error Details
Status Code | Message | Possible Reason | Example Response |
---|---|---|---|
400 | Bad Request | - Invalid input format or request structure (e.g., missing required fields or incorrect data types). - Width, height or position values less than or equal to 0. | Bad Request |
Unauthorized | The request is missing valid authentication credentials or the credentials provided are invalid. | Unauthorized | |
404 | Product not found | - The product ID provided in the request does not exist. - The requested resource (product) is not available. | { "errors": ["Product not found"] } |
422 | Invalid or empty product_id | missing required product_id or product_id with incorrect UUID types | { "errors": [ "ProductId must be a valid UUID"]} |