data-src=../../../includes/saas-only.md

Upload files to Amazon S3

Adobe Commerce as a Cloud Service (SaaS) supports file uploads through REST endpoints. This feature allows you to upload images to Amazon Simple Storage Service (S3). Sharing objects with presigned URLs describes how presigned URLs work.

Uploading files is a multi-step process, as shown in the following diagram:

1. Initiate the upload: An admin or integration starts the upload by calling the POST V1/media/initiate-upload endpoint with the file name. Commerce then uses the AWS SDK to generate a URL for uploading the file.

2. Receive the response: The response from the initiate-upload call includes a presigned URL, a unique key for the file, and an expiration time for the URL. The client code extracts these values from the response.

3. Upload the file: The client uploads the file to a temporary S3 location using the presigned URL and an HTTP PUT request. For more information, see PutObject.

4. Finalize the upload: After uploading the file to S3, the client calls POST V1/media/finish-upload using the unique key returned by initiate-upload.

5. Perform validation: Commerce uses a HEAD request on S3 Temporary to validate the key and size.

6. Move the file: Commerce performs a CopyObject operation to move the file from the temporary location to a permanent location in the S3 bucket.

7. Receive the final response: The response from the POST V1/media/finish-upload endpoint includes the unique key for the uploaded file. The client code extracts this key from the response.

8. Create or update the entity: After POST V1/media/finish-upload succeeds, the client creates or updates the entity (such as a category image) using the returned hashed key as the attribute value, not a URL or full S3 path.

9. Receive the create/update response: The response from the create or update call includes the details of the created or updated entity.

Initiate the upload

Use the POST V1/media/initiate-upload endpoint to start the file upload process by generating a presigned URL for uploading a file to an Amazon S3 bucket. This endpoint requires the file name (key) and media resource type (media_resource_type) as input parameters. The key value cannot contain slashes.

The REST endpoint is an admin or backend API, which requires the Magento_S3PresignedUploadRest::manage_media ACL resource, that allows you to upload catalog media. The following media resource types are supported:

• CATEGORY_IMAGE — a category image.
• PRODUCT_FILE_ATTRIBUTE — a product custom attribute of input type file.

data-variant=info

data-slots=text

When you call this endpoint, Commerce uses the AWS SDK to create a presigned URL that allows the client to upload the file directly to a temporary location in the S3 bucket. The presigned URL is valid for a limited time, specified by the expires_at field in the response.

The call requires an IMS access token.

curl --request POST \
  --url https://<server>.commerce.adobe.com/<tenant-id>/V1/media/initiate-upload \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "1.png",
    "media_resource_type": "CATEGORY_IMAGE"
}'

Upload the file to S3

The following curl command demonstrates how to upload a file using the presigned URL returned by the POST V1/media/initiate-upload call:

   curl --fail --show-error --silent -X PUT --data-binary @./cat.jpg 'https://<bucket>.s3.<region>.amazonaws.com/<path-to-temp-file>?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Security-Token=<token>&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=<value>&X-Amz-Date=<value>&X-Amz-SignedHeaders=host&X-Amz-Expires=<value>&X-Amz-Signature=<value>...'

Finish the upload

Use the POST V1/media/finish-upload endpoint to complete the upload process after the file is successfully uploaded to S3. This endpoint includes the unique key received from the initiate-upload response.

When you call this endpoint, Commerce verifies that the file associated with the provided key has been successfully uploaded to the S3 bucket. If the upload is confirmed, Commerce finalizes the upload process and makes the file available for use within the system. The response from the finish-upload endpoint includes the unique key for the uploaded file. This key can be used to reference the file in subsequent operations, such as associating it with a category image attribute.

curl --request POST \
  --url https://server.commerce.adobe.com/<tenant-id>/V1/media/finish-upload \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "<KEY_FROM_INITIATION>",
    "media_resource_type": "CATEGORY_IMAGE"
  }'

Add the uploaded file to an entity

Your Adobe Commerce instance must define the target attribute. Assign the returned key, filename only, to the attribute when you create or update it. Do not include the URL or path.

Add an image to a category

For CATEGORY_IMAGE, assign the returned key to the category image attribute when you create the category:

{
  "category": {
    "parent_id": "2",
    "name": "One",
    "is_active": true,
    "include_in_menu": true,
    "custom_attributes": [
      {
        "attribute_code": "image",
        "value": "1_7aa0b2d63f6d3dbf0290bb31.png"
      },
      {
        "attribute_code": "description",
        "value": "<p>test description one<\/p>"
      }
    ]
  }
}

Add a file to a product

For PRODUCT_FILE_ATTRIBUTE, assign the returned key to the product's file attribute. Set the value to the filename only (the key returned from finish-upload):

{
  "product": {
    "sku": "24-MB01",
    "custom_attributes": [
      {
        "attribute_code": "spec_sheet",
        "value": "manual_d35edd0d729fe160eac99295.pdf"
      }
    ]
  }
}