Image2ART REST API

The Image2ART REST API is an e-commerce interface for managing orders from New Era Portfolio. This is running API 1.0-beta.

Core Concepts

Environment Settings

New Era provides multi-environment support for development and staging configurations.

EnvironmentURLRequires SSLRequires Unique UsernameApproval Required
Testinghttp://api-testing.image2art.comNONONO
Staginghttp://api-stage.image2art.comNOYESYES
Production Test Modehttp://api.image2art.comNOYESYES
Productionhttps://api.image2art.comYESYESYES

Ready to get started?

Make note of the test username and secret key below and then head on over to the Examples section to start submitting test API requests. You should be up and running in as little as 5 minutes!

After you're comfortable and get a feel for it head on over to the Authentication to get your own username and secret key for access to your own Staging environment.

usernamesecret key
testing$2y$08$tEwCIc9DxDNKRvzHhfRRlOHxDbu.MyIk5EnzEmZVEJ/GeuHXa.tki

Orders

GET /orders

Returns all orders for a given username

ParameterDescriptionRequiredDefault
usernameYour api usernameYES
signatureThe request signatureYES
rowsThe number of results to returnNO20
startThe starting indexNO0

example request

curl -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"username":"testing", "signature": "..."}' \
    https://api.image2art.com/orders

response

{
    "orders": [
        {
            "id": 1000000,
            "status": "Pending",
            "purchase_date": "2013-12-01 12:34:56",
            "is_test": true,
            "notes": "Test Order",
            "total_price": 500,
            "total_items": 2,
            "items": [
                {
                    "id": 2000001,
                    "sku": "c07ced46866b1730",
                    "gp_sku": "MP148A-40x40-CG-F0000-ML000",
                    "quantity": 1,
                    "item_sale_price": 275,
                    "sale_price": 250,
                    "item_price": 275,
                    "final_price": 250,
                    "image": {
                        "name": "Dancing on the Water",
                        "code": "MP148A",
                        "artist": "Maxine Price"
                    },
                    "specs": {
                        "image_size": "40x40",
                        "print_size": "44x44",
                        "outer_size": "40x40",
                        "frame_code": "F0000",
                        "matte_code": "ML000",
                        "border_width": 2,
                        "border_color": "BLUR",
                        "stretcher_bar": "1.5 SB"
                    }
                },
                {
                    "id": 2000002,
                    "sku": "9b7d254d9ce6f163",
                    "gp_sku": "V00551-24x18-PF-F0092-ML002",
                    "quantity": 1,
                    "item_sale_price": 275,
                    "sale_price": 250,
                    "item_price": 275,
                    "final_price": 250,
                    "image": {
                        "name": "Starry Night",
                        "code": "V00551",
                        "artist": "Vincent Van Gogh"
                    },
                    "specs": {
                        "image_size": "24x18",
                        "print_size": "30x24",
                        "outer_size": "34x28",
                        "frame_code": "F0092",
                        "matte_code": "ML002",
                        "border_width": 3,
                        "border_color": "BRD",
                        "stretcher_bar": ""
                    }
                }
            ],
            "customer": {
                "name": "John Doe",
                "company": "Doe & Associates",
                "address": "123 Fake St.",
                "city": "Austin",
                "state": "TX",
                "zip": "78744",
                "country": "US",
                "phone": "512-123-4567",
                "email": "jdoe@newerahd.com"
            },
            "shipping": {
                "name": "Jane Doe",
                "company": "",
                "address": "456 False Ln.",
                "city": "Austin",
                "state": "TX",
                "zip": "78705",
                "country": "US"
            }
        },
        {
            "id": 1000001,
            "status": "Pending",
            "purchase_date": "2013-12-01 12:34:56",
            "is_test": true,
            "notes": "Test Order",
            "total_price": 500,
            "total_items": 2,
            "items": [
                {
                    "id": 2000001,
                    "sku": "c07ced46866b1730",
                    "gp_sku": "MP148A-40x40-CG-F0000-ML000",
                    "quantity": 1,
                    "item_sale_price": 275,
                    "sale_price": 250,
                    "item_price": 275,
                    "final_price": 250,
                    "image": {
                        "name": "Dancing on the Water",
                        "code": "MP148A",
                        "artist": "Maxine Price"
                    },
                    "specs": {
                        "image_size": "40x40",
                        "print_size": "44x44",
                        "outer_size": "40x40",
                        "frame_code": "F0000",
                        "matte_code": "ML000",
                        "border_width": 2,
                        "border_color": "BLUR",
                        "stretcher_bar": "1.5 SB"
                    }
                },
                {
                    "id": 2000002,
                    "sku": "9b7d254d9ce6f163",
                    "gp_sku": "V00551-24x18-PF-F0092-ML002",
                    "quantity": 1,
                    "item_sale_price": 275,
                    "sale_price": 250,
                    "item_price": 275,
                    "final_price": 250,
                    "image": {
                        "name": "Starry Night",
                        "code": "V00551",
                        "artist": "Vincent Van Gogh"
                    },
                    "specs": {
                        "image_size": "24x18",
                        "print_size": "30x24",
                        "outer_size": "34x28",
                        "frame_code": "F0092",
                        "matte_code": "ML002",
                        "border_width": 3,
                        "border_color": "BRD",
                        "stretcher_bar": ""
                    }
                }
            ],
            "customer": {
                "name": "John Doe",
                "company": "Doe & Associates",
                "address": "123 Fake St.",
                "city": "Austin",
                "state": "TX",
                "zip": "78744",
                "country": "US",
                "phone": "512-123-4567",
                "email": "jdoe@newerahd.com"
            },
            "shipping": {
                "name": "Jane Doe",
                "company": "",
                "address": "456 False Ln.",
                "city": "Austin",
                "state": "TX",
                "zip": "78705",
                "country": "US"
            }
        }
    ]
}

GET /orders/:id

Get data for a specified order.

ParameterDescriptionRequiredDefault
usernameYour api usernameYES
signatureThe request signatureYES

example request

curl -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"username":"testing", "signature": "..."}' \
    https://api.image2art.com/orders/1000001

response

{
    "id": 1000001,
    "status": "In Transit",
    "purchase_date": "2013-12-01 12:34:56",
    "is_test": true,
    "notes": "Test Order",
    "total_price": 250,
    "total_items": 1,
    "items": [
        {
            "id": 2000001,
            "sku": "c07ced46866b1730",
            "gp_sku": "MP148A-40x40-CG-F0000-ML000",
            "quantity": 1,
            "item_sale_price": 275,
            "sale_price": 250,
            "item_price": 275,
            "final_price": 250,
            "image": {
                "name": "Dancing on the Water",
                "code": "MP148A",
                "artist": "Maxine Price"
            },
            "specs": {
                "image_size": "40x40",
                "print_size": "44x44",
                "outer_size": "40x40",
                "frame_code": "F0000",
                "matte_code": "ML000",
                "border_width": 2,
                "border_color": "BLUR",
                "stretcher_bar": "1.5 SB"
            }
        }
    ],
    "customer": {
        "name": "John Doe",
        "company": "Doe & Associates",
        "address": "123 Fake St.",
        "city": "Austin",
        "state": "TX",
        "zip": "78744",
        "country": "US",
        "phone": "512-123-4567",
        "email": "jdoe@newerahd.com"
    },
    "shipping": {
        "name": "Jane Doe",
        "company": "",
        "address": "456 False Ln.",
        "city": "Austin",
        "state": "TX",
        "zip": "78705",
        "country": "US",
        "tracking": [
            {
                "number": "12313123",
                "method": "FedEx Home Delivery"
            },
            {
                "number": "123123123",
                "method": "UPS 2-day"
            }
        ]
    }
}

Responds with 403 Forbidden if access to the order is restricted.
Responds with 404 Not Found if the order does not exist.

example 403 response

{
    "error_code": 403,
    "error": {
        "short_message": "Not authorized.",
        "long_message": "You are not authorized to access the requested resource."
    }
}

example 404 response

{
    "error_code": 404,
    "error": {
        "short_message": "Not found.",
        "long_message": "The requested resource was not found."
    }
}

POST /orders

Create a new Order by sending "order" JSON with parameters listed below. An order is a collection of objects like "customer", "shipping", "items" and "extra" each item is described in detail in the Platform Objects section.

ParameterDescriptionRequired
usernameYour API usernameYES
signatureThe request signatureYES
external_order_numberOptional order number that can be used for trackingNO
customer[name]The customer's name.YES
customer[company]The customer's company name.NO
customer[email]The customer's email addressYES
customer[phone]The customer's phone numberYES
customer[address]The customer's street address.YES
customer[address2]NO
customer[city]The customer's city.YES
customer[state]The customer's state.YES
customer[zip]The customer's zip code.YES
customer[country]The customer's country code.YES
shipping[name]The customer's name.YES
shipping[company]The customer's company name.NO
shipping[address]The customer's street address.YES
shipping[address2]NO
shipping[city]The customer's city.YES
shipping[state]The customer's state.YES
shipping[zip]The customer's zip code.YES
shipping[country]The customer's country code.YES
shipping[method]An optional shipping method. See list below.NO
shipping[packing_slip]An option url to a custom packing slip.NO
billing[name]The customer's name.NO
billing[company]The customer's company name.NO
billing[address]The customer's street address.NO
billing[address2]NO
billing[city]The customer's city.NO
billing[state]The customer's state.NO
billing[zip]The customer's zip code.NO
billing[country]The customer's country code.NO
items[][sku]The base SKU for the ItemYES
items[][image][type]The image type. Allowed values are newera and externalNO
items[][image][code]The New Era exclusive image code.YES*
items[][image][url]The url to an external image.YES*
items[][image][edition]Edition number as a string (e.g. "15 of 950")NO
items[][border][type]The border type. Allowed values are mirror, blur and color.NO
items[][border][size]The border width in inches.NO
items[][border][color]The border color. Any valid CSS color is allowed.NO
items[][notes]Optional item notes.NO
items[][external_item_number]An optional id number that can be used for trackingNO
items[][security_hardware]Defaults to false. Set to true if security hardware should be installed on the piece.NO
items[][sidemark]A note to be placed on the shipping box.NO

example request

curl -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X POST \
    -d '{
    "username": "testing",
    "signature": "...",
    "customer": {
        "phone": "512-928-3200",
        "email": "bmaxwell@newerahd.com",
        "name": "bryan maxwell",
        "company": "new era portfolio",
        "address": "2101 e st elmo",
        "city": "austin",
        "state": "tx",
        "zip": "78745",
        "country": "US"
    },
    "shipping": {
        "name": "bryan maxwell",
        "company": "new era portfolio",
        "address": "2101 e st elmo",
        "city": "austin",
        "state": "tx",
        "zip": "78745",
        "country": "US"
    },
    "billing": {
        "name": "bryan maxwell",
        "company": "new era portfolio",
        "address": "2101 e st elmo",
        "city": "austin",
        "state": "tx",
        "zip": "78745",
        "country": "US"
    },
    "items": [
        {
            "quantity": 1,
            "sku": "3a76fa8cfe722eb7",
            "image": {
                "type": "external",
                "url": "http://www.gallerydirect.com/uploads/test.jpg"
            },
            "notes": "Please leave on front porch. -Customer"
        }
    ]
}' \
https://api.image2art.com/orders

response

{
    order: {
        id: 10001
    }
}

Shipping Methods

The following shipping methods are allowed. The default is best way.

iddescription
----------
fedexFed-Ex
fedex 2dayFed-Ex 2 Day
fedex 3dayFed-Ex 3 Day
fedex expressFed-Ex Express
fedex freightFed-Ex Freight
fedex groundFed-Ex Ground
fedex overnightFed-Ex Overnight
upsUPS
ups groundUPS Ground
ups overnightUPS Overnight
uspsUSPS

PUT /orders/:id

Update an order

shipping[name]The customer's name.NO
shipping[company]The customer's company name.NO
shipping[address]The customer's street address.NO
shipping[address2]NO
shipping[city]The customer's city.NO
shipping[state]The customer's state.NO
shipping[zip]The customer's zip code.NO
shipping[country]The customer's country code.NO

example request

curl -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X PUT \
    -d '{"username": "testing","signature": "...","shipping":{"name":"John Doe"}}' \
    https://api.image2art.com/orders/10001

response

{
    "order": {
        "id": 10001
    },
    "affectedRows": 1
}

Responds with 403 Forbidden if access to the order is restricted.
Responds with 404 Not Found if the order does not exist.

example 403 response

{
    "error_code": 403,
    "error": {
        "short_message": "Not authorized.",
        "long_message": "You are not authorized to access the requested resource."
    }
}

example 404 response

{
    "error_code": 404,
    "error": {
        "short_message": "Not found.",
        "long_message": "The requested resource was not found."
    }
}

DELETE /orders/:id

Delete a specified order.

Note: This method is currently unavailable and returns a 501 response code.

example request

curl -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -X DELETE \
    -d '{"username": "testing","signature": "..."}' \
    https://api.image2art.com/orders/10001

response

{
    "order": {
        "id": 10001
    },
    "affectedRows": 1
}

Responds with 403 Forbidden if access to the order is restricted.
Responds with 404 Not Found if the order does not exist.

example 403 response

{
    "error_code": 403,
    "error": {
        "short_message": "Not authorized.",
        "long_message": "You are not authorized to access the requested resource."
    }
}

example 404 response

{
    "error_code": 404,
    "error": {
        "short_message": "Not found.",
        "long_message": "The requested resource was not found."
    }
}

General

GET /

Return this HTML documentation or a JSON representation of the API, depending on the request "Accept" header.

example JSON response

{
  "endpoints": [
    "GET    /orders",
    "GET    /orders/:id",
    "POST   /orders",
    "PUT    /orders/:id",
    "DELETE /orders/:id",
    "GET    /",
    "GET    /ping"
  ],
  "version": "1.0-beta"
}

GET /ping

General health check: "Is the server up?" If basic auth credentials are provided, then authorization will be attempted and, on success, some authorized user data shown in the response.

This method is currently only available in testing and staging environments.

example request

curl -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{"username": "testing","signature": "..."}' \
    https://api-staging.image2art.com/ping

response

{
    "pong": "ping",
    "user": {
        "username": "testing",
        "email": "testing@newerahd.com"
    }
}

Authentication

We use HMAC and SHA256 to sign requests for authentication. You will be given a username and secret key that you can use to sign your requests. Below is a code sample of how requests are signed. Essentially the URL you're calling, say, orders is concatenated against the JSON you're going to send with the request to create the signature.

Example: Signing a Request in PHP

<?php
/**
 * Sign a string using the user's secret key
 *
 * @param  string $uri  API request path
 * @param  array  $data data being send with the request to be signed
 * @return string       HMAC-SHA256 hash
 */
public function signRequest($uri, $data = array()) {
    // ignore username and signature if provided
    if (isset($data['username'])) {
        unset($data['username']);
    }
    if (isset($data['signature'])) {
        unset($data['signature']);
    }

    $data['username'] = 'YOUR USERNAME HERE';

    $req = $uri.json_encode($data);

    return hash_hmac('sha256', $req, 'YOUR SECRET KEY HERE');
}

Example: Data and Signature

Data: orders{"start":0,"rows":20,"username":"testing"}
Signature: 16a060c526f2c460815567d73e05a4cdaf48e9ee2e3b9858e9b6933011ad798b

Platform Objects

Note: This section is still a work in progress.

Images

An image refers to a digital asset. It can be a New Era exclusive image or from an external source.

FieldTypeDescription
typestringThe image type. Allowed values are newera and external
codestringThe New Era exclusive image code.
urlstringThe url to an external image.

Addresses

An Address can be used for both shipping and billing information.

FieldTypeDescription
namestringThe addressee's name.
companystringThe addressee's company name.
addressstringThe addressee's street address.
address2string
citystringThe addressee's city.
statestringThe addressee's state.
zipstringThe addressee's zip code.
countrystringThe addressee's country code.

Customers

A Customer is an extended Address with additional required fields for email and telephone number.

FieldTypeDescription
namestringThe customer's name.
companystringThe customer's company name.
emailstringThe customer's email address
phonestringThe customer's phone number
addressstringThe customer's street address.
address2string
citystringThe customer's city.
statestringThe customer's state.
zipstringThe customer's zip code.
countrystringThe customer's country code.

Items

Line items, or more simply, Items are individual units to be produced. The most basic Items are made up of a SKU and a quantity. In this case the product information can be looked up by the SKU. Items can also be overloaded with custom Images.

FieldTypeDescription
skustringThe base SKU for the Item
quantityintThe item quantity. This is the total number of units to be produced.
imageImageThe image data to override the basic SKU
border[type]stringThe border type. Allowed values are mirror, blur and color.
border[size]intThe border width in inches.
border[color]stringThe border color. Any valid CSS color format is allowed.
notesstringOptional item notes.
external_item_numberstringAn optional id number that can be used for tracking

Orders

Orders are made up of Items that are printed, framed and shipped to Customers.

FieldTypeDescription
external_order_numberstringAn optional id number that can be used for tracking
customerCustomerThe Customer data for this order.
shippingAddressThe shipping Address data for this order.
billingAddressThe billing **Address data for this order.
itemsItem[]An array of Items

Order Status

Errors & Rate Limits

If there is an error during an API request you will receive a standard error response object from the server. The object will contain an "error_code" and a long/short error message. The short message gives you a high level idea of what went wrong where as the long message should be verbose enough to tell you exactly what was wrong. You will also receive the error message and code in the headers via the X-Erorr-Code and X-Error-Message header. You can see both the error response object and error headers below.

Example: Error Response

{
    "error": {
        "short_message": "Authentication Failed.",
        "long_message": "Signature is not valid"
    },
    "error_code": 112
}

Example: Error Request Headers

Notice the X-Error- headers

HTTP/1.1 400 Bad Request
Date: Mon, 30 Dec 2013 18:20:21 GMT
Server: Apache
X-Powered-By: PHP/5.3.27
Set-Cookie: laravel_session=htigio9k0g74e6iq8870q6osa5; expires=Mon, 30-Dec-2013 20:20:21 GMT; path=/; HttpOnly
Set-Cookie: laravel_session=htigio9k0g74e6iq8870q6osa5; expires=Mon, 30-Dec-2013 20:20:21 GMT; path=/; httponly
Cache-Control: no-cache
X-Rate-Limit: 200
X-Rate-Limit-Remaining: 194
X-Error-Code: 112
X-Error-Message: Signature is not valid
Connection: close
Transfer-Encoding: chunked
Content-Type: application/json

API Errors

Text below shows the error code and error long message portion of the error response object.

Order Errors

Order Item Errors

Rate Limits

Every consumer is given a rate limit for various endpoints. The rate limit is very liberal to allow for successful calls in almost every circumstance. The rate limit is there simply to catch a hack attempt/abuse against New Era's servers. You will be assigned rate limits for each GET and POST action available for each endpoint. Your rate limit status is returned to you in the response headers of each call. Rate limits reset every 24 hours.

Example: Response headers from POST to /orders

X-Rate-Limit: 200
X-Rate-Limit-Remaining: 194

API Client & SDK

We are working hard to provide example clients for the REST API. Right now we only have a PHP client written but we're working on a Python client and will continue adding more as requirements arise. This should get you started though with useful examples and demonstrations of how API calls are made to New Era using the API.

Widget

The Image2Art widget is an embeddable javascript widget that allows your customers the ability to configure and frame their custom artwork. When the customer adds an item to their cart the data is sent back to your system, seamlessly integrating Image2Art products with your own inventory.

To embed the widget you will need to add the following HTML snippet to your site. It requires a different API key that you will receive from your Image2Art support contact.

<script id="nep_widget" type="text/javascript" src="http://api.image2art.com/widget/v1/code.js?api_key=your api key"></script>
<div id="box_widget"></div>

Note: The script tag must have nep_widget as the id attribute and the box_widget div is required to contain the widget in the DOM.

After including the script tag above you may set the following configurations for widget functionality.

<script type="text/javascript">
	image2art.widget.setOptions({
		CustomerId: <your_user's_unique_id> // Only set this if your user is logged into your site. Otherwise set to null.
		LoginUrl: <url> // Your site's login page.
		AuthRequired: {
			projects: true|false, // Set to true if user must be logged in to create and manage projects.
			pricing: true|false // Set to true if user must be logged in to view pricing.
		},
		ShowHardwareOption: true|false // Show security hardware option for eligible substrates.
	});
</script>

The user is determined whether or not they are logged in by the presence of a CustomerId. If a user is NOT logged in and authentication is required for either projects or pricing, they will be prompted to log in upon interacting with those features. They will be redirected back to the URL provided in the LoginUrl property. You must exclude any query string parameters on this URL. We will attach a query string parameter of redirect_url which will provide a URL to redirect the user back to upon successful authentication so that they don't lose their spot within the widget.

Style Customization

The Image2Art widget using HTML and CSS so you can customize the styles to match to your site's lookand feel. To allow a flexible customization without interfering with your site's style, all widget styles are prefixed with the #nep_widget selector.

/* Customizing code must be included in the widget host site css files */
/* Search page assets left side bar --> Change background color to gray */
#nep_widget #sidebar{
    background: gray;
}

/* Search page images container --> Change background color to gray */
#nep_widget #images{
    background: gray;
}

/* Product page --> Change the image title font size */
#nep_widget h3 {
    font-size:14px !important;
}

Events

The Image2Art widget provides a number of event callbacks that allow you to hook in to the initialization and rendering process.

EventDescription
widget:readyFired when the widget has included all dependencies
widget:loadedFired after the widget.initialize() function runs
widget:price:changeFired on product page when an option is selected
widget:price:changedFired after the price display has been updated

Currently event handlers must be bound to the global window using the $ (jQuery) variable in the image2art namespace.

Example

<script>
    image2art.$(window).on('widget:ready', function(event) {
        // widget ready code
    });
</script>

Custom Price Control

The prices shown in the widget are configured in the Image2Art Admin Panel and by default represent the wholesale price. In some instances, however, it is more desirable to set prices dynamically. To accomplish this, the Image2Art Widget provides a setPrice callback that is passed product information each time a different configuration option is selected. To override this function simply redefine image2art.widget.setPrice in a script tag after including the nep_widget script.

The following example increases framed paper prices by 50% and every thing else by 25%.

<script>

image2art.widget.setPrice = function(product) {
    if (product["style"] == "PF") {
        product["price"] * 1.5;
    }

    return product["price"] * 1.25;
};

</script>

In this example, a sku price list is pregenerated and used as a lookup by setPrice:

<script>
    var skuPrices = {
        "sku1": 139,
        "sku2": 159,
        "sku3": 179
    }

    image2art.widget.setPrice = function(product) {
        if (skuPrices[product["sku"]]) {
            return skuPrices[product["sku"]];
        }

        return product["price"]
    }
</script>

Adding to Cart

Adding Image2Art products to your cart is seamless via the cart receivable path, a custom url on your domain. When a user clicks add to cart in the widget, the product data is sent to your cart receivable path via POST. This allows you to programatically handle the product in your system.

Example POST data:

{
  "artist": "Price, Maxine",
  "description": "Unlike some parts of Texas, the trees in Kerrville turn
   golden, yellow and red, particularly along the Guadalupe River which
   flows through the town. Maxine Price was intrigued by the upside down
   reflections of the trees on the far bank of the river combined with the
   overhanging branches of the trees on the near side. She has painted
   several scenes from that day on the Guadalupe including \"Dancing on the
   Water\". She uses not only her own photos as reference but her memory and
   feelings about day and the scene to paint from.",
  "frame": "F0092",
  "image_code": "MP148A",
  "image_size": "12x12",
  "inner_size": "18x18",
  "outer_size": "22x22",
  "preview": "http://imageset2.newerahd.com/cached/49/MP148A_F0092_ML000_PF_20_600.jpg",
  "price": 39,
  "size": "S",
  "sku": "473784f02f26d24f",
  "style": "PF",
  "substrate": "paper",
  "title": "Dancing on the Water",
  "url": "http://widgetdemo.image2art.com/#/product/edit/MP148A/paper/PF/F0092/S"
}

Glossary

Below you will find a list of terms and their meanings/descriptions with pictures where applicable.