NAV

Printforia v2 API Reference

This is the documentation for the Printforia API (V2).

Making HTTP Requests

Authentication

Example request with authentication and content type headers

curl -D- \
  -X GET \
  -H "X-Token: 01234567890abcdef01234567890abcd" \
  -H "Content-Type: application/json" \
  "https://api.printforia.com/v2/orders/01234567-890a-bcde-f0123-4567890abcde"

All requests require authentication with an API token.

Your API token will be provided by your account manager.

This API token must be sent in the X-Token header with every request.

Content Type

The Content-Type header should be set to application/json for all requests.

If a body is required in a request or response it will always be JSON.

Resources

Orders

Example POST request body to /v2/orders

{
    "customer_reference": "order-1000",
    "ship_to_address": {
      "recipient": "John H. Watson",
      "address1": "221 Baker Street",
      "address2": "Unit B",
      "address3": "",
      "city": "Washougal",
      "region": "WA",
      "postal_code": "98671",
      "country_code": "US",
      "email": "john.watson@example.com",
      "phone": "555-555-5555"
    },
    "return_to_address": {
      "recipient": "Returns Department",
      "address1": "4060 South Grant Street",
      "address2": "",
      "address3": "",
      "city": "Washougal",
      "region": "WA",
      "postal_code": "98671",
      "country_code": "US"
    },
    "shipping_method": "standard",
    "ioss_number": "3212345",
    "items": [
      {
        "customer_item_reference": "item-1",
        "sku": "gildan-5000-black-l",
        "quantity": 1,
        "description": "One Life, One World T-Shirt",
        "prints": [
          {
            "image_url": "http://example.com/image.png",
            "mockup_url": "http://example.com/mockup.png",
            "location": "front"
          }
        ]
      }
    ]
}

Example POST response body from /v2/orders

{
  "id": "V1StGXR8_Z5jdHi6B-myT",
  "customer_reference": "order-1000",
  "status": "created",
  "ship_to_address": {
    "recipient": "John H. Watson",
    "address1": "221 Baker Street",
    "address2": "Unit B",
    "address3": "",
    "city": "Washougal",
    "region": "WA",
    "postal_code": "98671",
    "country_code": "US",
    "email": "john.watson@example.com",
    "phone": "555-555-5555"
  },
  "return_to_address": {
    "recipient": "Returns Department",
    "address1": "4060 South Grant Street",
    "address2": "",
    "address3": "",
    "city": "Washougal",
    "region": "WA",
    "postal_code": "98671",
    "country_code": "US",
  },
  "shipping_method": "standard",
  "ioss_number": "3212345",
  "items": [
    {
      "id": "Uakgb_J5m9g-0JDMbcJqLJ",
      "customer_item_reference": "item-1",
      "sku": "gildan-5000-black-l",
      "quantity": 1,
      "description": "One Life, One World - T-Shirt - Large",
      "prints": [
        {
          "image_url": "http://example.com/image.png",
          "mockup_url": "http://example.com/mockup.png",
          "location": "front"
        }
      ]
    }
  ]
}

The orders resource can be used to create orders as well as retreive, update and cancel existing orders.

Order Object Details

Attribute Type Description
id String This is the ID assigned by Printforia to created orders. It is read only.
customer_reference String This is a reference that you assign to your order. It must be unique to your account, preventing duplicate submissions.
status String The possible values are unapproved, approved, in-progress, completed, rejected and canceled.
ship_to_address Object This is the address that will receive the fulfilled order. See ship_to_address object details below.
return_to_addresss Object This is the address designated for returns, if applicable. If a return address has been configured by your account manager this is not required to be sent with every order. See return_to_address object details below.
shipping_method String This is the shipping priority. It can be standard, express, will-call or overnight.
carrier String This is the carrier that was used to ship the order.
tracking_number String This is the tracking number associated with the carrier.
tracking_number_url String This is a URL that can be used to track the order.
ioss_number String A number that you provide if you are shipping an order to the EU and have paid VAT via IOSS.
Optional.
customs_declaration Object See customs_declaration object details below.
items Array An array of item objects on the order. See items object details below.
order_notes Array A read-only array of note objects. See order note object details below.

ship_to_address object details

Attribute Type Description
recipient String The full name of the order recipient.
Required. 50 Character Limit.
address1 String The first line of the address.
Required. 50 Character Limit.
address2 String The second line of the address.
Optional. 50 Character Limit.
address3 String The third line of the address.
Optional. 50 Character Limit.
city String The ship to city name.
Required. 45 Character Limit.
region String The state or region name.
Optional for non-US addresses. 45 Character Limit.
postal_code String The zip or postal code.
Required.
country_code String The two letter ISO 3166-1 alpha-2 country code
Required.
email String Email address of the recipient.
Optional. 45 Character Limit.
phone String Phone number of the recipient.
Optional. 45 Character Limit.

return_to_address object details

Attribute Type Description
recipient String Name of the return address. It could be "Returns Department", for example.
Required. 50 Character Limit.
address1 String The first line of the address.
Required. 50 Character Limit.
address2 String The second line of the address.
Optional. 50 Character Limit.
address3 String The third line of the address.
Optional. 50 Character Limit.
city String The return city name.
Required. 45 Character Limit
region String The state or region name.
Optional for non-US addresses. 45 Character Limit.
postal_code String The zip or postal code.
Required.
country_code String The two letter ISO 3166-1 alpha-2 country code.
Required.

customs_declaration object details

Attribute Type Description
contents_type String Used to choose the customs declaration that is printed on international shipping labels. Valid values are gift, sample or merchandise. If not set then merchandise is used as a default value.

item object details

Attribute Type Description
id String This is the ID assigned by Printforia to created items. It is read only.
customer_item_reference String This is a reference that you provide to the line item on the order. It is required and must be unique to the order.
sku String This is a SKU to print the order on. This is required. Avaliable SKUs will be provided by your account manager. If you need to submit orders using a custom identifier, a mapping table can be created by your account manager.
quantity Number The quantity of this item to print and ship.
description String A description of the item. This is required.
prints Object An array of print instructions. It can contain at least one value, and at most two values for front and back locations. See items[].prints object details below.

items[].prints object details

Attribute Type Description
image_url String A URL of the artwork. This is required.
mockup_url String A URL of a mockup image. This is required.
location String The location on the shirt to print the artwork. Available options are front and back.

order_notes[] note object details

Attribute Type Description
title String The title of a note.
body String The body of a note.
order_status_code String The order status at the time that a note is created.
note_date String A creation timestamp in ISO 8601 format.

Creating an Order

Orders are created with a POST request to the /v2/orders endpoint.

Getting an existing order

Orders can be retreived by id with a GET request to the /v2/orders/:id endpoint.

Orders can also be retreived by customer_reference using the ?customer_reference query parameter. Example GET request: /v2/orders?customer_reference=my_first_order

Updating an order

Example PATCH request to /v2/orders/:id to update an order

In this example we change the size of the first item, and add a new item to the order.

{
    "customer_reference": "1234-ABcd_!@#$",
    "ship_to_address": {
      "recipient": "John H. Watson",
      "address1": "221 Baker Street",
      "address2": "Unit B",
      "address3": "",
      "city": "Washougal",
      "region": "WA",
      "postal_code": "98671",
      "country_code": "US",
      "email": "john.watson@example.com",
      "phone": "555-555-5555"
    },
    "return_to_address": {
      "recipient": "Returns Department",
      "address1": "4060 South Grant Street",
      "address2": "",
      "address3": "",
      "city": "Washougal",
      "region": "WA",
      "postal_code": "98671",
      "country_code": "US",
    },
    "shipping_method": "standard",
  "items": [
    {
      "id": "Uakgb_J5m9g-0JDMbcJqLJ",
      "customer_item_reference": "item-1",
      "sku": "gildan-5000-black-s",
      "quantity": 1,
      "description": "One Life, One World T-Shirt - Small",
      "prints": [
        {
          "image_url": "http://example.com/image.png",
          "mockup_url": "http://example.com/mockup.png",
          "location": "front"
        }
      ]
    },
    {
      "customer_item_reference": "item-2",
      "sku": "gildan-5000-black-l",
      "quantity": 1,
      "description": "A new item added to the exsiting order.",
      "prints": [
        {
          "image_url": "http://example.com/image2.png",
          "mockup_url": "http://example.com/mockup2.png",
          "location": "front"
        }
      ]
    }
  ]
}

Example response code for successful update

204 No Content

An order that is still in created status may be updated with a PATCH request to /v2/orders/:id.

The attribute customer_item_reference is used to determine which items are being updated or added to the order.

All items must be present in the update object unless you intend to remove them from the order. Missing items (as determined by lack of customer_item_reference will be removed from the order.

An HTTP 204 No Content status code will be returned for successful update requests.

Canceling an order

Example order cancelation request payload

{
  "status": "canceled"
}

Example response from successful cancelation request

204 No Content

Orders that are still in created status can be canceled by sending a PATCH request to the /v2/orders/:id endpoint that changes the status attribute to canceled. Other top level order attributes do not have to be sent in a cancelation request.

Inventory

This resource can be used to check inventory availability for all SKUs or for a single SKU.

The stock_availability field will show either available or unavailable.

If stock_availability for a SKU is unavailable and there is a known restock date then a restock_date value will be included in the response.

Requesting Inventory for All SKUs

Inventory status for all SKUs can be retrieved by sending a GET request to the /v2/inventory endpoint.

Example response for all SKUs

[
...
   {
        "sku": "PRINTFORIA.BASIC-TEE-WOMEN.WHITE.3XL",
        "stock_availability": "available"
    },
...
    {
        "sku": "PRINTFORIA.BASIC-HOODIE-UNISEX.LIGHT_BLUE.L",
        "stock_availability": "unavailable",
        "restock_date": "2022-03-24T07:00:00.000Z"
    },
...
]

Requesting Inventory Status for a Single SKU

Inventory status for a single SKU can be retrieved by sending a GET request to /v2/inventory/:sku.

Example response for single SKU

{
    "sku": "PRINTFORIA.BASIC-TEE-UNISEX.LIGHT_BLUE.L",
    "stock_availability": "unavailable",
    "restock_date": "2022-03-24T07:00:00.000Z"
}

Errors

BadRequestError - Status code: 400

Status code: 400

{
  "status": "failed",
  "errors": [
      {
          "ship_to_address": [
              "ship_to_address is required"
          ]
      }
  ]
}

This error is returned when a request body is invalid.

Unprocessable Entity - Status code: 422

Status code: 422

{
    "message": "Order already exists"
}

This error is return when the request is ok, but there is a problem with the data.

Webhooks

An HTTPS endpoint for webhooks can be configured by your account manager.

Webhook events will be sent with a POST request to the configured HTTPS URL.

Security

Computing the X-Signature in Node.js

require("crypto");
var timestamp = Math.floor(new Date() / 1000);
var payload = {'tracking_number': 1234567890};
var apiToken = '3cb3edfc38ceb1ba24ff4eb66d3e7ff9'
hash = crypto.createHmac('sha256', apiToken);
hash.update(timestamp.toString() + "." + JSON.stringify(payload));
var signature = hash.digest("hex");
var header = `X-Signature: t=${timestamp};s=${signature}`
console.log(header);
X-Signature: t=1597813065;s=9daa7d22efb3b13fcc399df4fde881c7e57fea772b05fbe207e301430a002e16

You can validate the integrity of webhook requests by checking the X-Signature header.

The javascript example to the right shows how the signature (the s= value of X-Signature) is computed from a unix timestamp (the t= value of X-Signature) and your API token.

Webhook Events

Example status sent when order is approved

{
  "type": "order_status_change",
  "status": "approved", 
  "order_id": "V1StGXR8_Z5jdHi6B-myT",
  "customer_reference": "order-1000",
}

Order status change events will be sent for created, approved, in-progress, shipped, delivered and canceled status.

For convenience the carrier, tracking_number and tracking_url will be sent when an order is moved to shipped status.

Example status sent when order is shipped.

{
  "type": "order_status_change",
  "status": "shipped",
  "order_id": "V1StGXR8_Z5jdHi6B-myT",
  "customer_reference": "order-1000",
  "carrier": "USPS",
  "tracking_number": "12345678901234567890",
  "tracking_url": "https://tracking.example.com/12345678901234567890"
}

Image Specifications

View our Partner Onboarding Documentation for Image Specifications at this link: https://info.printforia.com/partner-onboarding-size-and-position