API Documentation

Description

Upload the images needed by a particular order. Query whether an order's images have been uploaded.

Call Signature

Application ID and call signature are required. Please see Call Signature documentation for more details.

Resource Path

This API uses the following resource path element:

/image - often paired with a Shutterfly image ID

It should appear in combination with its parent:

Order API - Example:

/order/000012345678-8000012/image
/order/000012345678-8000012/image/67b0de21b3022c546538

Methods

POST - Upload images needed by a specific order. This API is similar to the Image Upload API, but this version is single-image.
GET - Queries the state of one or more images within an order. The purpose is to determine which images have been successfully uploaded from Shutterfly's perspective.

Scheme

http
https (optional)

Host

for POST: up3.shutterfly.com; for GET: ws.shutterfly.com

Method Endpoint example

POST http://up3.shutterfly.com/order/000012345678-8000012/image/10d66da8e87e8def

GET http://ws.shutterfly.com/order/000012345678-8000012/image
http://ws.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c546538

Method	Endpoint example

POST	http://up3.shutterfly.com/order/000012345678-8000012/image/10d66da8e87e8def

GET	http://ws.shutterfly.com/order/000012345678-8000012/image http://ws.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c546538

In the following Method detail sections, click on Method name to expand or collapse the detail.
Click here to expand/collapse all.

Method: POST

Upload images needed by a specific order. This API is similar to the Image Upload API, but this version is single-image.

User authorization

User authorization is required for this method. Please see the user authorization documentation for more details.

Sample Input

POST /order/000012345678-8000012/image/10d66da8e87e8def?oflyAppId=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx HTTP/1.1
Host: up3.shutterfly.com
Content-Type: multipart/form-data; boundary=AaB03x
Content-Length: xxxxxx

--AaB03x
Content-Disposition: form-data; name="AuthenticationID"

000020654580|1196723290244|f248719765da1c300387b49e83faadfe23f76c63
--AaB03x
Content-Disposition: form-data; name="Image.Data"; filename="C:\pictures\sphinx.jpg"
Content-Type: image/jpeg

[... image's binary data ...]
--AaB03x--

Input Parameters

Content-Type

multipart/form-data; boundary=--------xxxxxx

Submit the following parameters in the Post body as multi-part form data.

AuthenticationID

A 'Content-Disposition: form-data' part for the User Authentication token, obtained from the User Authentication API.

Count: 1

Example: 000020654580|1195595728543|7b0df350319ce49be36aa52b038f8949ac285bdf

Image.Data

A 'Content-Disposition: form-data' part for the image being uploaded to Shutterfly, including its filename, Content-Type and binary contents. JPEG is the only supported format, so Content-Type should always be "image/jpeg".

Count: 1

Length: 0 - 20 Mb

Example: (image data)

filename

A sub-parameter of Image.Data, giving a filename for the image being uploaded. See the Sample Invocation. Note that unlike the album image upload, only a single image may be uploaded to this endpoint.

Count: 1

Example: filename="C:\pictures\sphinx.jpg"

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openfly="http://openfly.shutterfly.com/v1.0" 
    xmlns:upload="http://upload.openfly.shutterfly.com/v1.0">
  <title>Upload Result</title>
  <category term="upload-result" scheme="http://upload.openfly.shutterfly.com/v1.0" />
  <upload:errCode>0</upload:errCode>
  <upload:errMessage>N/A</upload:errMessage>
  <upload:numSuccess>1</upload:numSuccess>
  <upload:numFail>0</upload:numFail>
  <entry>
    <link rel="update" type="image/jpeg" href="http://up1.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c546538" />
    <category term="image" scheme="http://openfly.shutterfly.com/ecom/v1.0" />
    <id>http://ws.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c546538</id>
    <sflyecom:ref>67b0de21b3022c546538</sflyecom:ref>
    <sflyecom:imagestate>WAITING_FOR_UPLOAD</sflyecom:imagestate>
  </entry>
</feed>

Output Feed

Content-Type

application/atom+xml

feed

category

<category-term="upload-result" scheme="http://upload.openfly.shutterfly.com/v1.0"/>

upload:errCode

Error code, 0 if upload was successful. See error codes below for more details

Count: 1

Example: 0

upload:errMessage

Error message, N/A if upload was successful. See error codes below for more details

Count: 1

Example: N/A

upload:numSuccess

Number of successful image uploads, will be either 0 or 1 for this protocol.

Count: 1

Amount: 0 - 1

Example: 1

upload:numFail

Number of failed image uploads, will be either 0 or 1 for this protocol.

Count: 1

Amount: 0 - 1

Example: 0

image entry

If upload succeeded, there will be an image entry with further details.

category

<category-term="image" scheme="http://openfly.shutterfly.com/ecom/v1.0"/>

sflyecom:ref

Shutterfly reference identifier, will uniquely identify an image within the order.

Count: 1

Example: 67b0de21b3022c546538

sflyecom:imagestate

Image state.

Count: 1

Example: WAITING_FOR_UPLOAD

Possible Values:

WAITING_FOR_UPLOAD

Shutterfly is waiting for the client to upload this image. The image is NOT available on Shutterfly and the order cannot proceed.

READY

The image has been successfully uploaded and is available. If all images are in READY state, the order can proceed in processing.

Error Codes

If there is no error, methods always return HTTP status code 200 (or 201 for a create operation). See Common Response Codes documentation.

If there is an error, the following codes may be returned.

Given HTTP 200, one of the following will be embedded in the <upload:errCode> and <upload:errMessage> elements of the returned XML feed.

0 : OK

1 : Invalid auth ID

2 : Auth ID missing

3 : Unexpected exception

4 : Invalid image format

5 : Album exception

6 : Invalid image ID

7 : Invalid offset

8 : File append exception

9 : Invalid state exception

10 : IO exception

11 : Archive exception

12 : Source View creation exception

13 : No image data

14 : Already archived

15 : NA

16 : Missing parameter

Method: GET

Queries the state of one or more images within an order. The purpose is to determine which images have been successfully uploaded from Shutterfly's perspective.

The caller is returned an Atom feed.

http://ws.shutterfly.com/order/000012345678-8000012/image

All images are being requested, and each image within order will be an entry within the output feed.

http://ws.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c546538

A single image is being requested, and the image data will be at the feed level. There will be no entries within the feed.

Note: below documentation is for first example. The second example will have the same parameters at the feed level.

User authorization

User authorization is required for this method. Please see the user authorization documentation for more details.

Sample Output

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:openfly="http://openfly.shutterfly.com/v1.0"
      xmlns:sflyecom="http://openfly.shutterfly.com/ecom/v1.0">
  <link rel="self" href="http://ws.shutterfly.com/order/000012345678-8000012/image" />
  <id>http://ws.shutterfly.com/order/000012345678-8000012/image</id>
  <entry>
    <link rel="update" type="image/jpeg" 
      href="http://up1.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c55e409" />
    <category term="image" scheme="http://openfly.shutterfly.com/ecom/v1.0" />
    <id>http://ws.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c55e409</id>
    <sflyecom:ref>67b0de21b3022c55e409</sflyecom:ref>
    <sflyecom:imagestate>READY</sflyecom:imagestate>
  </entry>
  <entry>
    <link rel="update" type="image/jpeg" 
      href="http://up1.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c546538" />
    <category term="image" scheme="http://openfly.shutterfly.com/ecom/v1.0" />
    <id>http://ws.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c546538</id>
    <sflyecom:ref>67b0de21b3022c546538</sflyecom:ref>
    <sflyecom:imagestate>WAITING_FOR_UPLOAD</sflyecom:imagestate>
  </entry>
  <entry>
    <link rel="update" type="image/jpeg" 
      href="http://up1.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c52653e" />
    <category term="image" scheme="http://openfly.shutterfly.com/ecom/v1.0" />
    <id>http://ws.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c52653e</id>
    <sflyecom:ref>67b0de21b3022c52653e</sflyecom:ref>
    <sflyecom:imagestate>READY</sflyecom:imagestate>
  </entry>
</feed>

Output Feed

feed

category

<category-term="image" scheme="http://openfly.shutterfly.com/ecom/v1.0"/>

image entry

category

<category-term="image" scheme="http://openfly.shutterfly.com/ecom/v1.0"/>

link - update

Each image will supply an "update" link, which gives to location that the image should be uploaded to if necessary. Please note that uploads should NOT be done to the <id> URI.

Count: 1

Example: <link rel="update" type="image/jpeg" href="http://up1.shutterfly.com/order/000012345678-8000012/image/67b0de21b3022c55e409"/>

sflyecom:ref

Shutterfly reference identifier, will uniquely identify an image within the order.

Count: 1

Example: 67b0de21b3022c546538

sflyecom:imagestate

Image state.

Count: 1

Example: WAITING_FOR_UPLOAD

Possible Values:

WAITING_FOR_UPLOAD

Shutterfly is waiting for the client to upload this image. The image is NOT available on Shutterfly and the order cannot proceed.

READY

The image has been successfully uploaded and is available. If all images are in READY state, the order can proceed in processing.

Error Codes

If there is no error, methods always return HTTP status code 200 (or 201 for a create operation). See Common Response Codes documentation.

This API has no specific error codes, only the common HTTP responses will be returned.

Frequently Asked Questions

Upload

My upload doesn't work. It gets strange exceptions, like "IOException caught reading the stream". What's wrong?

POST multipart/form-data is not easy to program correctly. You must follow RFC1867 exactly, right down to the placement of empty lines (CRLF). Shutterfly recommends that you find a library routine in your programming language to do the job for you, or that you use the API Explorer for Image Upload to see what Shutterfly's Java library would generate.

Why is my image in WAITING_FOR_UPLOAD state?

This order was placed without the images being on Shutterfly yet, and this particular image has not yet been uploaded.

How do I upload a WAITING_FOR_UPLOAD image?

Please refer to the order upload API for further information on how to upload an ordered image.

How do I specify an image already within a Shutterfly album for this order?

We do not support album images for ordering at the current time. The image must be re-uploaded using the order upload API.

All images are in READY state, why is my order not processing?

Orders must be set to processing state using the order state API once all images are successfully uploaded.

Shutterfly Open API | Order Image

Description

Call Signature

Resource Path

Methods

Scheme

Host

Method: POST

User authorization

Sample Input

Input Parameters

Sample Output

Output Feed

feed

image entry

Error Codes

Method: GET

User authorization

Sample Output

Output Feed

feed

image entry

Error Codes

Frequently Asked Questions

Upload