Requirements

Some experience with a commonly used programming language
Knowledge of how to send JSON requests via either GET or POST.
Register at FinerWorks
Get API Authentication Credentials
Completed business profile
Completed billing profile (payment and billing address)

Steps to Get Started

key

Step 1 — Getting Your Authentication Credentials

To get started you will need to retrieve your web_api_key and app_key. Both can be found when you log in to your FinerWorks account. These should be included as request parameters in the header of any request. Alternatively, you can include these as querystring parameters in the request URI.

code

Step 2 — Build Your App

You can build on the platform of your choice. For initial development we recommend Postman, which allows you to test your calls and even generate sample code you can use in your application. FinerWorks does not provide direct programming support, so we won't be able to tell you how to “code”. If coding is beyond your abilities, we recommend finding someone with experience building apps that use RESTful APIs.

science

Step 3 — Test Your App

While you are building and testing your app, your app credentials should be set to test mode, or your API calls should include a "test_mode = true" flag.

info

While in test mode, nothing will be processed or billed for orders placed through that app. All responses will be valid and simulate what you'd receive in a live environment, so you can build your app accordingly.

rocket_launch

Step 4 — Go Live

When you have completed testing and are ready to go live, switch your app_key to "live" mode, or change your API calls to "test_mode = false". You can change your app_key out of test mode from the FinerWorks account where you retrieved your API authentication credentials. Once your app is live, any orders you place will be processed unless you cancel or place an order on hold.

End Points Reference List

You are responsible for ensuring the privacy of your customers' data when it's submitted. SSL is therefore recommended, though it is not required at this time. View the Help page for the full list of endpoint and method combinations.

Click here for a list of endpoint uris and examples.

About Providing Product Info

When submitting orders you will be required to provide a "sku" from your FinerWorks virtual inventory. Alternatively, you can provide a Product Code in place of a sku, which represents the style to print and options along with the appropriate image files. Product codes can be found within the various product pages, or whenever you set up a print online at FinerWorks.com.

Shipping

Using Shipping Class Codes (Deprecated)

warning

This method has been deprecated. We now recommend using the Shipping Id as described below.

Below are available general shipping classification codes, however you can also provide a more specific "shipping code" if you have it.

shipping_code	description	Transit Time Avg	Notes
EC	Economy	3-7 days	Goes the least expensive method
SD	Standard	2-5 days	Usually goes via a ground shipping method offered by one of the three major carriers.
EX	Express	2-3 days	Usually goes via UPS or FEDEX 2 day or Priority Mail (which ever is estimated faster)
ON	Overnight	1-2 days	Usually goes via Next Day Air or Express Mail. May not be available for some orders in which case the fastest method will be selected.

Using Shipping Id to Pass on Shipping to Customer

Using the shipping id provides a more accurate approach in making sure that the exact shipping method is being submitted. Below is a typical workflow that you might implement.

Future Development and Changes

Overtime FinerWorks will offer additional options and make structural changes based on products and services being offered. Structural changes should not create any disruption to existing applications.

Billing Policy

There are no fees to develop or use the API however once you go live and submit valid orders, you will be required to have a credit card on file in which we will bill you for all pending orders submitted prior to noon of that day. In the event that a card is declined for any reason, you will be notified by email so that appropriate arrangements can be made to update your account with a new card. We will attempt to rebill the following business day for those orders and any new orders. If a card still fails after a 3^rd attempt, or there's no response by the 4^th business day, any pending orders will be cancelled and will need to be resubmitted.

Code Examples

Below is some actual example code formatted for popular programming languages. The samples utilize the endpoint to Get Product Details as an example. You can use this as a template for calling the other endpoints or use the sample code provided with each endpoint documentation page. In many cases you will only need to change the endpoint uri and the JSON in the body of the request. All endpoints can be found here.

curl --location --request POST 'https://v2.api.finerworks.com/v3/get_product_details' \
--header 'Content-Type: application/json' \
--header 'web_api_key: my-web-api-key-goes-here' \
--header 'app_key: my-app-key-goes-here' \
--data-raw '[{
    "product_order_po": null,
    "product_qty": 3,
    "product_sku": "AP6543P49875"
},
{
    "product_order_po": null,
    "product_qty": 3,
    "product_sku": "AP6543P58353"
}]'

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://v2.api.finerworks.com/v3/get_product_details');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
    'follow_redirects' => TRUE
));
$request->setHeader(array(
    'Content-Type' => 'application/json',
    'web_api_key' => 'my-web-api-key-goes-here',
    'app_key' => 'my-app-key-goes-here'
));
$request->setBody('[{
        "product_order_po":null,
        "product_qty": 3,
        "product_sku": "AP6543P49875"
},
{
        "product_order_po":null,
        "product_qty": 3,
        "product_sku": "AP6543P58353"
}
]');
try {
    $response = $request->send();
    if ($response->getStatus() == 200) {
        echo $response->getBody();
    }
    else {
        echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
            $response->getReasonPhrase();
    }
}
catch(HTTP_Request2_Exception $e) {
    echo 'Error: ' . $e->getMessage();
}

var client = new RestClient("https://v2.api.finerworks.com/v3/get_product_details");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("web_api_key", "my-web-api-key-goes-here");
request.AddHeader("app_key", "my-app-key-goes-here");
request.AddParameter("application/json", "[{\r\n  \"product_order_po\":null,\r\n  \"product_qty\": 3,\r\n  \"product_sku\": \"AP6543P49875\"\r\n},\r\n{\r\n  \"product_order_po\":null,\r\n  \"product_qty\": 3,\r\n  \"product_sku\": \"AP6543P58353\"\r\n}\r\n]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

var settings = {
    "url": "https://v2.api.finerworks.com/v3/get_product_details",
    "method": "POST",
    "timeout": 0,
    "headers": {
        "Content-Type": "application/json",
        "web_api_key": "my-web-api-key-goes-here",
        "app_key": "my-app-key-goes-here"
    },
    "data": JSON.stringify([
        { "product_order_po": null, "product_qty": 3, "product_sku": "AP6543P49875" },
        { "product_order_po": null, "product_qty": 3, "product_sku": "AP6543P58353" }
    ]),
};

$.ajax(settings).done(function (response) {
    console.log(response);
});

var https = require('follow-redirects').https;

var options = {
    'method': 'POST',
    'hostname': 'v2.api.finerworks.com',
    'path': '/v3/get_product_details',
    'headers': {
        'Content-Type': 'application/json',
        'web_api_key': 'my-web-api-key-goes-here',
        'app_key': 'my-app-key-goes-here'
    },
    'maxRedirects': 20
};

var req = https.request(options, function (res) {
    var chunks = [];
    res.on("data", function (chunk) { chunks.push(chunk); });
    res.on("end", function () {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
    });
    res.on("error", function (error) { console.error(error); });
});

var postData = JSON.stringify([
    { "product_order_po": null, "product_qty": 3, "product_sku": "AP6543P49875" },
    { "product_order_po": null, "product_qty": 3, "product_sku": "AP6543P58353" }
]);

req.write(postData);
req.end();

require "uri"
require "net/http"

url = URI("https://v2.api.finerworks.com/v3/get_product_details")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["web_api_key"] = "my-web-api-key-goes-here"
request["app_key"] = "my-app-key-goes-here"
request.body = "[{\r\n  \"product_order_po\":null,\r\n  \"product_qty\": 3,\r\n  \"product_sku\": \"AP6543P49875\"\r\n},\r\n{\r\n  \"product_order_po\":null,\r\n  \"product_qty\": 3,\r\n  \"product_sku\": \"AP6543P58353\"\r\n}\r\n]"

response = https.request(request)
puts response.read_body

Product Codes and SKUs

Product codes and SKUs serve distinct purposes in managing and ordering products.

Product Codes

Product codes are used when supplying images for printing during the ordering process. They help specify the desired printing surface and are particularly useful for obtaining pricing information, shipping rates, or creating test orders. FinerWorks employs product codes to indicate the composition of a print product, encompassing the media type, mounting, and framing options. These codes consist of a series of ID numbers separated by delimiters, with each ID type representing a specific attribute (see example further below).

SKUs

SKUs are entered in the "product_sku" field of various API calls when ordering or managing products from your inventory. SKUs are beneficial when you have identical printed items to submit for ordering at different times. Similar to wish lists on other websites, SKUs are unique identifiers generated for each inventory item. They encompass all the relevant details, including the designated image for printing, allowing for efficient tracking and management of your inventory.

By leveraging product codes and SKUs, you can streamline the ordering process and effectively manage your inventory of printed items.

Breaking Down a Product Code

Below is an example of a product code for Archival Matte Paper print and its breakdown

5M6M9S16X20

Product Type ID	Delimiter	Media ID	Delimiter	Mounting/Style ID	Delimiter	Width	Height
5	M	6	M	9	S	16	20

Below is an example of a product code for a frame package that could be used with this print or just by itself.

F96S20X24J1S16X20G1

Delimiter	Frame ID	Delimiter	Width	Height	Delimiter	Mat ID	Delimiter	Window Width	Window Height	Delimiter	Glazing ID
F	96	S	20	24	J	1	S	16	20	G	1

Combining both Product Codes for a Print & Frame

5M6M9S16X20F96S20X24J1S16X20G1

P.O.S.T. Integration

block

P.O.S.T. integration is no longer supported following the removal of POST4. FinerWorks R&D is exploring how to reintroduce this functionality for POST5, but no timeline has been established yet.

P.O.S.T. (Print Online Setup Tool) is a web-based application that allows users to create their print-on-demand products for ordering and storing.

Getting Started