Introduction

The Printfection API is organized around REST to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors.

It uses built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON is returned in all responses from the API, including errors, and is expected as the body for all requests.

If you want to test our API without needing to set anything up, you can do it from our OpenAPI SwaggerUI version.

Conventions

  • All data is sent and received as JSON
  • Blank fields are included as null instead of being omitted
  • All timestamps are returned in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
  • Pagination: requests that list top-level objects are automatically limited to 100 objects per response. To page through responses, use the limit and offset query parameters. For example: GET /orders?offset=100&limit=50
  • Request limiting: authenticated requests are hard-limited to 1000 requests per hour. Subsequent requests will fail.

Usage Limitations

  • Only Giveaway and Collection campaigns are supported
  • Orders cannot be placed explicitly through the API at this time
  • Giveaway orders are placed once submitted by the end-user
  • Collection orders are gathered and can be placed (approved) within your Printfection account
  • Multiple items (lineitems) are only supported on the Collection campaign type

API Endpoint


https://api.printfection.com/v2/
Version: 2.0.3
Codename: We Have The Technology

Version History

  • 2.0.301/19/16Replace campaign_id property on order object with a campaign object
  • 2.0.208/11/15Collection campaign support (including multi-item support)
  • 2.0.107/28/15Giveaway campaign support
  • 2.0.009/30/14Initial API build and end-point support

Authentication

You authenticate to the Printfection API by providing your API key in every request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.


# Example Request
curl https://api.printfection.com/v2/campaigns -u <api_key>:

Items

The Item Object

id:
integer
object:
string Value is "item"
name:
string Name of the item
color:
string Color of the item, ex: "Green"
product:
object Contains information about the item's root product
created_at:
timestamp Datetime the item was created
sizes:
array size objects
stock:
stock object Only included if item has no sizes
assets:
array asset objects
campaigns:
array partial campaign objects 

// Example Object
{
  "id": 1,
  "object": "item",
  "name": "My Awesome T-Shirt",
  "color": "Green",
  "product": {
    "id": 123,
    "name": "American Apparel 50/50 T-Shirt"
  },
  "created_at": "2014-09-12T10:22:37Z",
  "campaigns": [],
  "sizes": [],
  "stock": {},
  "assets": []
}

Retrieving an item

Retrieves the details of an item in your account. Supply the unique item ID.

GET /items/:id

Arguments

id:
integer required

Returns

Returns an item object if a valid identifier was provided, and returns an error otherwise.


// Example Response
{
  "id": 1,
  "object": "item",
  "name": "My Awesome T-Shirt",
  "color": "Green",
  "product": {
    "id": 123,
    "name": "American Apparel 50/50 T-Shirt"
  },
  "created_at": "2014-09-12T10:22:37Z",
  "campaigns": [],
  "sizes": [],
  "stock": {},
  "assets": []
}

Listing all items

Lists all items in your account.

GET /items

Returns

Returns an array of item objects, sorted by the date they were created.


// Example Response
[
  {
    "id": 1,
    "object": "item",
    "name": "My Awesome T-Shirt",
    "color": "Green",
    "product": {
      "id": 123,
      "name": "American Apparel 50/50 T-Shirt"
    },
    "created_at": "2014-09-12T10:22:37Z",
    "campaigns": [],
    "sizes": [],
    "assets": []
  },
  {
    "id": 2,
    "object": "item",
    "name": "Amazing Water Bottle",
    "color": "Clear",
    "product": {
      "id": 124,
      "name": "32oz Nalgene Water Bottle"
    },
    "created_at": "2014-09-12T10:22:37Z",
    "campaigns": [],
    "sizes": [],
    "stock": {},
    "assets": []
  }
]

Sizes

The Size Object

id:
integer
object:
string Value is "size"
name:
string Name of the size, ex: "Medium" or "Extra Large"
short_name:
string Shortened name of the size, ex: "M" or "XL"
stock:
stock object 

// Example Object
{
  "id": 1,
  "object": "size",
  "name": "Medium",
  "short_name": "M",
  "stock": {}
}

Stock

The Stock Object

available:
integer Total inventory physically in stock minus inventory allocated to non shipped orders. Can be negative if stock in-route is allocated to orders before received into inventory. 

// Example Object
{
  "available": 10,
}

Assets

The Asset Object

id:
integer
object:
string Value is "asset".
name:
string Name of the file.
perspective:
string Name of the perspective. Often describes the perspective, ex: "front" or "back" or "sleeve"
type:
object Type of the asset {design, printable}.
url:
object The URL to the asset. Display assets have public URLs, printable assets have private URLs to download the asset.
notes:
object Notes about this asset. Usually used for printable assets to specify how they should print. 

// Example Object
{
  "id": 1,
  "object": "asset",
  "type": "display",
  "name": "AA-WhiteLogo-Front.png",
  "perspective": "front",
  "url": "https://img.printfection.com/18/26/234234lkajsdfdsf7/AA-WhiteLogo-Front.png",
  "notes": ""
}

Orders

The Order Object

id:
integer
object:
string Value is "order"
status:
string Status of the order. {open, received, approved, processed, shipped, completed}
code:
string Unique code that can be used to redeem the order.
url:
string Unique URL that can be used to redeem the order.
gift:
boolean Indicates whether this order is a gift.
gift_message:
string optional The gift message for this order. Can be blank.
created_at:
timestamp Datetime the order was created.
campaign:
campaign object Details about the order's campaign
ship_to:
object Details about the order's shipping address (the valid address is required).
lineitems:
array of lineitem objects
manifest:
object Contains information about the order's final manifest
campaign_id:
integer deprecated (v2.0.3) ID of the campaign the order was placed in. 

// Example Object
{
  "id": 1,
  "object": "order",
  "status": "open",
  "code": "fkzmzzrrn",
  "url": "https://get.printfection.com/customstring/4529475587/fkzmzzrrn",
  "gift": false,
  "gift_message": "",
  "created_at": "2014-09-12T10:22:37Z",
  "external_id": "",
  "campaign": {
    "id": 2,
    "object": "campaign",
    "type": "purchase",
    "name": "The Best Purchase Campaign Ever",
    "active": true,
    "archived": false,
    "url": "https://get.printfection.com/customstring/6651657281",
    "created_at": "2014-09-12T10:22:37Z"
  },
  "ship_to": {
     "name": "Joseph Schmo",
     "address": "123 Main Street",
     "address2": "Suite 101",
     "company": "ACME Inc.",
     "city": "Denver",
     "state": "Colorado",
     "zip": "80202",
     "country": "United States",
     "email": "joseph.schmo@example.com",
     "phone": "751-166-2910"
  },
  "lineitems": [],
  "manifest": {
    "lineitems": [],
    "subtotal": 0,
    "tax": 0,
    "shipping": 0,
    "fulfillment": 0,
    "total": 0,
    "shipments": [
     {
       "carrier": "UPS",
       "method": "UPS Ground",
       "tracking_numbers": [
         "1ZA826E90376588070"
       ],
       "created_at": "2014-09-13T12:21:37Z"
     }
    ],
    "created_at": "2014-09-12T10:22:37Z",
    "received_at": null,
    "approved_at": null,
    "processed_at": null,
    "shipped_at": null,
    "completed_at": null
  }
}

Retrieving an order

Retrieves the details of an order in your account. Supply the unique order ID.

GET /orders/:id

Arguments

id:
integer required

Returns

Returns an order object if a valid identifier was provided, and returns an error otherwise.


// Example Response
{
  "id": 1,
  "object": "order",
  "status": "open",
  "code": "fkzmzzrrn",
  "url": "https://get.printfection.com/customstring/4529475587/fkzmzzrrn",
  "gift": false,
  "gift_message": "",
  "created_at": "2014-09-12T10:22:37Z",
  "external_id": "",
  "campaign": {
    "id": 2,
    "object": "campaign",
    "type": "purchase",
    "name": "The Best Purchase Campaign Ever",
    "active": true,
    "archived": false,
    "url": "https://get.printfection.com/customstring/6651657281",
    "created_at": "2014-09-12T10:22:37Z"
  },
  "ship_to": {
     "name": "Joseph Schmo",
     "address": "123 Main Street",
     "address2": "Suite 101",
     "company": "ACME Inc.",
     "city": "Denver",
     "state": "Colorado",
     "zip": "80202",
     "country": "United States",
     "email": "joseph.schmo@example.com",
     "phone": "751-166-2910"
  }
  "lineitems": []
}

Listing all orders

Lists all orders in your account.

GET /orders GET /orders?campaign_id=1

Arguments

campaign_id:
integer optional Filters the list to only orders placed in the Campaign matching campaign_id.

Returns

Returns an array of order objects, sorted by the date they were created.


// Example Response
[
  {
    "id": 1,
    "object": "order",
    "status": "open",
    "code": "fkzmzzrrn",
    "url": "https://get.printfection.com/customstring/4529475587/fkzmzzrrn",
    "gift": false,
    "gift_message": "",
    "created_at": "2014-09-12T10:22:37Z",
    "external_id": "",
    "campaign": {
      "id": 1,
      "object": "campaign",
      "type": "giveaway",
      "name": "My Awesome Giveaway Campaign",
      "active": true,
      "archived": false,
      "url": "https://get.printfection.com/customstring/6651657281",
      "created_at": "2014-09-12T10:22:37Z"
    },
    "ship_to": {
       "name": "Joseph Schmo",
       "address": "123 Main Street",
       "address2": "Suite 101",
       "company": "ACME Inc.",
       "city": "Denver",
       "state": "Colorado",
       "zip": "80202",
       "country": "United States",
       "email": "joseph.schmo@example.com",
       "phone": "751-166-2910"
    }
    "lineitems": []
  },
  {
    "id": 2,
    "object": "order",
    "status": "open",
    "code": "zx1la90",
    "url": "https://printfection.com/zx1la90",
    "gift": false,
    "gift_message": "",
    "created_at": "2014-09-12T10:22:37Z",
    "external_id": "",
    "campaign": {
      "id": 2,
      "object": "campaign",
      "type": "purchase",
      "name": "The Best Purchase Campaign Ever",
      "active": true,
      "archived": false,
      "url": "https://get.printfection.com/customstring/6651657281",
      "created_at": "2014-09-12T10:22:37Z"
    },
    "ship_to": {
       "name": "Frank Underwood",
       "address": "1600 Pennsylvania Avenue NW",
       "address2": "",
       "company": "ACME Inc.",
       "city": "Washington",
       "state": "DC",
       "zip": "20500",
       "country": "United States",
       "email": "frank.underwood@us.gov",
       "phone": "751-166-2910"
    }
    "lineitems": []
  }
]

Creating a new order

To create a new order, supply the unique ID of the campaign (campaign_id) that the order should be placed in.

For orders to be approved with Printfection they must have ship_to and lineitems information. The user may input this information themselves (Giveaway campaign) or you may submit it in your request (Collection campaign). It is not required that you add ship_to and lineitems in your POST.


POST /orders

{
  "campaign_id": 1,
  "external_id": "0035A00003nJleEQAS",
  "ship_to": {
     "name": "Joseph Schmo",
     "address": "123 Main Street",
     "address2": "Suite 101",
     "company": "ACME Inc.",
     "city": "Denver",
     "state": "Colorado",
     "zip": "80202",
     "country": "United States",
     "email": "joseph.schmo@example.com",
     "phone": "751-166-2910"
  },
  "lineitems": [
    {
      "item_id": 1,
      "size_id": 2,
      "quantity": 3
    }
  ]
}

Arguments

campaign_id:
integer required Unique ID of the campaign this order should be placed in.
ship_to:
object optional Details about the order's shipping address.
lineitems:
array of lineitem objects optional Details about the order's line items.
external_id:
string Any reference to an object in an external system. Limited to 100 characters and must contain only the following characters: a-zA-Z0-9-_.?!@#$%*();:,+

Returns

Returns the new order object if valid information was provided, and returns an error otherwise.


// Example Response
{
  "id": 1,
  "object": "order",
  "status": "open",
  "code": "fkzmzzrrn",
  "url": "https://get.printfection.com/customstring/4529475587/fkzmzzrrn",
  "gift": false,
  "gift_message": "",
  "created_at": "2014-09-12T10:22:37Z",
  "external_id": "",
  "campaign": {
    "id": 2,
    "object": "campaign",
    "type": "purchase",
    "name": "The Best Purchase Campaign Ever",
    "active": true,
    "archived": false,
    "url": "https://get.printfection.com/customstring/6651657281",
    "created_at": "2014-09-12T10:22:37Z"
  },
  "ship_to": {
     "name": "Joseph Schmo",
     "address": "123 Main Street",
     "address2": "Suite 101",
     "company": "ACME Inc.",
     "city": "Denver",
     "state": "Colorado",
     "zip": "80202",
     "country": "United States",
     "email": "joseph.schmo@example.com",
     "phone": "751-166-2910"
  },
  "lineitems": [
    {
      "id": 123,
      "object": "lineitem",
      "order_id": 1,
      "item_id": 1,
      "size_id": 2,
      "quantity": 3,
      "created_at": "2014-09-12T10:22:37Z"
    }
  ]
}

Updating an existing order

To update an existing order, supply the unique ID of the order and the information to be updated.

Note that some information about an order cannot be updated, such as its campaign_id value. Additionally, once an order has been placed, it can no longer be updated.


PATCH /orders/:id

{
  "ship_to": {
     "name": "Sally Schmo",
  }
}

Arguments

id:
integer required Unique ID of the order to be updated.

Returns

Returns the updated order object if valid information was provided, and returns an error otherwise.


// Example Response
{
  "id": 1,
  "object": "order",
  "status": "open",
  "code": "fkzmzzrrn",
  "url": "https://get.printfection.com/customstring/4529475587/fkzmzzrrn",
  "gift": false,
  "gift_message": "",
  "created_at": "2014-09-12T10:22:37Z",
  "external_id": "",
  "campaign": {
    "id": 2,
    "object": "campaign",
    "type": "purchase",
    "name": "The Best Purchase Campaign Ever",
    "active": true,
    "archived": false,
    "url": "https://get.printfection.com/customstring/6651657281",
    "created_at": "2014-09-12T10:22:37Z"
  },
  "ship_to": {
     "name": "Sally Schmo",
     "address": "123 Main Street",
     "address2": "Suite 101",
     "company": "ACME Inc.",
     "city": "Denver",
     "state": "Colorado",
     "zip": "80202",
     "country": "United States",
     "email": "sally.schmo@example.com",
     "phone": "751-166-2910"
  },
  "lineitems": [
    {
      "id": 123,
      "object": "lineitem",
      "order_id": 1,
      "item_id": 1,
      "size_id": 2,
      "quantity": 3,
      "created_at": "2014-09-12T10:22:37Z"
    },
    {
      "id": 124,
      "object": "lineitem",
      "order_id": 1,
      "item_id": 2,
      "size_id": 3,
      "quantity": 5,
      "created_at": "2014-09-12T10:20:33Z"
    }
  ]
}

Cancelling an existing order

To cancel an existing order, supply the unique ID of the order.

Note that once an order has been placed, it can no longer be cancelled.

DELETE /orders/:id

Arguments

id:
integer required Unique ID of the order to be cancelled.

Returns

Returns the cancelled order object if the order was cancelled, and returns an error otherwise.


// Example Response
{
  "id": 1,
  "object": "order",
  "status": "cancelled",
  "code": "fkzmzzrrn",
  "url": "https://get.printfection.com/customstring/4529475587/fkzmzzrrn",
  "gift": false,
  "gift_message": "",
  "created_at": "2014-09-12T10:22:37Z",
  "external_id": "",
  "campaign": {
    "id": 2,
    "object": "campaign",
    "type": "purchase",
    "name": "The Best Purchase Campaign Ever",
    "active": true,
    "archived": false,
    "url": "https://get.printfection.com/customstring/6651657281",
    "created_at": "2014-09-12T10:22:37Z"
  },
  "ship_to": {
     "name": "Sally Schmo",
     "address": "123 Main Street",
     "address2": "Suite 101",
     "company": "ACME Inc.",
     "city": "Denver",
     "state": "Colorado",
     "zip": "80202",
     "country": "United States",
     "email": "sally.schmo@example.com",
     "phone": "751-166-2910"
  },
  "lineitems": [
    {
      "id": 123,
      "object": "lineitem",
      "order_id": 1,
      "item_id": 1,
      "size_id": 2,
      "quantity": 3,
      "created_at": "2014-09-12T10:22:37Z"
    },
    {
      "id": 124,
      "object": "lineitem",
      "order_id": 1,
      "item_id": 2,
      "size_id": 3,
      "quantity": 5,
      "created_at": "2014-09-12T10:20:33Z"
    }
  ]
}

LineItems

The LineItem Object

id:
integer
object:
string Value is "lineitem"
order_id:
integer ID of the order the lineitem belongs to.
item_id:
integer ID of the item in the lineitem.
size_id:
integer ID of the size of the item in the lineitem. Defaults to 0. Should be 0 for items that do not have sizes. Note: size_id is different for each item_id, it does not map to default values like 1=Small 2=Medium.
quantity:
positive integer Quantity of items in the lineitem.
created_at:
timestamp Datetime the lineitem was created. 

// Example Object
{
  "id": 123,
  "object": "lineitem",
  "order_id": 1,
  "item_id": 1,
  "size_id": 2,
  "quantity": 3,
  "created_at": "2014-09-12T10:22:37Z"
}

Retrieving a lineitem

Retrieves the details of a lineitem. Supply the unique lineitem ID.

GET /orders/:order_id/lineitems/:id

Arguments

order_id:
integer ID of the order to the lineitem belongs to.
id:
integer required

Returns

Returns an lineitem object if a valid identifier was provided, and returns an error otherwise.


// Example Response
{
  "id": 123,
  "object": "lineitem",
  "order_id": 1,
  "item_id": 1,
  "size_id": 2,
  "quantity": 3,
  "created_at": "2014-09-12T10:22:37Z"
}

Adding a lineitem to an order

To add a new lineitem to an existing order, supply the unique IDs of the order, item, size, and a quantity.


POST /orders/:order_id/lineitems

{
  "item_id": 3,
  "size_id": 4,
  "quantity": 1
}

Arguments

order_id:
integer ID of the order to add the lineitem to.
item_id:
integer ID of the item in the lineitem.
size_id:
integer ID of the size of the item in the lineitem.
quantity:
positive integer Quantity of items in the lineitem.

Returns

Returns the new lineitem object if valid information was provided, and returns an error otherwise.


// Example Response
{
  "id": 125,
  "object": "lineitem",
  "order_id": 1,
  "item_id": 3,
  "size_id": 4,
  "quantity": 1,
  "created_at": "2014-09-12T10:22:37Z"
}

Updating an existing lineitem

To update an existing lineitem, supply the unique ID of the lineitem.

Note that the order_id of an existing lineitem cannot be changed.


PATCH /order/:order_id/lineitems/:id

{
  "quantity": 2
}

Arguments

order_id:
integer ID of the order to the lineitem belongs to.
id:
integer ID of the lineitem to be updated.

Returns

Returns the updated lineitem object if valid information was provided, and returns an error otherwise.


// Example Response
{
  "id": 125,
  "object": "lineitem",
  "order_id": 1,
  "item_id": 3,
  "size_id": 4,
  "quantity": 2,
  "created_at": "2014-09-12T10:22:37Z"
}

Deleting a lineitem

To delete an existing lineitem, supply the unique ID of the lineitem.

Note that a lineitem cannot be updated once its order has been placed.

DELETE /orders/:order_id/lineitems/:id

Arguments

order_id:
integer ID of the order to the lineitem belongs to.
id:
integer ID of the lineitem to be deleted.

Returns

Returns the deleted lineitem object if it was deleted, and returns an error otherwise.


// Example Response
{
  "id": 125,
  "object": "lineitem",
  "order_id": 1,
  "item_id": 3,
  "size_id": 4,
  "quantity": 2,
  "created_at": "2014-09-12T10:22:37Z"
}

Campaigns

The Campaign Object

id:
integer
object:
string Value is "campaign".
name:
string Name of campaign.
type:
string Type of campaign. {shop, giveaway, purchase, freeforall, import}.
active:
boolean Indicates whether the campaign is active.
archived:
boolean Indicates whether the campaign is archived.
url:
string Web URL for the campaign.
created_at:
timestamp Datetime the lineitem was created.
giveaway_links
string Object containing single-use giveaway link redemption status and web URLs for distribution, if applicable. 

// Example Object
{
  "id": 1,
  "object": "campaign",
  "type": "giveaway",
  "name": "My Awesome Giveaway Campaign",
  "active": true,
  "archived": false,
  "url": "https://get.printfection.com/customstring/6651657281",
  "created_at": "2014-09-12T10:22:37Z",
  "giveaway_links": [
        {
            "status": "Redeemed",
            "link": "https://get.printfection.com/xqbxg/5592122409/rykcffgxkw"
        },
        {
             "status": "Unused",
             "link": "https://get.printfection.com/xqbxg/5592122409/czqfdrqmns"
        }
  
}

Retrieving a campaign

Retrieves the details of a campaign in your account. Supply the unique campaign ID.

GET /campaigns/:id

Arguments

id:
integer required

Returns

Returns a campaign object if a valid identifier was provided, and returns an error otherwise.


// Example Response
{
  "id": 1,
  "object": "campaign",
  "type": "giveaway",
  "name": "My Awesome Giveaway Campaign",
  "active": true,
  "archived": false,
  "url": "https://get.printfection.com/customstring/6651657281",
  "created_at": "2014-09-12T10:22:37Z"
}

Listing all campaigns

Lists all campaigns in your account, sorted by the date they were created.

GET /campaigns

Returns

Returns an array of campaign objects, sorted by the date they were created.


// Example Response
[
  {
    "id": 1,
    "object": "campaign",
    "type": "giveaway",
    "name": "My Awesome Giveaway Campaign",
    "active": true,
    "archived": false,
    "url": "https://get.printfection.com/customstring/6651657281",
    "created_at": "2014-09-12T10:22:37Z"
  },
  {
    "id": 2,
    "object": "campaign",
    "type": "purchase",
    "name": "The Best Purchase Campaign Ever",
    "active": true,
    "archived": false,
    "url": "https://get.printfection.com/customstring/6651657281",
    "created_at": "2014-09-12T10:22:37Z"
  }
]

Errors

The Printfection API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, placing an order failed, etc.), and codes in the 5xx range indicate an error with Printfection's servers.

HTTP Status Code Summary

  • 200 OK - Everything worked as expected.
  • 400 Bad Request - Invalid or missing request parameters.
  • 401 Unauthorized - No valid API key provided.
  • 404 Not Found - The requested item doesn't exist.
  • 50x Server errors - Something went wrong on our end.

The Error Object

object:
string Value is "error".
code:
integer Indicates the type of error.
message:
string A human-readable message giving more details about the error. 

// Example Object
{
  "object": "error",
  "code": 99,
  "message": "Something went wrong."
}