Product Images


The Product resource supports storing images in two places.

Each product has a primary image, accessed via the product.image field on the Product API resource. The product's primary image is used for thumbnails in Merchant App and other places.

Each product also supports storing a collection of Additional Image API resources. Additional images can be tagged and you can store as many as you like with each product.

A product's primary image and additional images require that each individual image asset file be uploaded as a Media Object API resource.

Primary Image

The product's primary image is accessed via API endpoints for the Product resource.

Uploading a Primary Image

You may find it helpful to walk through the following example of setting a product's primary image.

  1. First, create a new Media Object from a local image file. Let's assume you have a file named my-image.png.

    curl -X POST https://api.pilon.io/media-objects \
        -H "Content-Type: multipart/form-data" \
        -H "Accept: application/json" \
        -H "Authorization: Bearer ACCESS_TOKEN_GOES_HERE" \
        -F environment="e652c7d6-5885-11e9-8647-d663bd873d93" \
        -F file=@my-image.png 
  2. You should receive a JSON response soemthing like this:

    {
        "id": "39fd2214-5886-11e9-8647-d663bd873d93",
        "environment": "/environments/e652c7d6-5885-11e9-8647-d663bd873d93",
        "encodingFormat": "image/png",
        "contentSize": 3967521,
        "created": "2019-04-06T16:00:45.672Z",
        "updated": "2019-04-06T16:00:45.672Z",
        "contentUrl": "https://i.pilon.io/a95a31099ad8190243d30b0acefde5b87adbc902.png"
    }
  3. Next, you need to set this media object as the primary image on your product. Reference the id of the newly created Media Object, like this:

    curl -X PUT https://api.pilon.io/products/678827fa-5887-11e9-8647-d663bd873d93 \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -H "Authorization: Bearer ACCESS_TOKEN_GOES_HERE" \
        -d $'{
    	  "image": "39fd2214-5886-11e9-8647-d663bd873d93"
    	}'

Uploading Additional Images

You may find it helpful to walk through the following example of adding additional images to a product.

  1. First, create a new Media Object from a local image file. Let's assume you have a file named my-image.png.

    curl -X POST https://api.pilon.io/media-objects \
        -H "Content-Type: multipart/form-data" \
        -H "Accept: application/json" \
        -H "Authorization: Bearer ACCESS_TOKEN_GOES_HERE" \
        -F environment="e652c7d6-5885-11e9-8647-d663bd873d93" \
        -F file=@my-image.png 
  2. You should receive a JSON response soemthing like this:

    {
        "id": "39fd2214-5886-11e9-8647-d663bd873d93",
        "environment": "/environments/e652c7d6-5885-11e9-8647-d663bd873d93",
        "encodingFormat": "image/png",
        "contentSize": 3967521,
        "created": "2019-04-06T16:00:45.672Z",
        "updated": "2019-04-06T16:00:45.672Z",
        "contentUrl": "https://i.pilon.io/a95a31099ad8190243d30b0acefde5b87adbc902.png"
    }
  3. Next, create the additional image, referencing the product id and the id of the newly created Media Object, like this. Note that you can set arbitrary tags or attributes to be associated with the image.

    curl -X POST https://api.pilon.io/products/additional-images \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -H "Authorization: Bearer ACCESS_TOKEN_GOES_HERE" \
        -d $'{
            "product": "/products/678827fa-5887-11e9-8647-d663bd873d93",
    	    "image": "/media-objects/39fd2214-5886-11e9-8647-d663bd873d93",
            "attributes": {
                "myTag": "some value",
                "anotherTag": "another value"
            }
    	}'

Additional Image Resource

Each product support storing and tagging a collection of additional images.

Add an Additional Image to Product

POST/products/additional-images

curl -X POST https://api.pilon.io/products/additional-images \
     -H "Authorization: Bearer ACCESS_TOKEN_GOES_HERE" \
     -H "Content-Type: application/json" \
     -d $'{
		  "image": "string",
		  "attributes": "string"
		}'

Retrieve an Additional Image

GET/products/additional-images/{id}

curl -X GET https://api.pilon.io/products/additional-images/{id} \
     -H "Authorization: Bearer ACCESS_TOKEN_GOES_HERE" \
     -H "Content-Type: application/json"

Update an Additional Image

PUT/products/additional-images/{id}

curl -X PUT https://api.pilon.io/products/additional-images/{id} \
     -H "Authorization: Bearer ACCESS_TOKEN_GOES_HERE" \
     -H "Content-Type: application/json" \
     -d $'{
		  "attributes": "string"
		}'

Delete an Additional Image

DELETE/products/additional-images/{id}

curl -X DELETE https://api.pilon.io/products/additional-images/{id} \
     -H "Authorization: Bearer ACCESS_TOKEN_GOES_HERE" \
     -H "Content-Type: application/json"