--- title: "Initiate a multi-file staged upload task" description: > Initiate a staged upload for multiple files. This API will return the upload credentials necessary for future upload operations. doc_type: openapi doc_category: openapi doc_version: v20270301 source_url: html: 'https://developer.shopline.com/docs/admin-rest-api/product/files/initiate-a-file-staged-upload' md: 'https://developer.shopline.com/docs/admin-rest-api/product/files/initiate-a-file-staged-upload.md' --- # Initiate a multi-file staged upload task Initiate a staged upload for multiple files. This API will return the upload credentials necessary for future upload operations. - **Base URL:** `https://{handle}.myshopline.com/admin/openapi` - **Required Scopes:** `write_files` - **API Version:** v20270301 - **API Type:** Admin - **API Protocol:** RESTful ## Endpoint ```http POST /files/upload.json ``` ## Base URL * `https://{handle}.myshopline.com/admin/openapi` * `{handle}`: `handle` : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is `open001.myshopline.com` , the store handle is `open001` . ## Required Permissions * `write_files` ## Request ### Request Headers * `Content-Type` string (required) The field must be set to the fixed value `application/json; charset=utf-8`. * `Authorization` string (required) The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. ### Request Body * `file_info` array A list of information about the files. * `file_name` string The name of the file. A complete and accurate file extension must be provided for format identification.
Maximum length: 255 * `file_size` long The size of the file, in bytes. Required when the file type is a video. * `mime_type` string The MIME type of the file. Valid values are: - `image/jpeg` - `image/png` - `image/bmp` - `image/webp` - `image/svg+xml` - `image/x-icon` - `video/mp4` - `video/webm` - `video/quicktime` - `application/pdf` - `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - `text/csv` - `application/vnd.openxmlformats-officedocument.wordprocessingml.document` - `font/ttf` - `font/woff` - `font/otf` - `font/sfnt` - `application/font-sfnt` - `audio/mpeg` - `text/html` - `text/javascript` - `application/javascript` - `text/css` - `application/json` - `application/xml` - `text/xml` - `text/plain` - `application/octet-stream` - `application/x-rar-compressed` - `application/zip` ## Response ### Status Codes * `200` For the complete list of codes and messages, see [Http status code](https://developer.shopline.com/docs/apps/api-instructions-for-use/http-status-code.md?lang=en). * `401` * `429` ### Response Headers * `traceId` A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise. ### Response Body #### 200 * `signs` array A list of signature information for the files. * `access_id` string The access key associated with the signature. * `call_back` string The callback parameter for the file upload. * `host` string The destination URL for file uploading. * `key` string Relative path for storing the file, including the filename. * `policy` string Signature policy information for the file upload. * `signature` string Signature for the upload request. * `url` string The pre-allocated temporary access URL for the file. #### 401 * `errors` string Error message. #### 429 * `errors` string Error message. ## OpenAPI Definition ```json { "tags": [ "Initiate a multi-file staged upload task" ], "description": "Initiate a staged upload for multiple files. This API will return the upload credentials necessary for future upload operations. ", "externalDocs": { "description": "Permission point used by the interface is `write_files` , For more information about the use of permission points, see", "url": "ec20/3cv5d7wpfgr6a8z5/xabczf5442284vkq?lang=en", "errorTableDescription": "| Error Code | HTTP Status Code | Error Description |\n|------------|------------------|-------------------|\n| SUCCESS | 200 | request success |\n" }, "operationId": "6MkTalBm", "parameters": [ { "name": "Content-Type", "in": "header", "description": "The field must be set to the fixed value `application/json; charset=utf-8`.", "required": true, "schema": { "name": "Content-Type", "type": "string", "example": "application/json; charset=utf-8" } }, { "name": "Authorization", "in": "header", "description": " The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. ", "required": true, "style": "string", "schema": { "name": "Authorization", "description": " The access token for the API resource. Refer to [App authorization](https://developer.shopline.com/docs/apps/api-instructions-for-use/app-authorization.md?lang=en) to obtain the access token, and then pass the obtained token in the Bearer format. ", "type": "string", "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA" }, "example": "Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhcHBJZCI6MCwiYXBwS2V5IjoiNzU2ZjI1NWE2NjdlZTcwNTk1MzM0ZjVjYzk4NzU5MzBmN2E3NGZjMSIsImV4cCI6MTg3OTQ4MjA3NiwiaXNzIjoieXNvdWwiLCJzZWxsZXJJZCI6IjIwMDAyMzQ4ODAiLCJzdG9yZUlkIjoiMTY3MjM2OTcyOTYwNiIsInRpbWVzdGFtcCI6MTc4NDc4NzY3NjY2MSwidmVyc2lvbiI6IlYyIn0.3ZzbGAH4cLU1QR2VPEvMOQInUDvus-C4amkINSQIPuNVlXsFKj0sAt1c0KnUy9MWUOFV9cHlkf7J90r2y1FzpA" } ], "requestBody": { "content": { "application/json": { "schema": { "name": "body", "description": "body position parameter", "type": "object", "properties": { "file_info": { "name": "file_info", "description": "A list of information about the files. ", "type": "array", "items": { "type": "object", "properties": { "file_name": { "name": "file_name", "description": "The name of the file. A complete and accurate file extension must be provided for format identification.
\nMaximum length: 255", "type": "string", "example": "file_name.jpg" }, "file_size": { "name": "file_size", "description": "The size of the file, in bytes. Required when the file type is a video.", "type": "long", "example": 300 }, "mime_type": { "name": "mime_type", "description": "The MIME type of the file. Valid values are:\n- `image/jpeg`\n- `image/png`\n- `image/bmp`\n- `image/webp`\n- `image/svg+xml`\n- `image/x-icon`\n- `video/mp4`\n- `video/webm`\n- `video/quicktime`\n- `application/pdf`\n- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`\n- `text/csv`\n- `application/vnd.openxmlformats-officedocument.wordprocessingml.document`\n- `font/ttf`\n- `font/woff`\n- `font/otf`\n- `font/sfnt`\n- `application/font-sfnt`\n- `audio/mpeg`\n- `text/html`\n- `text/javascript`\n- `application/javascript`\n- `text/css`\n- `application/json`\n- `application/xml`\n- `text/xml`\n- `text/plain`\n- `application/octet-stream`\n- `application/x-rar-compressed`\n- `application/zip`", "type": "string", "example": "image/jpeg" } }, "required": [ "file_name", "mime_type" ], "example": { "file_name": "file_name.jpg", "file_size": 300, "mime_type": "image/jpeg" } }, "example": [ {} ] } }, "required": [ "file_info" ], "example": { "file_info": [ {} ] } }, "examples": { "Initiate a file staged upload ": { "description": "Initiate a staged upload for multiple files. This API will return the upload credentials necessary for future upload operations. ", "value": { "file_info": [ { "file_name": "my video.mp4", "file_size": "2000", "mime_type": "video/mp4" }, { "file_name": "my image.jpeg", "file_size": "50", "mime_type": "image/png" } ] } } } } }, "required": true }, "responses": { "200": { "description": "For the complete list of codes and messages, see [Http status code](https://developer.shopline.com/docs/apps/api-instructions-for-use/http-status-code.md?lang=en).", "headers": { "traceId": { "description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise." } }, "content": { "application/json": { "schema": { "name": "body", "type": "object", "properties": { "signs": { "name": "signs", "description": "A list of signature information for the files. ", "type": "array", "items": { "type": "object", "properties": { "access_id": { "name": "access_id", "description": "The access key associated with the signature.", "type": "string", "example": "LTAI5tRrVqCocJKdSpEovixm" }, "call_back": { "name": "call_back", "description": "The callback parameter for the file upload.", "type": "string", "example": "eyJjYWxsYmFja0JvZHkiOiJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mc2l6ZT0ke3NpemV9JmNvbnRlbnRUeXBlVHlwZT0ke2NvbnRlbnRUeXBlVHlwZX0mZm9ybWF0PSR7aW1hZ2VJbmZvLmZvcm1hdH0mYml6dHlwZT1cIm9wZW5hcGlTdGFzaENoYW5nZUxpbmtcIiIsImNhbGxiYWNrQm9keVR5cGUiOiJhcHBsaWNhdGl" }, "host": { "name": "host", "description": "The destination URL for file uploading.", "type": "string", "example": "https://sl-resource-tmp-sg.s3.xxx.com" }, "key": { "name": "key", "description": "Relative path for storing the file, including the filename.", "type": "string", "example": "temp/file/store/1626235806828/6991265004189666341/image.jpg" }, "policy": { "name": "policy", "description": "Signature policy information for the file upload. ", "type": "string", "example": "eyJleHBpcmF0aW9uIjoiMjAyNi0wNS0xMlQwODo1Mjo1NloiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwyMDk3MTUyMF0sWyJlcSIsIiRrZXkiLCJ0ZW1wL2ZpbGUvc3RvcmUvMTYyNjIzNTgwNjgyOC82OTkxMjY1MDA0MTg5NjY2MzQxLzAwMDQ5ZWEzNDQ4ZTQzMWM4YTRiYzVh" }, "signature": { "name": "signature", "description": "Signature for the upload request. ", "type": "string", "example": "6+YHcWnLhu0YofPIzAQUaZ9kKZI=" }, "url": { "name": "url", "description": "The pre-allocated temporary access URL for the file.", "type": "string", "example": "https://sl-resource-tmp-sg.s3-ap-southeast-1.xxx.com/temp%2Ffile%2Fstore%2F1672369729606%2F6995259736342668404%2Fimage.png?Expires=1747882880&OSSAccessKeyId=LTAI5tNjm7fr4EUCoEps4UPE&Signature=kLIWPCVwWTQMZcHUWyszjoH4DPM%3D" } }, "example": { "access_id": "LTAI5tRrVqCocJKdSpEovixm", "call_back": "eyJjYWxsYmFja0JvZHkiOiJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mc2l6ZT0ke3NpemV9JmNvbnRlbnRUeXBlVHlwZT0ke2NvbnRlbnRUeXBlVHlwZX0mZm9ybWF0PSR7aW1hZ2VJbmZvLmZvcm1hdH0mYml6dHlwZT1cIm9wZW5hcGlTdGFzaENoYW5nZUxpbmtcIiIsImNhbGxiYWNrQm9keVR5cGUiOiJhcHBsaWNhdGl", "host": "https://sl-resource-tmp-sg.s3.xxx.com", "key": "temp/file/store/1626235806828/6991265004189666341/image.jpg", "policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0wNS0xMlQwODo1Mjo1NloiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwyMDk3MTUyMF0sWyJlcSIsIiRrZXkiLCJ0ZW1wL2ZpbGUvc3RvcmUvMTYyNjIzNTgwNjgyOC82OTkxMjY1MDA0MTg5NjY2MzQxLzAwMDQ5ZWEzNDQ4ZTQzMWM4YTRiYzVh", "signature": "6+YHcWnLhu0YofPIzAQUaZ9kKZI=", "url": "https://sl-resource-tmp-sg.s3-ap-southeast-1.xxx.com/temp%2Ffile%2Fstore%2F1672369729606%2F6995259736342668404%2Fimage.png?Expires=1747882880&OSSAccessKeyId=LTAI5tNjm7fr4EUCoEps4UPE&Signature=kLIWPCVwWTQMZcHUWyszjoH4DPM%3D" } } } }, "example": { "signs": null } }, "examples": { "Initiate a file staged upload ": { "description": "Initiate a staged upload for multiple files. This API will return the upload credentials necessary for future upload operations. ", "value": { "signs": [ { "access_id": "LTAI5tNjm7fr4EUCoEps4UPE", "call_back": "eyJjYWxsYmFja0JvZHkiOiJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mbWltZVR5cGU9JHttaW1lVHlwZX0mc2l6ZT0ke3NpemV9JmNvbnRlbnRUeXBlVHlwZT0ke2NvbnRlbnRUeXBlVHlwZX0mZm9ybWF0PSR7aW1hZ2VJbmZvLmZvcm1hdH0mYml6dHlwZT1cIm9wZW5hcGlTdGFzaENoYW5nZUxpbmtcIiIsImNhbGxiYWNrQm9keVR5cGUiOiJhcHBsaWNhdGlvbi9qc29uIiwiY2FsbGJhY2tVcmwiOiJodHRwczovL2FwaS1vc3Nub3RpZnktc2ctcHJldmlldy5teXNob3BsaW5lLmNvbS9hcGkvc2lnbmF0dXJlL29zcy9wb3N0L25vdGlmeSJ9Cg==", "host": "https://sl-resource-tmp-sg.s3.xxx.com", "key": "temp/file/store/1672369729606/6995259736325891187/video.mp4", "policy": "eyJleHBpcmF0aW9uIjoiMjAyNS0wNS0yMlQwMzowMToyMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwyMDk3MTUyMF0sWyJlcSIsIiRrZXkiLCJ0ZW1wL2ZpbGUvc3RvcmUvMTY3MjM2OTcyOTYwNi82OTk1MjU5NzM2MzI1ODkxMTg3L3ZpZGVvLm1wNCJdLFsiaW4iLCIkY29udGVudC10eXBlIixbInZpZGVvL21wNCJdXSxbImVxIiwiJGNhbGxCYWNrIiwiZXlKallXeHNZbUZqYTBKdlpIa2lPaUppZFdOclpYUTlKSHRpZFdOclpYUjlKbTlpYW1WamREMGtlMjlpYW1WamRIMG1iV2x0WlZSNWNHVTlKSHR0YVcxbFZIbHdaWDBtYzJsNlpUMGtlM05wZW1WOUptTnZiblJsYm5SVWVYQmxWSGx3WlQwa2UyTnZiblJsYm5SVWVYQmxWSGx3WlgwbVptOXliV0YwUFNSN2FXMWhaMlZKYm1adkxtWnZjbTFoZEgwbVltbDZkSGx3WlQxY0ltOXdaVzVoY0dsVGRHRnphRU5vWVc1blpVeHBibXRjSWlJc0ltTmhiR3hpWVdOclFtOWtlVlI1Y0dVaU9pSmhjSEJzYVdOaGRHbHZiaTlxYzI5dUlpd2lZMkZzYkdKaFkydFZjbXdpT2lKb2RIUndjem92TDJGd2FTMXZjM051YjNScFpua3RjMmN0Y0hKbGRtbGxkeTV0ZVhOb2IzQnNhVzVsTG1OdmJTOWhjR2t2YzJsbmJtRjBkWEpsTDI5emN5OXdiM04wTDI1dmRHbG1lU0o5Q2c9PSJdLFsiaW4iLCIkeC1vc3MtY29udGVudC10eXBlIixbImZvcm0tZmllbGQtbnVsbCJdXV19Cg==", "signature": "yZ7+COvtdMCuVlTLJNcjZWsiONw=", "url": "https://sl-resource-tmp-sg.s3-ap-southeast-1.xxx.com/temp%2Ffile%2Fstore%2F1672369729606%2F6995259736325891187%2Fvideo.mp4?Expires=1747882880&OSSAccessKeyId=LTAI5tNjm7fr4EUCoEps4UPE&Signature=PfJxZps6aSlO7%2FROX3r9ePiBAls%3D" }, { "access_id": "LTAI5tNjm7fr4EUCoEps4UPE", "call_back": "eyJjYWxsYmFja0JvZHkiOiJidWNrZXQ9JHtidWNrZXR9Jm9iamVjdD0ke29iamVjdH0mbWltZVR5cGU9JHttaW1lVHlwZX0mc2l6ZT0ke3NpemV9JmNvbnRlbnRUeXBlVHlwZT0ke2NvbnRlbnRUeXBlVHlwZX0mZm9ybWF0PSR7aW1hZ2VJbmZvLmZvcm1hdH0mYml6dHlwZT1cIm9wZW5hcGlTdGFzaENoYW5nZUxpbmtcIiIsImNhbGxiYWNrQm9keVR5cGUiOiJhcHBsaWNhdGlvbi9qc29uIiwiY2FsbGJhY2tVcmwiOiJodHRwczovL2FwaS1vc3Nub3RpZnktc2ctcHJldmlldy5teXNob3BsaW5lLmNvbS9hcGkvc2lnbmF0dXJlL29zcy9wb3N0L25vdGlmeSJ9Cg==", "host": "https://sl-resource-tmp-sg.s3.xxx.com", "key": "temp/file/store/1672369729606/6995259736342668404/image.png", "policy": "eyJleHBpcmF0aW9uIjoiMjAyNS0wNS0yMlQwMzowMToyMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwxMDQ4NTc2MF0sWyJlcSIsIiRrZXkiLCJ0ZW1wL2ZpbGUvc3RvcmUvMTY3MjM2OTcyOTYwNi82OTk1MjU5NzM2MzQyNjY4NDA0L2ltYWdlLnBuZyJdLFsiaW4iLCIkY29udGVudC10eXBlIixbImltYWdlL3BuZyJdXSxbImVxIiwiJGNhbGxCYWNrIiwiZXlKallXeHNZbUZqYTBKdlpIa2lPaUppZFdOclpYUTlKSHRpZFdOclpYUjlKbTlpYW1WamREMGtlMjlpYW1WamRIMG1iV2x0WlZSNWNHVTlKSHR0YVcxbFZIbHdaWDBtYzJsNlpUMGtlM05wZW1WOUptTnZiblJsYm5SVWVYQmxWSGx3WlQwa2UyTnZiblJsYm5SVWVYQmxWSGx3WlgwbVptOXliV0YwUFNSN2FXMWhaMlZKYm1adkxtWnZjbTFoZEgwbVltbDZkSGx3WlQxY0ltOXdaVzVoY0dsVGRHRnphRU5vWVc1blpVeHBibXRjSWlJc0ltTmhiR3hpWVdOclFtOWtlVlI1Y0dVaU9pSmhjSEJzYVdOaGRHbHZiaTlxYzI5dUlpd2lZMkZzYkdKaFkydFZjbXdpT2lKb2RIUndjem92TDJGd2FTMXZjM051YjNScFpua3RjMmN0Y0hKbGRtbGxkeTV0ZVhOb2IzQnNhVzVsTG1OdmJTOWhjR2t2YzJsbmJtRjBkWEpsTDI5emN5OXdiM04wTDI1dmRHbG1lU0o5Q2c9PSJdLFsiaW4iLCIkeC1vc3MtY29udGVudC10eXBlIixbImZvcm0tZmllbGQtbnVsbCJdXV19Cg==", "signature": "yOdrzcc5TybeOmasArln98Z/Fi4=", "url": "https://sl-resource-tmp-sg.s3-ap-southeast-1.xxx.com/temp%2Ffile%2Fstore%2F1672369729606%2F6995259736342668404%2Fimage.png?Expires=1747882880&OSSAccessKeyId=LTAI5tNjm7fr4EUCoEps4UPE&Signature=kLIWPCVwWTQMZcHUWyszjoH4DPM%3D" } ] } } } } } }, "401": { "headers": { "traceId": { "description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Error message. ", "type": "string" } }, "required": [ "errors" ] } } } }, "429": { "headers": { "traceId": { "description": "A globally unique identifier for the request. It is used to track the request flow throughout the system, allowing for easy location and debugging when issues arise." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "description": "Error message. ", "type": "string" } }, "required": [ "errors" ] } } } } }, "security": [ { "oauth2": [] } ], "method": "post", "path": "/files/upload.json", "servers": [ { "url": "https://{handle}.myshopline.com/admin/openapi", "variables": { "handle": { "default": "openapiceshidianpu", "description": "`handle` : The store's unique identifier, which is the prefix of the store's domain name. For example, if a store's domain name is `open001.myshopline.com` , the store handle is `open001` ." } } } ], "info": { "title": "Initiate a multi-file staged upload task", "version": "v20270301" }, "authIndexes": [ "write_files" ] } ```