DocsDocsReference

Upload product image

Uploads an image either by file or URL and adds it to a product

PUT/api/v1/{team_slug}/{app_slug}/products/{product_id}/images
API
Management
Updated
Apr 26, 2026

management-api:PUT:/api/v1/{team_slug}/{app_slug}/products/{product_id}/images

Uploads an image either by file or URL and adds it to a product

API ownership

  • API family: Management API
  • Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data.
  • Do not use from: Browser-only storefront code or public clients.
  • Guide route: /apis/management/latest

The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation.

Operation

  • Method: PUT
  • Path: /api/v1/\{team_slug\}/\{app_slug\}/products/\{product_id\}/images
  • Summary: Upload product image
  • Description: Uploads an image either by file or URL and adds it to a product
  • OpenAPI contract: management-api
  • Operation ID: Not documented in the OpenAPI contract.

Operation key uses API family, method, and path because this OpenAPI contract does not publish an operation ID.

Parameters3 parameters
NameInRequiredTypeDescription
product_idpathYesstringProduct Number
app_slugpathYesstringApp slug
team_slugpathYesstringTeam slug
Request bodyNo documented body
  • Required: No
  • Description: Not documented in the OpenAPI contract.
  • Content: application/x-www-form-urlencoded (object)

Schema

PropertyTypeRequiredDetails
imagestring (binary)Noformat: binary Image file to upload
titlestringNoTitle for the image
statusstringNoStatus for image. One of active, inactive, draft
altstringNoAlternative text for the image
copyrightstringNoCopyright text for the image
prioritynumberNoPriority for the image list
urlstringNoURL for image to upload
publicbooleanNoIf image is public or not
filenamestringNoCustom filename (without extension)
blurhashstringNoOptional precomputed blurhash. If provided, generation is skipped
parent_idstringNoParent image ID
attributesstring[]NoAttribute for image, e.g. white-background

Generated example (synthetic):

{
  "image": "string",
  "title": "string",
  "status": "string",
  "alt": "string",
  "copyright": "string",
  "priority": 0,
  "url": "string",
  "public": false,
  "filename": "string",
  "blurhash": "string",
  "parent_id": "string",
  "attributes": [
    "string"
  ]
}
Responses4 statuses
StatusDescriptionContent
200Image uploaded successfullyapplication/json (object)
400Invalid requestapplication/json (object)
401Unauthorized accessapplication/json (object)
500Internal server errorapplication/json (object)

200 - object

Product Image Response

PropertyTypeRequiredDetails
dataobjectNo-
detailsstring[]NoAdditional contextual information about the response. Used to provide supplementary details beyond the main data payload, such as validation warnings or processing notes
successbooleanNo-
Image With Priority
PropertyTypeRequiredDetails
altstringNo-
app_idstringNo-
attributesobject[]No-
blurhashstringNo-
copyrightstringNo-
customobjectNo-
folder_idstringNo-
idstringNo-
parent_idstringNo-
priorityintegerNo-
publicbooleanNo-
source_app_idstringNo-
source_idstringNo-
statusstringNo-
titlestringNo-
translationsobjectNo-
urlstringNo-
Attribute
PropertyTypeRequiredDetails
created_atstringNo-
descriptionstringNo-
filterablebooleanNo-
idstringNo-
keystringNo-
namestringNo-
template_keystringNo-
template_namestringNo-
translatablebooleanNo-
translationsobjectNo-
updated_atstringNo-
valuesobjectNo-
Image Translation
PropertyTypeRequiredDetails
altobject[]No-
copyrightobject[]No-
titleobject[]No-
{
  "data": {
    "alt": "string",
    "app_id": "string",
    "attributes": [
      {
        "created_at": "string",
        "description": "string",
        "filterable": false,
        "id": "string",
        "key": "string",
        "name": "string",
        "template_key": "string",
        "template_name": "string",
        "translatable": false,
        "translations": {
          "description": null,
          "name": null
        },
        "updated_at": "string",
        "values": {}
      }
    ],
    "blurhash": "string",
    "copyright": "string",
    "custom": {},
    "folder_id": "string",
    "id": "string",
    "parent_id": "string",
    "priority": 0,
    "public": false,
    "source_app_id": "string",
    "source_id": "string",
    "status": "string",
    "title": "string",
    "translations": {
      "alt": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ],
      "copyright": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ],
      "title": [
        {
          "id": null,
          "locale": null,
          "value": null
        }
      ]
    },
    "url": "string"
  },
  "details": [
    "string"
  ],
  "success": false
}

400 - object

Error Message

PropertyTypeRequiredDetails
detailsstring[]No-
messagestringNo-
successbooleanNo-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

401 - object

Error Message

PropertyTypeRequiredDetails
detailsstring[]No-
messagestringNo-
successbooleanNo-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

500 - object

Error Message

PropertyTypeRequiredDetails
detailsstring[]No-
messagestringNo-
successbooleanNo-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

Contract identity

Use these fields to confirm you are implementing the intended endpoint contract.

  • API family: Management API
  • Method: PUT
  • Path: /api/v1/\{team_slug\}/\{app_slug\}/products/\{product_id\}/images
  • Operation ID: Not documented in the OpenAPI contract.
  • OpenAPI tag: Products
  • OpenAPI summary: Upload product image

Upload product image

# Upload product image Uploads an image either by file or URL and adds it to a product
PUT /api/v1/{team_slug}/{app_slug}/products/{product_id}/images
Purpose

Uploads an image either by file or URL and adds it to a product

Required inputs

product_id path app_slug path team_slug path

Primary response

200 ยท Image uploaded successfully

Operation key

management-api:PUT:/api/v1/{team_slug}/{app_slug}/products/{product_id}/images

## API ownership - API family: Management API - Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data. - Do not use from: Browser-only storefront code or public clients. - Guide route: [/apis/management/latest](/apis/management/latest) The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation. ## Operation - Method: `PUT` - Path: `/api/v1/{team_slug}/{app_slug}/products/{product_id}/images` - Summary: Upload product image - Description: Uploads an image either by file or URL and adds it to a product - OpenAPI contract: management-api - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:PUT:/api/v1/{team_slug}/{app_slug}/products/{product_id}/images` Operation key uses API family, method, and path because this OpenAPI contract does not publish an operation ID. ## Parameters | Name | In | Required | Type | Description | | --- | --- | --- | --- | --- | | product_id | path | Yes | string | Product Number | | app_slug | path | Yes | string | App slug | | team_slug | path | Yes | string | Team slug | ## Request body - Required: No - Description: Not documented in the OpenAPI contract. - Content: application/x-www-form-urlencoded (object) ### Schema | Property | Type | Required | Details | | --- | --- | --- | --- | | `image` | string (binary) | No | format: binary Image file to upload | | `title` | string | No | Title for the image | | `status` | string | No | Status for image. One of `active`, `inactive`, `draft` | | `alt` | string | No | Alternative text for the image | | `copyright` | string | No | Copyright text for the image | | `priority` | number | No | Priority for the image list | | `url` | string | No | URL for image to upload | | `public` | boolean | No | If image is public or not | | `filename` | string | No | Custom filename (without extension) | | `blurhash` | string | No | Optional precomputed blurhash. If provided, generation is skipped | | `parent_id` | string | No | Parent image ID | | `attributes` | string[] | No | Attribute for image, e.g. white-background | **Generated example (synthetic):** ```json { "image": "string", "title": "string", "status": "string", "alt": "string", "copyright": "string", "priority": 0, "url": "string", "public": false, "filename": "string", "blurhash": "string", "parent_id": "string", "attributes": [ "string" ] } ``` ## Responses | Status | Description | Content | | --- | --- | --- | | 200 | Image uploaded successfully | application/json (object) | | 400 | Invalid request | application/json (object) | | 401 | Unauthorized access | application/json (object) | | 500 | Internal server error | application/json (object) | ### 200 - object #### Product Image Response | Property | Type | Required | Details | | --- | --- | --- | --- | | `data` | object | No | - | | `details` | string[] | No | Additional contextual information about the response. Used to provide supplementary details beyond the main data payload, such as validation warnings or processing notes | | `success` | boolean | No | - | ##### Image With Priority | Property | Type | Required | Details | | --- | --- | --- | --- | | `alt` | string | No | - | | `app_id` | string | No | - | | `attributes` | object[] | No | - | | `blurhash` | string | No | - | | `copyright` | string | No | - | | `custom` | object | No | - | | `folder_id` | string | No | - | | `id` | string | No | - | | `parent_id` | string | No | - | | `priority` | integer | No | - | | `public` | boolean | No | - | | `source_app_id` | string | No | - | | `source_id` | string | No | - | | `status` | string | No | - | | `title` | string | No | - | | `translations` | object | No | - | | `url` | string | No | - | ##### Attribute | Property | Type | Required | Details | | --- | --- | --- | --- | | `created_at` | string | No | - | | `description` | string | No | - | | `filterable` | boolean | No | - | | `id` | string | No | - | | `key` | string | No | - | | `name` | string | No | - | | `template_key` | string | No | - | | `template_name` | string | No | - | | `translatable` | boolean | No | - | | `translations` | object | No | - | | `updated_at` | string | No | - | | `values` | object | No | - | ##### Image Translation | Property | Type | Required | Details | | --- | --- | --- | --- | | `alt` | object[] | No | - | | `copyright` | object[] | No | - | | `title` | object[] | No | - |
Generated example (synthetic) ```json { "data": { "alt": "string", "app_id": "string", "attributes": [ { "created_at": "string", "description": "string", "filterable": false, "id": "string", "key": "string", "name": "string", "template_key": "string", "template_name": "string", "translatable": false, "translations": { "description": null, "name": null }, "updated_at": "string", "values": {} } ], "blurhash": "string", "copyright": "string", "custom": {}, "folder_id": "string", "id": "string", "parent_id": "string", "priority": 0, "public": false, "source_app_id": "string", "source_id": "string", "status": "string", "title": "string", "translations": { "alt": [ { "id": null, "locale": null, "value": null } ], "copyright": [ { "id": null, "locale": null, "value": null } ], "title": [ { "id": null, "locale": null, "value": null } ] }, "url": "string" }, "details": [ "string" ], "success": false } ```
### 400 - object #### Error Message | Property | Type | Required | Details | | --- | --- | --- | --- | | `details` | string[] | No | - | | `message` | string | No | - | | `success` | boolean | No | - | **Generated example (synthetic):** ```json { "details": [ "string" ], "message": "string", "success": false } ``` ### 401 - object #### Error Message | Property | Type | Required | Details | | --- | --- | --- | --- | | `details` | string[] | No | - | | `message` | string | No | - | | `success` | boolean | No | - | **Generated example (synthetic):** ```json { "details": [ "string" ], "message": "string", "success": false } ``` ### 500 - object #### Error Message | Property | Type | Required | Details | | --- | --- | --- | --- | | `details` | string[] | No | - | | `message` | string | No | - | | `success` | boolean | No | - | **Generated example (synthetic):** ```json { "details": [ "string" ], "message": "string", "success": false } ``` ## Contract identity Use these fields to confirm you are implementing the intended endpoint contract. - API family: Management API - Method: `PUT` - Path: `/api/v1/{team_slug}/{app_slug}/products/{product_id}/images` - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:PUT:/api/v1/{team_slug}/{app_slug}/products/{product_id}/images` - OpenAPI tag: Products - OpenAPI summary: Upload product image