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.
- Which API should I use?
- Pull API
- Push API
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|
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:
This will result in the store being loaded with a new cart containing your image:
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:
- Complete a preview image handshake using the
/api/push/previewimage endpoint and receive an
- Open Pop-up Store using the
/loaderendpoint with your preview token including the width and height of the to-be-uploaded print image
- Complete a print image handshake using the
/api/push/printimage endpoint again including your
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:
- Complete a single image handshake using the
/api/push/imageendpoint and receive an
- Open Pop-up Store using the
/loaderendpoint including the
For further documentation on the API endpoints, see our API endpoints Documentation page.