DocsDocsReference

Upload image

Uploads an image by either URL or file. If both a URL and file are provided, the URL will be used over the file. A URL can be provided without a file, and vice versa.

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

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

Uploads an image by either URL or file. If both a URL and file are provided, the URL will be used over the file. A URL can be provided without a file, and vice versa.

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\}/images
  • Summary: Upload image
  • Description: Uploads an image by either URL or file. If both a URL and file are provided, the URL will be used over the file. A URL can be provided without a file, and vice versa.
  • 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.

Parameters5 parameters
NameInRequiredTypeDescription
app_slugpathYesstringApp slug
team_slugpathYesstringTeam slug
connect_to_skuqueryNobooleanTry to connect the image to a product or variant using the filename. If filename matches an existing product or variant do we connect it. Priority can be set via a numeric suffix (sku_3) or an uppercase letter suffix A-Z (sku_A, where A=1 through Z=26). If the format don't match sku_priority (e.g sku.jpeg) do we fallback to priority 10
connect_to_slugqueryNobooleanTry to connect the image to a product usign the filename. If filename matches an existing product do we connect it. Priority can be set via a numeric suffix (slug_3) or an uppercase letter suffix A-Z (slug_A, where A=1 through Z=26). If the format don't match slug_priority (e.g slug.jpeg) do we fallback to priority 10
connect_to_variant_groupqueryNobooleanTry to connect the image to a variant group using the filename. Format: productNumber_variantGroupSlug[_priority].extension where priority is numeric or uppercase A-Z (A=1 through Z=26). Example: 2512301_102.jpg links product 2512301 variant group slug 102.
Request bodyNo documented body
  • Required: No
  • Description: Not documented in the OpenAPI contract.
  • Content: application/x-www-form-urlencoded (object)

Schema

PropertyTypeRequiredDetails
titlestringNoImage title
altstringNoAlternative image text
copyrightstringNoImage copyright text
imagestring (binary)Noformat: binary Image file to upload
urlstringNoUrl to source file. Url will be used if provided over file
statusstringNoStatus for image. One of active, inactive, draft
filenamestringNoCustom filename (without extension)
blurhashstringNoOptional precomputed blurhash. If provided, generation is skipped
parent_idstringNoParent image ID

Generated example (synthetic):

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

200 - object

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 Used By
PropertyTypeRequiredDetails
altstringNo-
app_idstringNo-
attributesobject[]No-
blurhashstringNo-
copyrightstringNo-
customobjectNo-
folder_idstringNo-
idstringNo-
parent_idstringNo-
publicbooleanNo-
source_app_idstringNo-
source_idstringNo-
statusstringNo-
titlestringNo-
translationsobjectNo-
urlstringNo-
used_byobject[]No-
variantsobject[]No-
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-
Asset Consumer
PropertyTypeRequiredDetails
created_atstringNo-
idstringNo-
namestringNo-
priorityintegerNo-
slugstringNo-
typeenum("product", "variant", "attribute")No-
updated_atstringNo-
Image
PropertyTypeRequiredDetails
altstringNo-
app_idstringNo-
attributesobject[]No-
blurhashstringNo-
copyrightstringNo-
customobjectNo-
folder_idstringNo-
idstringNo-
parent_idstringNo-
publicbooleanNo-
source_app_idstringNo-
source_idstringNo-
statusstringNo-
titlestringNo-
translationsobjectNo-
urlstringNo-
{
  "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",
    "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",
    "used_by": [
      {
        "created_at": "string",
        "id": "string",
        "name": "string",
        "priority": 0,
        "slug": "string",
        "type": "product",
        "updated_at": "string"
      }
    ],
    "variants": [
      {
        "alt": "string",
        "app_id": "string",
        "attributes": [],
        "blurhash": "string",
        "copyright": "string",
        "custom": {},
        "folder_id": "string",
        "id": "string",
        "parent_id": "string",
        "public": false,
        "source_app_id": "string",
        "source_id": "string",
        "status": "string",
        "title": "string",
        "translations": {
          "alt": null,
          "copyright": null,
          "title": 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\}/images
  • Operation ID: Not documented in the OpenAPI contract.
  • OpenAPI tag: Images
  • OpenAPI summary: Upload image

Upload image

# Upload image Uploads an image by either URL or file. If both a URL and file are provided, the URL will be used over the file. A URL can be provided without a file, and vice versa.
PUT /api/v1/{team_slug}/{app_slug}/images
Purpose

Uploads an image by either URL or file.

Required inputs

app_slug path team_slug path

Primary response

200 ยท Image uploaded successfully

Operation key

management-api:PUT:/api/v1/{team_slug}/{app_slug}/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}/images` - Summary: Upload image - Description: Uploads an image by either URL or file. If both a URL and file are provided, the URL will be used over the file. A URL can be provided without a file, and vice versa. - OpenAPI contract: management-api - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:PUT:/api/v1/{team_slug}/{app_slug}/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 | | --- | --- | --- | --- | --- | | app_slug | path | Yes | string | App slug | | team_slug | path | Yes | string | Team slug | | connect_to_sku | query | No | boolean | Try to connect the image to a product or variant using the filename. If filename matches an existing product or variant do we connect it. Priority can be set via a numeric suffix (sku_3) or an uppercase letter suffix A-Z (sku_A, where A=1 through Z=26). If the format don't match sku_priority (e.g sku.jpeg) do we fallback to priority 10 | | connect_to_slug | query | No | boolean | Try to connect the image to a product usign the filename. If filename matches an existing product do we connect it. Priority can be set via a numeric suffix (slug_3) or an uppercase letter suffix A-Z (slug_A, where A=1 through Z=26). If the format don't match slug_priority (e.g slug.jpeg) do we fallback to priority 10 | | connect_to_variant_group | query | No | boolean | Try to connect the image to a variant group using the filename. Format: productNumber_variantGroupSlug[_priority].extension where priority is numeric or uppercase A-Z (A=1 through Z=26). Example: 2512301_102.jpg links product 2512301 variant group slug 102. | ## Request body - Required: No - Description: Not documented in the OpenAPI contract. - Content: application/x-www-form-urlencoded (object) ### Schema | Property | Type | Required | Details | | --- | --- | --- | --- | | `title` | string | No | Image title | | `alt` | string | No | Alternative image text | | `copyright` | string | No | Image copyright text | | `image` | string (binary) | No | format: binary Image file to upload | | `url` | string | No | Url to source file. Url will be used if provided over file | | `status` | string | No | Status for image. One of `active`, `inactive`, `draft` | | `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 | **Generated example (synthetic):** ```json { "title": "string", "alt": "string", "copyright": "string", "image": "string", "url": "string", "status": "string", "filename": "string", "blurhash": "string", "parent_id": "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 #### 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 Used By | 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 | - | | `public` | boolean | No | - | | `source_app_id` | string | No | - | | `source_id` | string | No | - | | `status` | string | No | - | | `title` | string | No | - | | `translations` | object | No | - | | `url` | string | No | - | | `used_by` | object[] | No | - | | `variants` | object[] | 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 | - | ##### Asset Consumer | Property | Type | Required | Details | | --- | --- | --- | --- | | `created_at` | string | No | - | | `id` | string | No | - | | `name` | string | No | - | | `priority` | integer | No | - | | `slug` | string | No | - | | `type` | enum("product", "variant", "attribute") | No | - | | `updated_at` | string | No | - | ##### Image | 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 | - | | `public` | boolean | No | - | | `source_app_id` | string | No | - | | `source_id` | string | No | - | | `status` | string | No | - | | `title` | string | No | - | | `translations` | object | No | - | | `url` | string | 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", "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", "used_by": [ { "created_at": "string", "id": "string", "name": "string", "priority": 0, "slug": "string", "type": "product", "updated_at": "string" } ], "variants": [ { "alt": "string", "app_id": "string", "attributes": [], "blurhash": "string", "copyright": "string", "custom": {}, "folder_id": "string", "id": "string", "parent_id": "string", "public": false, "source_app_id": "string", "source_id": "string", "status": "string", "title": "string", "translations": { "alt": null, "copyright": null, "title": 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}/images` - Operation ID: Not documented in the OpenAPI contract. - Stable operation key: `management-api:PUT:/api/v1/{team_slug}/{app_slug}/images` - OpenAPI tag: Images - OpenAPI summary: Upload image