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: The shopper clicks an Upload File button on the storefront. The JavaScript code on the page uses the POST V1/media/initiate-upload endpoint to start the upload process. The call specifies the file name provided by the shopper. Commerce uses the AWS SDK to generate the URL to which the file will be uploaded.

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 code uses the presigned URL to upload the file directly to an Amazon S3 bucket. This is done using a standard HTTP PUT request. The file is uploaded to a temporary location in the S3 bucket.

4. Finalize the upload: After the file is successfully uploaded to S3, the client code calls the POST V1/media/finish-upload endpoint to complete the upload process. The mutation includes the unique key received from the initiate-upload response.

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 following media resource type are supported:

• CATEGORY_IMAGE
• CUSTOMER_ATTRIBUTE_ADDRESS_FILE
• CUSTOMER_ATTRIBUTE_ADDRESS_IMAGE
• CUSTOMER_ATTRIBUTE_FILE
• CUSTOMER_ATTRIBUTE_IMAGE
• NEGOTIABLE_QUOTE_ATTACHMENT

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.

Copy
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"
}'
Copied to your clipboard
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:

Copy
   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>...'
Copied to your clipboard
   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.

Copy
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"
  }
Copied to your clipboard
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. For REST (CATEGORY_IMAGE), assign the returned key to the category image attribute when creating the category.

Example:

Copy
{
    "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>"
            }
        ]
    }
}
Copied to your clipboard
{
    "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>"
            }
        ]
    }
}

Last updated 10/7/2025

Was this helpful?

Yes

No