Overview

Introduction


Getting Started with Millers/Mpix Fulfillment API

Welcome to the Millers/Mpix API reference. Our API consists of rest based endpoints for submitting and tracking orders as well as accessing product resources.

Typical Responses

  • 200 OK - Successful request.
  • 201 Created - Success + resource created.
  • 400 Bad Request - Missing parameters or request could not be determined.
  • 401 Unauthorized - Authentication failed.
  • 403 Forbidden - Successful Request.
  • 404 Not Found - resource not found.

Use Cases

Log in / Authentication

We use two tokens for access to api resources. Tokens are passed as HTTP Header values. The values required to generate these tokens are assigned for you during on-boarding.
  1. An Application Token X-MpixApi-Token
  2. A User Auth Token X-MpixUser
See sample code for generating these tokens.

Start an Order Session

With auth tokens in place you can start an order session. The response will include a session id, to be passed as part of the order post, and a url for uploading order images.

Upload Images

Currently we expect images to be uploaded prior to submitting an order. Upon successful upload we responsd with an imageid that will be posted in the order json.
  1. POST Images to Session Upload URL.
  2. retrieve ImageId from Response.

Submit Order

  1. POST the order json to /orders
  2. A response containing order details (total, shipping total, status, etc.) is immediately returned in the response to this request.

Order Status: Polling

  1. Make a GET request to /orders.
  2. You can poll the order status for a single order or for all orders updated in the last X number of hours.

Order Status: Callbacks

  1. You provide an endpoint to accept a json payload. The url is set once for your account.
  2. A pre-defined json payload is posted to your endpoint when the order is completed (shipped).
  3. Send return acknowledgement json with success true/false.
  4. 
            

Sessions


Start Session
This will return pertinent data such as sessionid and uploadurl. With the uploadurl you can upload your images. See code example. The sessionid is needed for API calls to Create Order.

Request

HEADERS
X-Entity-Key
String
The string assigned to a partner which represents their business. This is the name of your tabs in the dashboard. It is expected for all API calls.
X-MpixApi-Token
String
This is generated by combining the AppID and AppKey from the dashboard. Instructions to generate. It is expected for all API calls.
X-MpixUser
String
User authentication token. Expected for most API requests. See Login.

Response

HEADERS
Content-Type
JSON
The body of this response is in JSON format.
BODY
sessionid
String
The primary value returned from this request.
creationdate
DateTime
The date in which the session was created.
lastupdate
DateTime
The date of the last action performed on the session.
expirationdate
DateTime
The date in which the session will expire.
entity
String
The string assigned to a partner which represents their business.
uploadurl
String
The location to upload images.
servertime
DateTime
The time on the server at the time of the request.

Order Resources


Get Order Details
Poll for order status and tracking information. Returns an array of order status objects.

Request

HEADERS
X-Entity-Key
String
The string assigned to a partner which represents their business. This is the name of your tabs in the dashboard. It is expected for all API calls.
X-MpixApi-Token
String
This is generated by combining the AppID and AppKey from the dashboard. Instructions to generate. It is expected for all API calls.
X-MpixUser
String
User authentication token. Expected for most API requests. See Login.
URL
orderid
String radio
The ID represents the order in our database. Using this url parameter will narrow the response to one result.
partnerorderid
String radio
The ID represents the order in the partner's database. Using this url parameter will narrow the response to one result.
lastUpdatedHours
Integer radio
This represents the number of hours that have lapsed based on current time. Using this parameter will return data for all orders that have been updated within the time window.

Response

HEADERS
Content-Type
JSON
The body of this response is in JSON format.
BODY
Returns an array of OrderDetail


Create Order
Create an Order.

Request

HEADERS
Content-Type
JSON
The body of this request must be passed as JSON.
X-Entity-Key
String
The string assigned to a partner which represents their business. This is the name of your tabs in the dashboard. It is expected for all API calls.
X-MpixApi-Token
String
This is generated by combining the AppID and AppKey from the dashboard. Instructions to generate. It is expected for all API calls.
X-MpixUser
String
User authentication token. Expected for most API requests. See Login.
BODY
entity
String required
The string assigned to a partner which represents their business.
sessionid
String required
Returned from Start Session
partnerorderid
String optional
The ID that represents the order in the partner's database. The sessionid is used if not provided.
MillersId
String optional
Optional Miller's Account Number associated with the order.
strictoptions
Boolean optional
Enforces all defined options are passed in the request.
shippingtype
Enum optional
  • Order
  • Group
orderoptions
Array of Objects optional
Order Level Options that do not affect price.
orderinfo
OrderInfo required
Container for ship method, order addresses, payment, etc.
orderlineitems
Array of OrderLineItem optional
Order Level Items that affect price.
orderitems
Array of OrderItem required
Container for items ordered.
ordergroups
Array of OrderGroup optional
Container of groups related to school orders.
callback_url
URI optional
URL for order status updates

Response

HEADERS
Content-Type
JSON
The body of this response is in JSON format.
BODY
discount
Decimal
The total of any discounts applied to the order.
entity
String
The string assigned to the partner representing their business.
error
Object
An object describing errors encountered.
isorderalreadyprocessed
Boolean
An integrety check for the order.
orderid
String
The ID representing the order in our database.
sessionid
String
Returns the sessionid related to the create order request.
shipping
Decimal
The amount charged for shipping.
subtotal
Decimal
The total of the order before shipping, tax and discounts.
tax
Decimal
The tax charged for the order.
total
Decimal
The final cost of the order.
trackingnumber
String
A number used by UPS to determine the whereabouts of your shipped order while in transit.
transactionid
String
Related to the E-commerce transaction that occurs when the order is processed.
partnerorderid
String
The ID that represents the order in the partner's database.


Order Preflight
You can submit an order for 'preflight' which will verify the order and any options passed. Along with pricing this will also return available shipping methods. Can be used to pre-check orders, verify options, or check possible shipping methods.

Request

HEADERS
Content-Type
JSON
The body of this request must be passed as JSON.
X-Entity-Key
String
The string assigned to a partner which represents their business. This is the name of your tabs in the dashboard. It is expected for all API calls.
X-MpixApi-Token
String
This is generated by combining the AppID and AppKey from the dashboard. Instructions to generate. It is expected for all API calls.
X-MpixUser
String
User authentication token. Expected for most API requests. See Login.
BODY
See Create Order for an overview of the properties

Response

HEADERS
Content-Type
JSON
The body of this response is in JSON format.
BODY
CheckoutAllowed
Boolean
Informs if the order passes the preflight test.
ShippingMethods
Array of ShippingMethod
A list of shipping methods that are applicable to this order.

Product Resources


Get Product
Get a single product by name. Supply the product id in the url.

Request

HEADERS
Content-Type
JSON
The body of this request must be passed as JSON.
X-Entity-Key
String
The string assigned to a partner which represents their business. This is the name of your tabs in the dashboard. It is expected for all API calls.
X-MpixApi-Token
String
This is generated by combining the AppID and AppKey from the dashboard. Instructions to generate. It is expected for all API calls.
URL
id
String required
The id of the product.

Response

HEADERS
Content-Type
JSON
The body of this response is in JSON format.
BODY
ProductId
Integer
The identifier of the product.
Name
String
The name of the product.
Layout
The layout of the product.
PriceItems
Array of PriceItem
The country of the state.


Get Products
Get all available products.

Request

HEADERS
Content-Type
JSON
The body of this request must be passed as JSON.
X-Entity-Key
String
The string assigned to a partner which represents their business. This is the name of your tabs in the dashboard. It is expected for all API calls.
X-MpixApi-Token
String
This is generated by combining the AppID and AppKey from the dashboard. Instructions to generate. It is expected for all API calls.

Response

HEADERS
Content-Type
JSON
The body of this response is in JSON format.
BODY
Returns an array of Product

Referenced Objects




Address

A container of address information.
References:
OrderInfo

Type
Enum
type of address.
  • Shipping
Name
String
The name of the contact at the address.
Country
Enum
The country of the address.
  • US
  • CA
Address1
String
The street 1 of the address.
Address2
String
The street 2 of the address.
City
String
The city of the address.
StateProvince
Enum
The two-character state/province code of the address.
PostalCode
String
The zip/postal code of the address.
Email
String
The email of the contact at the address.
phone
String
The phone of the contact at the address.
groupid
Integer
taxrate
TaxRate readonly
A container for tax information related to the address.


Image

Holds the definitions of an image.
References:
ImageGroup

Name
String
Name of the Image.
ImageId
Integer
An ID corresponding to a photo.
Rotation
Integer
Image rotation in degrees
  • 0
  • 90
  • 180
  • 270
The default is ‘0’
SmallThumbUrl
String
A URL that points to a small thumbnail for this image.
LargeThumbUrl
String
A URL that points to a large thumbnail for this image.
Width
Integer
The width of this image.
Height
Integer
The height of this image.
Rendered
Boolean
A boolean representing if this image is rendered.


ImageGroup

Defines a page's side (front & back).
References:
Page
ProductPage

Name
String
Name of the ImageGroup.
Images
Array of Image
Array of images assigned to a page side.
Options
Array of ImageGroupOption
Array of options for the image group.


ImageGroupOption

Defines the options for an image group.
References:
ImageGroup

GroupName
String
Name of the image group.
Name
String
Name of the image group option.
Val
String
Value of the image group option.


ImageLayout

This is a layout of the image.
References:
OrderItem

Name
String
Name of the layout. Default value is "default"
Pages
Array of Page
Container for groups of images and options.


OrderDetail

Information concerning the state of an order.
References:
GetOrderDetails

entity
String
The string assigned to a partner which represents their business.
orderid
String
The ID that represents the order in our database.
status
String
The status will be one of the following
  • Received
  • In Production
  • Shipped
  • Cancelled
  • Error
trackingnumber
String
The tracking number will allow you to find the current position of the package in the delivery process. This will be populated once the item ships.
partnerorderid
String
The ID that represents the order in the partner's database.
itemcount
Integer
The number of items included in the order.
ordertotal
Decimal
The overall cost of the order.


OrderGroup

Container of groups related to school orders.
References:
CreateOrder

groupid
Integer
The identifier of this group.
firstname
String
The first name of the recipient/contact.
lastname
String
The last name of the recipient/contact.
studentid
String
The student to contact concerning the product.
teacher
String
The teacher to contact concerning the product.
grade
String
packages
Array
Ids of packages to deliver to this group.
alacarteitems
Array of Objects
Separate items traveling with this order.
email
String
The email of the contact/recipient.


OrderInfo

Container for ship method, order addresses, payment, etc.
References:
CreateOrder

ShipMethod
String
The desired ship method.
ShippingType
Enum
The shipping type for the order
  • Order
OrderAddresses
Array of Address
An Array of address blocks.
PaymentMech
Object
Specifying the payment type via an object. Use a key of PaymentType with the value of net.


OrderItem

An Order Item
References:
CreateOrder

Name
String
Name/product id of the orderitem.
Qty
Integer
The quantity of the orderitem.
Unit
Integer
Typcially used for page count with multi-page products.
PaperType
String
The type of paper to use (e.g., esuraface).
Images
This is the layout of the element (how it's printed). Do not confuse the naming with an array of Image.


OrderLineItem

Order Level Items that affect price.
References:
CreateOrder

Name
String
Name of the lineitem.
Value
Boolean
Activate this lineitem.


Page

Container for groups of images and options.
References:
ImageLayout

Name
String
Name of the page defined in the layout. It is case-sensitive.
ImageGroup
Array of ImageGroup
The array defines both sides of each page.


PriceCategory

Container for a specific charging scenario.
References:
PriceItem

Description
String
Description of the category.
MaxQty
Integer
The maximum quantity of the category.
MinQty
Integer
The minimum quantity of the category.
Price
Decimal
The price of the category.
QtyUnit
Integer
The number of items in a set.


PriceItem

Container for special charging for an item.
References:
GetProduct

Name
String
Name of the price item.
Description
String
Description of the price item.
PriceCategories
Array of PriceCategory
An array of the price scenarios.


ProductLayout

Container for the definition of the product.
References:
GetProduct

Width
Decimal
The width of the product.
Height
Decimal
The height of the product.
ProductPages
Array of ProductPage
A conatiner of page definitions related to the product.


ProductPage

Container for the definition of the product.
References:
ProductLayout

Name
String
The name of the page.
ImageGroups
Array of ImageGroup
An array of Imagegroups.


ShippingMethod

Container for shipping method information.
References:
OrderPreflight

Name
String
Name of the shipping method.
Description
String
Description of the shipping method.
Country
String
Country the shipping method supports.
Price
Decimal
Cost of the shipping method.


TaxRate

A container of tax information for a locale.
References:
Address

county
String
The locale county.
city
String
The locale city.
state
String
The locale state.
rate
Decimal
The tax rate of the locale.
taxable
Boolean
Informs if the locale is taxable.
Click Endpoints for API Request/Response Definitions