Image Submission | Documentation | CanvasPop Photo Printing API

Image Handshake

Before Pop-up Store can be displayed to a user, the desired image must be sent via one of two image APIs. The following describes the methods for sending an image to the Pop-up Store to be placed into a customer's cart.

Image Handshake

Contents

Which API should I use?

The API you should use when loading Pop-up Store depends on if the desired image exists already at a URL and can be “pulled” into Pop-up Store, or if it exists within your application and needs to be “pushed” into Pop-up Store through an HTTP POST.

API When to use
Pull API Image can be accessed via a public URL
Push API Image cannot be accessed via a public URL and must be pushed to Pop-up Store via an HTTP POST

Pull API

The Pull API is designed to be used with images that exist at a publicly accessible URL. It works by including the URL to the desired image as a URL parameter when opening the store. If the image being loaded into Pop-up Store exists on an external domain or server outside of your application, you must own the rights to the image.

The Pull API will first verify your partner account via the access_key parameter, and then verify and retrieve the image in the image_url parameter in the URL. This image is then placed in CanvasPop's image store and loaded into a cart for the user.

The API will also examine the image's properties to determine an appropriate set of sizes to present to the user, based on which will fit the best and with minimal cropping.

To avoid including the full URL in the parameter, Pop-up Store settings allow you to configure a root image path. This string will be prepended to the image_url value before attempting to download the image.

Using the Pull API

To use the Pull API simply open a new browser window to the following URL:

https://store.canvaspop.com/api/pull?image_url=<_URL_TO_YOUR_IMAGE>&access_key=<YOUR_API_ACCESS_KEY>

This will result in the store being loaded with a new cart containing your image:

Cart Example

Push API

The Push API is used for sending an image that does not exist at a publicly accessible URL. It works by including the image file as an HTTP POST parameter, along with the appropriate authentication headers described in our authentication documentation page.

Method #1: Uploading a preview image followed by a print image

The Push API supports a two-step handshake that allows a partner to first send a smaller, lower resolution file followed by a high resolution printable image in the background. This allows a user to begin the checkout process without having to wait for the larger upload to complete.

Steps to implement:
  1. Complete a preview image handshake using the /api/push/preview image endpoint and receive an image_token value
  2. Open Pop-up Store using the /loader endpoint with your preview token including the width and height of the to-be-uploaded print image
  3. Complete a print image handshake using the /api/push/print image endpoint again including your image_token value

Method #2: Uploading a single high resolution image

Pop-up Store also supports sending a single high resolution image should no smaller version of the file exist. Using this method may result in a slightly longer delay in starting the checkout process.

Steps to implement:
  1. Complete a single image handshake using the /api/push/image endpoint and receive an image_token value
  2. Open Pop-up Store using the /loader endpoint including the image_token received


For further documentation on the API endpoints, see our API endpoints Documentation page.