API

Intro


Welcome to the Inklocker API service! This API was designed to make fulfillment of printed clothing and accessories as easy as possible. Whether you are a store or wholesaler, the goal is to outsource your orders with a simple API call.

The Inklocker API follows the common REST pattern, but leans heavily towards the JSON data format for interaction. To make the API as explorable as possible, accounts have test and live mode API keys.

There is no "switch" for changing between modes, just use the appropriate API key to perform a live or test transaction. Requests made to the test sandbox never make any real charges or transactions that may impact your account.

Requests

For every request you make to this API service, you will need to authenticate your account by including your secret key in the headers.

You can manage your API keys in the Dashboard. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Please make sure the following holds true for all requests to the API:
- make sure all requests are made over HTTPS
- set "Authorization" header to "Bearer [SECRET API KEY]" for API authentication
- set "Content-Type" header to "application/json" for all inbound communication

If you would like to store any additional information to reference corresponding objects in your system please refer to the Meta.

Authorization
curl "https://api.inklocker.com/inventory" \
    -H "Authorization: Bearer bd5e86d81be54e1e50ac276636ca3c4e" \
    -H "Content-Type: application/json"
Posting Data
curl "https://api.inklocker.com/foo/bar" \
    -H "Authorization: Bearer bd5e86d81be54e1e50ac276636ca3c4e" \
    -H "Content-Type: application/json" \
    -d '{"foo":"bar"}'

CORE ELEMENTS

Variant

A variant is a product option (size, color etc.) that contains the sku of the stock blank item used and multiple print options associated with it.

OPTIONS
  • productID
    string
    REQUIRED

    The ID of the parent product.

  • sku
    string
    REQUIRED

    A SKU is a string that represent a stock blank item.

  • print
    array
    REQUIRED

    A list of print objects that describes how the artwork is to be printed.

Example
{
    "sku": "bgedg-be004-natpnk-one",
    "print": [
        {
            "url": "https://api.inklocker.com/artwork/mickey.png",
            "location": "front",
            "size": "5cmx5cm",
            "offset": "5x5"
        },
        {
            "url": "https://api.inklocker.com/artwork/mickey.png",
            "location": "back",
            "size": "5cmx5cm",
            "offset": "5inx5in"
        }
    ]
}

Print

A print object is a printed image in a specific location on the shirt. You may use the offset in inches or centimeters in width by height format.

OPTIONS
  • type
    string
    Default dtg

    Print type

  • url
    string
    REQUIRED

    A url pointing to the location of where the artwork resides.

  • location
    string
    REQUIRED

    The placement of the artwork on the product.

  • size
    string
    optional

    The width/height size that the image should be when printed. If size is not provided it will be calculated based on the dpi value.

  • offset
    string
    REQUIRED

    The x/y offset position of where the artwork wil be printed.

  • dpi
    number
    Default 150

    The dot pitch/pixels per inch that the artwork will be printed at.

  • options
    array
    optional

    Print type specific options

Example 1:
{
    "url": "https://api.inklocker.com/artwork/mickey.png",
    "location": "front",
    "size": "5inx5in",
    "offset": "5inx5in",
    "options": ["add-underbase"]
}
Example 2:
{
    "url": "https://api.inklocker.com/artwork/mickey.png",
    "location": "front",
    "offset": "5inx5in",
    "dpi": 200
}
Example 3:
{
    "url": "https://api.inklocker.com/artwork/mickey.png",
    "location": "back",
    "offset": "5cmx5cm"
}

SKU

A SKU is a string that represent a stock blank item. The string is the brand, style, size and color concatenated together to be able to identify a specific item by it.

Example
"hanes-5250-ltblue-2xl"

Credit Card

The credit card to charge.

OPTIONS
  • number
    string
    optional

    The credit card number

  • exp
    string
    optional

    The expiration date

  • cvc
    number
    optional

    The card verification code

Example
{
    "number": "4111111111111111",
    "exp": "12/23",
    "cvc": 123
}

Status


A status is the object representing the order as it progresses through the stages of production to shipment. We post the event object to you if you are subscribed to the webhook.

OPTIONS
  • orderID
    string
    optional

    The ID of the order.

  • status
    string
    optional

    A string representing the status of the order. There are three possible order states: order-received, order-started and order-shipped.

Order Received
{
    orderID: "OVNBBQ44F2GIQPXE9QTIU5CX",
    status: "order-received"
}
Order Started
{
    orderID: "OVNBBQ44F2GIQPXE9QTIU5CX",
    status: "order-started"
}
Order Shipped
{
   orderID: "OVNBBQ44F2GIQPXE9QTIU5CX",
   status: "order-shipped",
   trackingNumber: "9400136897846017037454",
   shippingLabel: "https://api.inklocker.com/img/shipping-label.png",
   carrier: "USPS"
}

Address

OPTIONS
  • street
    string
    REQUIRED

    A strign reprsenting the street of the address.

  • unit
    string
    optional

    A string representing the unit number, apartment, or suite of the address.

  • city
    string
    REQUIRED

    A string representing the city of the address.

  • state
    string
    optional

    A string representing the state of the address. This s only neccessary for domestic US addresses.

  • province
    string
    optional

    A string representing the province/territory of the address. This is only neccessary for International addresses.

  • postalcode
    string
    optional

    A string representing the postal code of the address.

  • country
    string
    optional

    The two letter country code representing the country of the address. If not provided, it will be auto detected.

Domestic
{
    street: '2000 Sunset Blvd',
    unit: '510',
    city: 'Beverly Hills',
    state: 'CA',
    postalcode: '90210',
    country: 'US'
}
International
{
    street: '546 Downing St',
    unit: '',
    city: 'London',
    province: 'England',
    postalcode: 'SW1A 2AB',
    country: 'UK'
}

Meta

Meta is useful for storing additional, structured information on an object. As an example, you could store corresponding unique identifier from your system on an Inklocker Order object.

NOTE: You can specify up to 20 keys, with key names up to 40 characters long and values up to 500 characters long.

OPTIONS
  • customParam
    string
    optional

    Any custom parameter from your system.

Example
{
    ...
    meta: {
        customParam: "12345678"
    }
    ...
}

ACCOUNT

Email

Change your email to receive notifications.

OPTIONS
  • email
    string
    optional

    The email you would like to have associated with your account.

Definition
POST "https://api.inklocker.com/account/email"
Request
curl "https://api.inklocker.com/account/password" \
    -H "Authorization: Bearer bd5e86d81be54e1e50ac276636ca3c4e" \
    -H "Content-Type: application/json" \
    -d '{"email": "john.smith@email.com"}'
Response
{
    "status": "success",
    "data": true
}

Password

Update your password.

OPTIONS
  • current
    string
    optional

    The current password associated with your account.

  • new
    string
    optional

    The new password to set.

Definition
POST "https://api.inklocker.com/account/password"
Request
curl "https://api.inklocker.com/account/password" \
    -H "Authorization: Bearer bd5e86d81be54e1e50ac276636ca3c4e" \
    -H "Content-Type: application/json" \
    -d '{"current": "12345", "new": "54321"}'
Response
{
    "status": "success",
    "data": true
}

Payment

The default payment method will be charged if a payment method is not provided with an order.

OPTIONS
  • creditCard
    object
    optional

    The credit card to charge.

Definition
POST "https://api.inklocker.com/account/payment"
Request
curl "https://api.inklocker.com/account/password" \
    -H "Authorization: Bearer bd5e86d81be54e1e50ac276636ca3c4e" \
    -H "Content-Type: application/json" \
    -d '{"creditCard": { "number": "4111111111111111", exp: "12/23", cvc: 123 } }'
Response
{
    "status": "success",
    "data": true
}

INVENTORY

The inventory is the list of all stock blanks that you can choose from to create a product to print on. Any items listed here will have an up to date pricing and availability information. The SKU provided for each item is the unique ID which you will use to reference it.

OPTIONS
  • page
    number
    optional

    Page number to start at with each page showing 100 results

  • category
    string
    optional

    An available filter, that if provided with a value allows you to filter via category (women, men, kids etc).

  • type
    string
    optional

    An available filter, that if provided with a value allows you to filter via type (sweatshirts, t-shirts, tank-tops etc).

  • brand
    string
    optional

    An available filter, that if provided with a value allows you to filter via brand.

  • style
    string
    optional

    An available filter, that if provided with a value allows you to filter via style.

  • size
    string
    optional

    An available filter, that if provided with a value allows you to filter via size.

  • color
    string
    optional

    An available filter, that if provided with a value allows you to filter via color.

Definition
GET "https://api.inklocker.com/inventory"
Request
curl "https://api.inklocker.com/inventory?brand=bagedge&color=natural" \
    -H "Authorization: Bearer bd5e86d81be54e1e50ac276636ca3c4e" \
    -H "Content-Type: application/json"
Response
{
    "status": "success",
    "total": 3,
    "data": [
        {
            "sku": "bgedg-be004-natroy-one",
            "brand": "bagedge",
            "style": "be004",
            "color": "natural",
            "size": "one-size",
            "weight": 0.59375,
            "price": 4.93,
            "availability": [
                {
                    "location": "Los Angeles, CA",
                    "qty": 328
                }
            ]
        },
        {
            "sku": "bgedg-be004-natfgn-one",
            "brand": "bagedge",
            "style": "be004",
            "color": "natural",
            "size": "one-size",
            "weight": 0.59375,
            "price": 4.93,
            "availability": [
                {
                    "location": "Los Angeles, CA",
                    "qty": 435
                }
            ]
        },
        {
            "sku": "bgedg-be004-natpnk-one",
            "brand": "bagedge",
            "style": "be004",
            "color": "natural",
            "size": "one-size",
            "weight": 0.59375,
            "price": 4.93,
            "availability": [
                {
                    "location": "Los Angeles, CA",
                    "qty": 271
                },
                {
                    "location": "Fort Worth, TX",
                    "qty": 555
                }
            ]
        }
    ]
}

Browse

You can browse the inventory as you would a catalog.
Start off with an initial category list and then use a selected element to go one level deeper until you find your product.

Definition
GET "https://api.inklocker.com/inventory/browse"
Response
{
    "status": "success",
    "data": [
        {
            refID: 'accessories',
            name: 'Accessories'
        }, {
            refID: 'kids',
            name: 'Kids'
        }, {
            refID: 'men',
            name: 'Men'
        }, {
            refID: 'women',
            name: 'Women'
        }
    ]
}
Definition
GET "https://api.inklocker.com/inventory/browse/men"
Response
{
    "status": "success",
    "data": [
        {
            refID: 'long-sleeves',
            name: 'Long sleeves',
            image: 'https://inventory.inklocker.com/img/categories/men-long-sleeves.jpg'
        }, {
            refID: 'sweatshirts',
            name: 'Sweatshirts',
            image: 'https://inventory.inklocker.com/img/categories/men-sweatshirts.jpg'
        }, {
            refID: 't-shirts',
            name: 'T-shirts',
            image: 'https://inventory.inklocker.com/img/categories/men-t-shirts.jpg'
        }, {
            refID: 'tank-tops',
            name: 'Tank tops',
            image: 'https://inventory.inklocker.com/img/categories/men-tank-tops.jpg'
        }
    ]
}
Definition
GET "https://api.inklocker.com/inventory/browse/men/t-shirts"
Response
{
    "status": "success",
    "data": [
        {
            refID: 'alt',
            name: 'Alternative',
            image: 'https://inventory.inklocker.com/img/brands/alternative/logo.jpeg'
        }, {
            refID: 'american',
            name: 'American Apparel',
            image: 'https://inventory.inklocker.com/img/brands/american-apparel/logo.jpeg'
        }, {
            refID: 'anvil',
            name: 'Anvil',
            image: 'https://inventory.inklocker.com/img/brands/anvil/logo.jpeg'
        }, {
            refID: 'augst',
            name: 'Augusta Sportswear',
            image: 'https://inventory.inklocker.com/img/brands/augusta-sportswear/logo.jpeg'
        }, {
            refID: 'bella',
            name: 'Bella + Canvas',
            image: 'https://inventory.inklocker.com/img/brands/bella-canvas/logo.jpeg'
        }, {
            refID: 'code5',
            name: 'Code Five',
            image: 'https://inventory.inklocker.com/img/brands/code-five/logo.jpeg'
        },
        {
            refID: 'hanes',
            name: 'Hanes',
            image: 'https://inventory.inklocker.com/img/brands/hanes/logo.jpeg'
        }
    ]
}
Definition
GET "https://api.inklocker.com/inventory/browse/men/t-shirts/hanes"
Response
{
    "status": "success",
    "data": [
        {
            refID: '518t',
            name: 'Beefy-T Tall T-Shirt',
            image: 'https://inventory.inklocker.com/img/brands/hanes/518T/model.jpeg'
        }, {
            refID: '5250',
            name: 'Tagless T-Shirt',
            image: 'https://inventory.inklocker.com/img/brands/hanes/5250/model.jpeg'
        }
    ]
}
Definition
GET "https://api.inklocker.com/inventory/browse/men/t-shirts/hanes/5250"
Response
{
    "status": "success",
    "data": [
        {
            refID: 'aqtcbl',
            name: 'Aquatic Blue',
            image: 'https://inventory.inklocker.com/img/brands/hanes/5250/aquatic-blue/primary-swatch.jpeg'
        }, {
            refID: 'ash',
            name: 'Ash',
            image: 'https://inventory.inklocker.com/img/brands/hanes/5250/ash/primary-swatch.jpeg'
        }, {
            refID: 'athorg',
            name: 'Athletic Orange',
            image: 'https://inventory.inklocker.com/img/brands/hanes/5250/athletic-orange/primary-swatch.jpeg'
        }, {
            refID: 'black',
            name: 'Black',
            image: 'https://inventory.inklocker.com/img/brands/hanes/5250/black/primary-swatch.jpeg'
        }, {
            refID: 'bluhor',
            name: 'Blue Horizon',
            image: 'https://inventory.inklocker.com/img/brands/hanes/5250/blue-horizon/primary-swatch.jpeg'
        }
    ]
}
Definition
GET "https://api.inklocker.com/inventory/browse/men/t-shirts/hanes/5250/black"
Response
{
    "status": "success",
    "data": [
        {
            refID: 's',
            name: 'S'
        }, {
            refID: 'm',
            name: 'M'
        }, {
            refID: 'l',
            name: 'L'
        }, {
            refID: 'xl',
            name: 'XL'
        }, {
            refID: '2xl',
            name: '2XL'
        }, {
            refID: '3xl',
            name: '3XL'
        }, {
            refID: '4xl',
            name: '4XL'
        }, {
            refID: '5xl',
            name: '5XL'
        }, {
            refID: '6xl',
            name: '6XL'
        }
    ]
}
Definition
GET "https://api.inklocker.com/inventory/browse/men/t-shirts/hanes/5250/black/l"
Response
{
    "status": "success",
    "data": [
        {
            sku: 'hanes-5250-black-l',
            category: 'men',
            type: 't-shirts',
            brand: 'hanes',
            style: '5250',
            color: 'black',
            size: 'l',
            price: 2.5,
            "availability": [
                {
                    "location": "Los Angeles, CA",
                    "qty": 243
                },
                {
                    "location": "Fort Worth, TX",
                    "qty": 505
                },
                {
                    "location": "Olathe, KS",
                    "qty": 39
                },
                {
                    "location": "Robbinsville, NJ",
                    "qty": 570
                },
                {
                    "location": "Bolingbrook, IL",
                    "qty": 927
                }
            ]
        }
    ]
}

STOCK

Product

You can create your own custom products. Each created product will have variants that consist of SKU's, print options and retail prices that you set.

OPTIONS
  • name
    string
    optional

    Product name

  • description
    string
    optional

    Product description to be used to display information about your product

  • variants
    array
    optional

    A list of variant objects that include SKU, artwork/print specs and retail price.

  • tags
    array
    optional

    A list of tags to filter by later on for easy products management

Definition
POST "https://api.inklocker.com/product"
Request
curl "https://api.inklocker.com/product" \
    -H "Authorization: Bearer bd5e86d81be54e1e50ac276636ca3c4e" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Super Tee", "description": "The best shirt...", "variants": [] }'
Response
{
    "status": "success",
    "data": {}
}

Artwork

Endpoint to upload your custom artwork/images that you would like us to host for you. You can reference your artwork when creating product variants and we will use it when printing your orders.

OPTIONS
  • name
    string
    optional

    Product name

  • url
    string
    optional

    A url of where the image is being hosted (or raw image content see below)

  • content
    string
    optional

    A base64 encoded string in data URI format representing the content of the image

  • tags
    array
    optional

    A list of tags to filter by later on for easy artwork management

Definition
POST "https://api.inklocker.com/artwork"
Request
curl "https://api.inklocker.com/product" \
    -H "Authorization: Bearer bd5e86d81be54e1e50ac276636ca3c4e" \
    -H "Content-Type: application/json" \
    -d '{ "name": "Red Car", "tags": [], "content: "data:image/png;base64,R0lGODlhEAAQAMQAAORHHOVSKudfOulr..." }'
Response
{
    "status": "success",
    "data": {
        "id": "b3556a52beb14470e1919be1d93c343a",
        "name": "Super Tee",
        "tags": [
            "logo",
            "gym"
        ],
        "url": "http://localhost/artwork/b3556a52beb14470e1919be1d93c343a.png"
    }
}

SALES

Quote

A quote will return all of the details of the order and will have a price/leadtime that is valid for a brief period of time. When it is time to make an actual order, you'll be simply providing the quoteID to the order endpoint.

Please keep in mind that prices may change between the time you created a quote and when you placed a corresponding order.

OPTIONS
  • to
    object
    REQUIRED

    End customer contact information and address that will include name, phone number, email and address. This information is required to get an accurate quote for the shipping rate.

  • from
    object
    optional

    Contact information that will be printed as return address on the package to the end customer.

  • items
    array
    REQUIRED

    A list of items and their quantities to get the quote for. Each item provided requires a SKU (provided from the catalog) and a qty.

Request
POST "https://api.inklocker.com/quote"
{
    "to": {
        "name": "John Smith",
        "email": "john.smith@email.com",
        "phone": "555-555-5555",
        "street": "2000 Sunset Blvd",
        "unit": "510",
        "city": "Beverly Hills",
        "state": "CA",
        "postalcode": "90210",
        "country": "US"
    },
    "from": {
        "name": "Best T-Shirts Ever",
        "email": "john.smith@email.com",
        "phone": "555-555-5555",
        "street": "2000 Sunset Blvd",
        "unit": "510",
        "city": "Beverly Hills",
        "state": "CA",
        "postalcode": "90210",
        "country": "US"
    },
    "items": [
        {
            "sku": "INDTCO-PRM90HT-BLACK-2XL",
            "print": [
                {
                    "url": "https://api.inklocker.com/artwork/mickey.png",
                    "location": "front",
                    "size": "5cmx5cm",
                    "offset": "5inx5in"
                },
                {
                    "url": "https://api.inklocker.com/artwork/mickey.png",
                    "location": "back",
                    "size": "5cmx5cm",
                    "offset": "5inx5in"
                }
            ],
            "qty": 2
        },
        {
            "sku": "ANVIL-980-WHITE-2XL",
            "print": [
                {
                    "url": "https://api.inklocker.com/artwork/mickey.png",
                    "location": "front",
                    "size": "5cmx5cm",
                    "offset": "5inx5in"
                }
            ],
            "qty": 10
        }
    ]
}
Response

Orders

An order represents a purchase from an existing quote.
You will provide the quote ID you created to place a committed order.

If the prices have in fact changed between the time you created the quote and making the order, an error will come back invalidating the quote.
To prevent any surprises we recommend creating another quote immediately before placing the order to have a successful charge.

If you would like to have control over duplicate order validation please provide a refID for each order submission.
- If the same refID is provided more than once an order is considered a duplicate.
- If refID is not provided then an order is considered unique by default.

OPTIONS
  • quoteID
    string
    optional

    The quote ID of the order you want to place.

  • service
    string
    optional

    This is The quote ID of the order you want to place.

  • to
    object
    optional

    The to address (only if a quote ID is not provided).

  • from
    object
    optional

    The from address (only if a quote ID is not provided).

  • printshop
    string
    optional

    The printshop ID of that you would like to use instead of the reccomended one.

  • items
    array
    optional

    The items array (only if a quote ID is not provided).

  • payment
    object
    optional

    The payment method chosen, credit card

  • refID
    string
    optional

    The order ID from your system to be referenced in Inklocker. If provided, this ID will be used to validate for duplicates. Orders will be considered duplicates if the same refID is specified in more than one order submission.

Request
POST "https://api.inklocker.com/orders"
Response
{
    "status": "success",
    "data": {
        "to": {
            "name": "John Smith",
            "address": "6250 Hollywood Blvd, Los Angeles, CA 90028, USA",
            "street": "6250 Hollywood Blvd",
            "city": "Los Angeles",
            "state": "CA",
            "zipcode": "90028",
            "lat": 34.1009554,
            "lng": -118.3258303
        },
        "from": {
            "name": "Best T-Shirts Ever",
            "address": "155 Main St, San Francisco, CA 94105, USA",
            "street": "155 Main St",
            "city": "San Francisco",
            "state": "CA",
            "zipcode": "94105",
            "lat": 37.7912173,
            "lng": -122.3939352
        },
        "items": [
            {
                "sku": "BGEDG-BE004-NATPNK-ONE",
                "print": [
                    {
                        "url": "https://api.inklocker.com/artwork/mickey.png",
                        "location": "front",
                        "size": "5cmx5cm",
                        "offset": "5x5",
                        "cost": 5.75
                    },
                    {
                        "url": "https://api.inklocker.com/artwork/mickey.png",
                        "location": "back",
                        "size": "5cmx5cm",
                        "offset": "5inx5in",
                        "cost": 3
                    }
                ],
                "qty": 2,
                "cost": 18.61
            },
            {
                "sku": "BGEDG-BE004-NATLTB-ONE",
                "print": [
                    {
                        "url": "https://api.inklocker.com/artwork/mickey.png",
                        "location": "front",
                        "size": "5cmx5cm",
                        "offset": "5inx5in",
                        "cost": 5.75
                    }
                ],
                "qty": 10,
                "cost": 55.05
            }
        ],
        "subtotal": 73.66,
        "shipping": 0,
        "tax": 6.08,
        "total": 79.74,
        "eta": "3 business days"
    }
}

ADVANCED

Web Hooks


Each Webhook contains the url which we will notify whenever an object in our system updates. Several types of objects are processed asynchronously in the system, so whenever an object updates, an Event is sent via HTTP POST to each configured webhook URL. The Webhook object provides CRUD operations for all Webhooks.

Currently, our recommended best practice for securing Webhooks involves using basic authentication and HTTPS on your endpoint. This will help prevent any altering of any information communicated to you by us, prevent any third parties from seeing your webhooks in transit, and will prevent any third parties from masquerading as Inklocker and sending fraudulent data. Inklocker performs certificate validation and requires any TLS-enabled (HTTPS) webhook recipients to have a certificate signed by a public trusted certification authority. We do not support sending webhooks to over SSLv2, SSLv3, or any connection using so-called export-grade ciphers. For documention on how to set up your server with TLS, we recommend Mozilla's guide to Server-Side TLS and Qualys's SSL/TLS deployment best practices guide.

In general, a Webhook's endpoint should return a status code of 2XX. A 200 is preferred, but any 2XX status will indicate to our system that the Webhook request was successful. Endpoints that return a large volume and rate of failures over a period of time will get automatically disabled by the system; a disabled Webhook can be re-enabled using the Webhook update endpoint.

OPTIONS
  • url
    number
    optional

    A url to provide that we will post an status object to when the action occurs.

Definition
POST "https://api.inklocker.com/webhooks"
Request
curl "https://api.inklocker.com/webhooks" \
    -H "Authorization: Bearer bd5e86d81be54e1e50ac276636ca3c4e" \
    -H "Content-Type: application/json" \
    -d '{"url":"https://mysite.com/api/listener"}'
Response
{
    "status": "success",
    "data": "https://mysite.com/api/listener"
}