• Version: 1.2.0

Images

Using the files endpoint, you can upload images to your store and assign them to any item in your store. The images that you upload will be distributed in our edge-cached content delivery network (CDN) so your store webpages will load as fast as possible. Images have the following fields by default:

Key Type Required Unique Details
id Integer No Yes Automatically populated when you create the image.
file String Yes No The name and path of the image to upload to our servers.
name String No Yes The name to give the image once uploaded.
assign_to Integer No No The ID number of the object to which you want to attach this image.
mime String No No The mime type of the uploaded image. This will be automatically detected if you do not provide this field.
url Array No Yes The resulting URLs of the cached image. This value is automatically created when you upload the image.
segments Array No Yes The URL of the cached image, split into the domain name and file path (suffix). This value is automatically created when you upload the image.
details Array No No Contains information about the file that you uploaded, including the type, size, width, and height. This value is automatically created when you upload the image.
created_at String No No Automatically populated when you create the image.
updated_at String No No Automatically populated when you modify the image.

Before using images, you’ll need to create them with the https://api.molt.in/v1/files endpoint. Images can then be assigned to products, brands, collections, and more. Any object that has an images[] array in its returned information can have images assigned to it.

Before you can use this (or any endpoint), you need to authenticate to get a bearer token.

This topic will cover the following processes:

Create a New Image

Every image that you create must have data for at least the fields marked Required in the table above. You can put data fields in any order. We strongly recommend that you assign your image to an object when you create it, as images cannot be edited once they have been created.

Because we are sending a file instead of the string, we need to change a couple of things from how we normally run cURL statements. First, we need to send the file as form data. To do this, we need to add an extra header to indicate that this is a multi-part form and include the file as a form element using the -F switch. Second, we need to put an ‘@’ symbol before the file name to indicate that we want to send the file at this location and not just the string itself.

curl -X POST https://api.molt.in/v1/files \
	-H "Authorization: Bearer XXXX" \
	-H "Content-Type: multipart/form-data" \
	-F "file=@C:\Users\Admin\Pictures\moltin_logo.png" \
	-d "assign_to=1019656230785778497"

On success, this call will return a 201 Created HTML status code and the image information for the newly created image, including any default or generated values. The object it returns looks like this by default (the data will be different, of course):

{
  "status":true,
  "result":
  {
    "id":1049464552850194651,
    "url":
    {
      "http":"http:\/\/commercecdn.com\/1018614836482801759\/ae0b589b-c230-4fae-b3af-1ef4e142f322.jpeg",
      "https":"https:\/\/commercecdn.com\/1018614836482801759\/ae0b589b-c230-4fae-b3af-1ef4e142f322.jpeg"
    },
    "segments":
    {
      "domain":"commercecdn.com\/",
      "suffix":"\/1018614836482801759\/ae0b589b-c230-4fae-b3af-1ef4e142f322.jpeg"
    },
    "details":
    {
      "type":"image",
      "size":42606,
      "width":422,
      "height":640
    }
  }
}

The file actions below will return information in this same format.

Retrieve Image Information by ID

Your store could have thousands of images. Because of this, you cannot return all images at once. Instead, you can return an individual image by appending their ID number to the files endpoint.

curl -X GET https://api.molt.in/v1/files/1049464552850194651 \
	-H "Authorization: Bearer XXX"

This returns a 200 OK status code and the image information for the selected ID number.

Delete a Single Image

To remove an image, you use the same files/{ID number} endpoint we used to retrieve a single image, except we use the DELETE request method.

curl -X DELETE https://api.molt.in/v1/files/1049464552850194651
	-H "Authorization: Bearer XXXX"

If successful, this call returns 200 OK and the following:

{
	"status":true,
	"message":"File removed successfully"
}

The image will be automatically removed from any store objects that it had been assigned to.

Requesting images you have uploaded

You can use our free CDN system to request your images.

https://commercecdn.com/12323442/8e536fb8-c33d-4a59-b23f-b6f7c92b0edd.png

Any objects that contain images will include an image field with a list of images available:

{
	    images: [{
	        details: {
	            type: "image",
	            size: 61357,
	            width: 140,
	            height: 195
	        },
	        height: 195
	        size: 61357
	        type: "image"
	        width: 140
	        id: "986987987",
	        name: "grid_thumbnail.png",
	        segments: {
	            domain: "commercecdn.com/",
	            suffix: "986987987/2bbf22ba-345c-4ccd-a21d-3e2b916d9d17.png"
	        },
	        domain: "commercecdn.com/",
	        suffix: "986987987/2bbf22ba-345c-4ccd-a21d-3e2b916d9d17.png",
	        url: {
	            http: "http://commercecdn.com/986987987/2bbf22ba-345c-4ccd-a21d-3e2b916d9d17.png"
	            https: "https://commercecdn.com/986987987/2bbf22ba-345c-4ccd-a21d-3e2b916d9d17.png"
	        }
	    }]
	}

Resizing images on the fly

Any images you upload to your products or categories will be available from our CDN. You can call the URL for the image to request it, but you can also ask for those images to be resized on the fly.

Manipulating height and width

You can add h and w to the URL string to request the image in a specific size and width:

https://commercecdn.com/w100/h200/12323442/8e536fb8-c33d-4a59-b23f-b6f7c92b0edd.png

This will send back the image with a width of 100px and a height of 200px.

Manipulating Fill and Fit

You can couple requests for a specific sized image with the fill or fit variables.

The Fill mode creates an image with the exact given width and height while retaining original proportions.

https://commercecdn.com/fill/w100/h200/12323442/8e536fb8-c33d-4a59-b23f-b6f7c92b0edd.png

The Fit mode changes the image’s size to fit in the given width while retaining original proportions.

https://commercecdn.com/fit/w100/h200/12323442/8e536fb8-c33d-4a59-b23f-b6f7c92b0edd.png