Uploading Clarity's Attachments with APIs

Attachments like documents, images, and other files enrich assets with valuable context and detail. Clarity’s developers would like to test attaching files with headless APIs to improve their team’s ability to programmatically augment products with media (e.g., graphics, flyers).

In this article, you’ll leverage APIs to upload an attachment to an existing commerce product.

Exercise: Adding Clarity’s PDF Attachments

Here you’ll use the Commerce Admin APIs to attach a flyer to the Classic Aviator Sunglasses product.

1. Sign in as the Clarity Admin user.

   • Username: admin@clarityvisionsolutions.com

   • Password: learn

2. Navigate to the API Explorer at http://localhost:8080/o/api.

3. In the upper right, click the REST Applications drop-down menu and select headless-commerce-admin-catalog/v1.0.

4. Under the Attachment section, expand the postProductByExternalReferenceCodeAttachmentByBase64 endpoint.

   

5. Add 3d607d51-b58d-d188-5a27-03041440d340 to the externalReferenceCode parameter.

6. Input the following code to the Request body:

   {
   	"attachment" : "%BASE64-PLACEHOLDER%",
   	"externalReferenceCode": "FLYERAVIATOR",
   	"priority": 10,
   	"title": {
   		"en_US": "Classic Aviator Flyer"
   	}
   }
   

   Copy

7. In your course workspace, navigate to the exercises/module-3/flyer-base64.txt file and copy its contents

8. Replace the %BASE64-PLACEHOLDER% in the API Explorer Request body with the copied contents, retaining the surrounding quotes.

   

9. Click Execute.
   The response body should be similar to the following:

   {
   	"cdnEnabled": false,
   	"cdnURL": "",
   	"customFields": [],
   	"displayDate": "2025-03-27T18:37:00Z",
   	"expirationDate": "2025-04-27T18:37:00Z",
   	"externalReferenceCode": "FLYERAVIATOR",
   	"fileEntryExternalReferenceCode": "9714200b-244f-3122-9920-301b31cadfa8",
   	"fileEntryGroupExternalReferenceCode": "c720902d-34b3-21f4-6ece-b90614f0fad1",
   	"fileEntryId": 66559,
   	"galleryEnabled": true,
   	"id": 66564,
   	"options": {},
   	"priority": 10,
   	"src": "https://localhost:8080/o/commerce-media/accounts/-9223372036854775808/attachments/66564?download=true",
   	"tags": [],
   	"title": {
   		"en_US": "Classic Aviator Flyer"
   	},
   	"type": 1
   }
   

   Copy

10. Copy the src field’s URL value, paste it into your browser's address bar, and change the security protocol from https to http to download the PDF.

11. Once downloaded, open the file.
    

12. Navigate back to Clarity’s home page.

13. Open the Global Menu (), go to the Commerce tab, and click Products.

14. Click Classic Aviator Sunglasses.

15. Go to the Media tab and confirm that the flyer was added to the product.
    

Conclusion

Great! You can now leverage headless APIs to attach files to assets within Liferay. Next, you’ll learn how to leverage batch engine APIs to perform bulk exports and imports of data.