Print & fulfillment API

Introduction

This API is a REST service for the purpose of viewing our catalog items and making orders for us to produce and ship to your customer.

All API requests and responses are JSON and use HTTP GET, POST, PUT, and DELETE.

To start using the API, you will need to either contact us for an API key, or register an account (https://www.cmarvel.com/register/) to receive an API key.

Once your account has been verified, you can log in at https://www.cmarvel.com/user/login/ to see your API keys.

Authentication

Authentication with the API key is required for all requests, and is done through HTTP basic auth.

To authenticate, you need to add the Authorization header and Base64-encode the API key, without the square brackets:

Authorization: Basic [base64-encode(YOUR_KEY)]

Please note that the API does not distinguish between username or password, so the API key can either be the username or password (leaving the other blank). For example, if the tool used to access the API requires the format username:password, then either [base64-encode(:YOUR_KEY)] or [base64-encode(YOUR_KEY:)] will work. If your API key is api1234, then the HTTP request header can either be:

Authorization: Basic YXBpMTIzNDo=

Authorization: Basic OmFwaTEyMzQ=

The content-type header is also highly recommended:

Content-Type: application/json

Api Endpoints

All live API requests should be sent to: https://www.cmarvel.com/api/

Test API requests can be sent to: https://www.cmarvel.com/sandbox/

Products Catalog API

The Products Catalog API provides a list of our products available for printing, recommended minimum image sizes, and pricing.

Request GET https://www.cmarvel.com/api/products/

Parameters None

Return On success, returns a "result" array of objects.

RESULT ARRAY OBJECTS

Attribute	Type	Description
`item_id`	integer	Identifier for the product, used for ordering
`item_name`	string	Name of product
`price`	string	Price (in US dollars) of product per unit
`width`	integer	Minimum recommended width of artwork in pixels
`height`	integer	Minimum recommended height of artwork in pixels

      
      
{
  "result": [
    {
       "item_id":1,
       "item_name":"iPhone 5",
       "price": "10.00",
       "width": 1057,
       "height": 1822
    },
    {
       "item_id": 2,
       "item_name": "iPhone 6",
       "price": "10.75",
       "width": 1016,
       "height": 1847
    },
    {...etc}
  ]
}


{
   "errors": [
	   "API key does not match."
   ]
}

Orders API

The Orders API allows you to make an order, view one or more orders, update an order, or delete an order.

Purpose Making an order.

Request POST https://www.cmarvel.com/api/order/

Parameters

Attribute	Type	Description
`recipient`	object (optional)	The "recipient" object contains shipping address. If left blank, this will default to the address of the account holder.
`name`	string	Full name of the recipient.
`phone`	string (optional)
`email`	string (optional)
`company`	string (optional)
`address1`	string
`address2`	string (optional)
`city`	string (optional)
`state`	string (optional)	State or province. Optional for some countries, but required for US addresses. US states need to be in 2 letter format.
`country`	string	2 or 3 letter country code.
`zip`	string	Zip or postal/province code.
`return_address`	object(optional)	The "return_address" object lets the carrier know where to return an item if there is an address problem. If left blank, this will default to the address of the account holder.
`name`	string	Full name of the recipient.
`company`	string (optional)
`address1`	string
`address2`	string (optional)
`city`	string
`state`	string (optional)	State or province. Optional for some countries, but required for US addresses. US states need to be in 2 letter format.
`country`	string	2 or 3 letter country code.
`zip`	string	Zip or postal/province code.
`shipdate`	string (optional)	Specify when you would like the order to be shipped out. It can be formatted with Hour:Min AM/PM or with military time without AM/PM. Timezonecan be in an abbreviated format or region format. If no timezone is specified, UTC timezone will be used. For example, any of the following would work: 10/09/2015, 4/3/2015 4:35PM, 2015/10/09 PST 4:35 PM, 2015/10/09 17:45 Europe/Kiev.
`shiplabel`	string (optional)	Used to provide your own shipping label for the order. Its value should be a URL to a file (any format is acceptable, such as PNG, JPG, PDF, ZPL, a batch of files inside a ZIP, and etc).
`cust_order_num`	string (optional)	Order number for your own internal record-keeping (for example, this can correspond to the order number in your customer-facing storefront).
`items`	array	Array of items you wish to order.
`item_id`	integer	Specifies the item_id from the catalog.
`qty`	integer	The number of units for this item to be produced.
`name`	string (optional)	An optional name for this particular production job for your record-keeping.
`finish`	string enum	For phone cases, it can be "gloss" or "matte". Mousepads can only be "matte". For all other items, it must be "gloss".
`bg_color`	string (optional)	If your artwork is a PNG with transparencies, a hexadecimal "bg_color" (#7f0318 for example) may be given to print on a particular background color, except on black mugs, which will always have a black background. For white mugs, the handle remains white, as the background color cannot be printed on the handle.
`image`	string	A URL to an image file (JPG or PNG).
`image_back`	string (optional)	For mug items, an "image_back" URL of an image file (JPG or PNG) can be provided if the item has a different art on each side of the mug. If "image_back" is present, then "mockup_back" is highly recommended.
`mockup`	string (optional)	A "mockup" URL of an image (JPG or PNG) can be added to show us exactly how you want the item produced, especially if the item needs to have the image centered in a specific way.
`mockup_back`	string (optional)	A URL of an image (JPG or PNG) to show the other side of a mug.
`notes`	string (optional)	Notes or instructions regarding this particular item.
`notes`	string (optional)	Notes or instructions regarding the overall order.

      
{
   "recipient": {
     "name": "Joe Johnson",
     "address1": "172 W Providencia Ave #105",
     "city": "Burbank",
     "state": "CA",
     "country": "US",
     "zip": "91502"
   },
   "return_address": {
     "name": "Mary Sue",
     "company": "Marys Outfitters",
     "address1": "123 Main St.",
     "address2": "Apt #5",
     "city": "Burbank",
     "state": "CA",
     "country": "US",
     "zip": "91502"
  },
  "cust_order_num": "1234ABCD",
  "shiplabel": "http://yoursite.com/shiplabel.pdf",
  "shipdate": "2015/10/09 4:35 PM PST",
  "items": [
    {
      "item_id": 2,
      "qty": 25,
      "finish": "matte",
      "image": "http://yoursite.com/img.jpg"
    }, 
    {
      "item_id": 3,
      "qty": 125,
      "name": "Breast Cancer Awareness Campaign",
      "finish": "gloss",
      "bg_color": "#fff000",
      "image": "http://yoursite.com/img2.png",
      "image_back": "http://yoursite.com/img2-back.png",
      "mockup": "http://yoursite.com/mockupimg2.jpg",
      "mockup_back": "http://yoursite.com/mockupimg2-back.jpg",
      "notes": "Make sure you get this order correct!"
    },
    {
      "item_id": 3,
      "qty": 225,
      "finish": "matte",
      "image": "http://yoursite.com/img2.jpg"
    }
  ],
  "notes": "Item #3 is super important! Get it right!"
}

Return

On success, returns the "result" object containing order information and an "error" attibute with the value null.

Result Object:

Attribute	Type	Description
`order`	object	Contains main order information, see below.
`shiplabel`	string	Same as the "shiplabel" parameter in the request.
`shipdate`	string	Same as the "shipdate" parameter in the request.
`recipient`	object	Same as the "recipient" parameter in the request.
`return_address`	object	Same as the "return_address" parameter in the request.
`items`	array	Same as the "items" parameter in the request, but with a few extra attributes. See below.
`notes`	string	Same as the "notes" parameter in the request.

Order Object:

Attribute	Type	Description
`created`	string	Date and time the order was initially accepted.
`updated`	string	Date and time the order was last updated.
`status`	string enum	"Processing", "In Production", "Ready To Ship", "Shipped", or "Cancelled".
`order_num`	string	The order number generated by the API. This is the reference that will be used to identify and troubleshoot specific orders.
`cust_order_num`	string	Same as "cust_order_num" parameter in the request.
`carrier`	string	If and when tracking is available for this order, this attribute will show who the carrier is (USPS, UPS, etc). For a full reference of carrier values, please see the ###CARRIERS section towards the end of the documentation.
`tracking`	string	If and when tracking is available, this is the tracking number for this order. If a shipping label is provided by you via "shiplabel" and the order is successfully shipped using that label, then "carrier" and "tracking" will be an empty string "", as there is no way for us to programatically add the tracking information to our database.
`subtotal`	string	The cost of this order (excluding shipping and tax) in US dollars.
`tax`	string	The sales tax for this order in US dollars.
`shipping`	string	The shipping cost for this order in US dollars (zero if the item successfully ships using your provided "shiplabel"). Starts out as "To be calculated" in the inception of the order.
`total`	string	The grand total for the order in US dollars.

Items Object:

Attribute	Type	Description
`print_job_id`	integer	An order can contain multiple, different items. This is used to reference a specific item in the order.
`item_id`	integer
`item_name`	string	The name of the specific product in our catalog.
`name`	string
`qty`	integer
`price`	string
`finish`	string enum
`bg_color`	string
`image`	string
`image_back`	string
`mockup`	string
`mockup_back`	string
`status`	string enum	"Processing", "In Production", or "Complete".
`notes`	string

      
{
  "result": {
    "order": {
      "created": "12-19-2014, 02:59 PST",
      "updated": "12-19-2014, 02:59 PST",
      "status": "Processing",
      "order_num": "S6F0ZBTH6KI",
      "cust_order_num": "1234ABCD",
      "carrier": "",
      "tracking": "",
      "subtotal": "4500.00",
      "tax": "0.05",
      "shipping": "To be calculated",
      "total": "To be calculated"
    },
    "shiplabel": "http:\/\/yoursite.com\/shiplabel.pdf",
    "shipdate": "10/10/2015, 00:35:00",
    "recipient": {
      "name": "Joe Johnson",
      "phone": "",
      "email": "",
      "company": "",
      "address1": "172 W Providencia Ave #105",
      "address2": "",
      "city": "Burbank",
      "state": "CA",
      "country": "US",
      "zip": "91502"
    },
    "return_address": {
      "name": "Mary Sue",
      "company": "Marys Outfitters",
      "address1": "123 Main St.",
      "address2": "Apt #5",
      "city": "Burbank",
      "state": "CA",
      "country": "US",
      "zip": "91502"
    },
    "items": [
      {
        "print_job": 85,
        "item_id": 2,
        "item_name": "iPhone6",
        "name": "",
        "qty": 25,
        "price": "12",
        "finish": "matte",
        "image": "http:\/\/yoursite.com\/img.jpg",
        "file_id": 0,
        "status": "Processing",
        "notes": ""
      },
      { 
        "print_job": 86,
        "item_id": 3,
        "item_name": "iPhone6 Plus",
        "name": "Breast Cancer Awareness Campaign",
        "qty": 125,
        "price": "12",
        "finish": "gloss",
        "image": "http:\/\/yoursite.com\/img2.jpg",
        "mockup": "http:\/\/yoursite.com\/mockupimg2.jpg",
        "file_id": 0,
        "status": "Processing",
        "notes": "Make sure you get this order correct!"
      },
      {
        "print_job": 87,
        "item_id": 3,
        "item_name": "iPhone6 Plus",
        "name": "",
        "qty": 225,
        "price": "12",
        "finish": "matte",
        "image": "http:\/\/yoursite.com\/img2.jpg",
        "file_id": 0,
        "status": "Processing",
        "notes": ""
      }
    ],
    "notes": "Item #3 is super important! Get it right!"
  },
  "errors": null
}

Retrieving one Order

Purpose Retrieving information on one specific order.

Request GET https://www.cmarvel.com/api/order/ORDER_NUM_HERE

Parameters None

Return On success, returns a "result" array of a single object and an "error" attribute with the value null. The single object is exactly the same as the object returned from a successful order.

      
      
{
  "result": [
    {
      "order": {
        "created": "12-19-2014, 02:59 PST",
        "updated": "12-19-2014, 02:59 PST",
        "status": "Processing",
        "order_num": "S6F0ZBTH6KI",
        "cust_order_num": "1234ABCD",
        "carrier": "",
        "tracking": "",
        "subtotal": "4500.00",
        "tax": "0.05",
        "shipping": "To be calculated",
        "total": "To be calculated"
      },
      "shiplabel": "http:\/\/yoursite.com\/shiplabel.pdf",
      "shipdate": "10/10/2015, 00:35:00",
      "recipient": {
        "name": "Joe Johnson",
        "phone": "",
        "email": "",
        "company": "",
        "address1": "172 W Providencia Ave #105",
        "address2": "",
        "city": "Burbank",
        "state": "CA",
        "country": "US",
        "zip": "91502"
      },
      "return_address": {
        "name": "Mary Sue",
        "company": "Marys Outfitters",
        "address1": "123 Main St.",
        "address2": "Apt #5",
        "city": "Burbank",
        "state": "CA",
        "country": "US",
        "zip": "91502"
      },
      "items": [
        {
          "print_job": 85,
          "item_id": 2,
          "item_name": "iPhone6",
          "name": "",
          "qty": 25,
          "price": "12",
          "finish": "matte",
          "image": "http:\/\/yoursite.com\/img.jpg",
          "file_id": 0,
          "status": "Processing",
          "notes": ""
        },
        {
          "print_job": 86,
          "item_id": 3,
          "item_name": "iPhone6 Plus",
          "name": "Breast Cancer Awareness Campaign",
          "qty": 125,
          "price": "12",
          "finish": "gloss",
          "image": "http:\/\/yoursite.com\/img2.jpg",
          "mockup": "http:\/\/yoursite.com\/mockupimg2.jpg",
          "file_id": 0,
          "status": "Processing",
          "notes": "Make sure you get this order correct!"
        },
        {
          "print_job": 87,
          "item_id": 3,
          "item_name": "iPhone6 Plus",
          "name": "",
          "qty": 225,
          "price": "12",
          "finish": "matte",
          "image": "http:\/\/yoursite.com\/img2.jpg",
          "file_id": 0,
          "status": "Processing",
          "notes": ""
        }
      ],
      "notes": "Item #3 is super important! Get it right!"
    }
  ],
  "errors": null
}

Retrieving latest 100 Orders

Purpose Retrieving the latest 100 orders.

Request GET https://www.cmarvel.com/api/order/

Parameters None

Return On success, returns a "result" array of the lastest 100 order objects, and an "error" attribute with the value null. The objects are exactly the same as the object returned from a successful order.

If you wish to see more than just the latest 100 orders, the API can paginate orders 100 at a time by descending date created with the following:

GET https://www.cmarvel.com/api/order/[PAGE]

where [PAGE] is a whole number. For example:

GET https://www.cmarvel.com/api/order/1 (orders 1-100)

GET https://www.cmarvel.com/api/order/2 (orders 101-200)

GET https://www.cmarvel.com/api/order/3 (orders 201-300)

      
      
{
  "result": [
    {
      "order": {
        order info here
      },
      "shiplabel": ship label,
      "shipdate": ship date,
      "recipient": {
        recipient info here
      },
      "items": [
        {
          item 1
        },
        {
          item 2
        },
      ],
      "notes": notes info
    },
    {
      "order": {
        order info here
      },
      "recipient": {
        recipient info here
      },
      "return_address": {
        return_address info here
      },
      "items": [
        {
          item 1
        },
        {
          item 2
        },
      ],
      "notes": notes info
    },
    {...etc}
  ],
  "errors": null
}

Updating a specific order

Purpose Updating a specific order.

Request PUT https://www.cmarvel.com/api/order/ORDER_NUM_HERE

Parameters

Attribute	Type	Description
`name`	string (optional)
`phone`	string (optional)
`email`	string (optional)
`company`	string (optional)
`address1`	string (optional)
`address2`	string (optional)
`city`	string (optional)
`state`	string (optional)
`country`	string (optional)
`zip`	string (optional)

return_address: object(optional)

Attribute	Type	Description
`name`	string (optional)
`company`	string (optional)
`address1`	string (optional)
`address2`	string (optional)
`city`	string (optional)
`state`	string (optional)
`country`	string (optional)
`zip`	string (optional)
`shipdate`	string (optional)
`shiplabel`	string (optional)
`cust_order_num`	string (optional)

items: array (optional)

Attribute	Type	Description
`print_job`	integer
`item_id`	integer
`qty`	integer (optional)
`name`	string (optional)
`finish`	string enum (optional)
`bg_color`	string (optional)
`image`	string (optional)
`image_back`	string (optional)
`mockup`	string (optional)
`mockup_back`	string (optional)
`notes`	string (optional)
`notes`	string (optional)

Please note that only orders with the "Processing" status may be updated through the API. Once an order is confirmed through our system and production begins, then the order is final. Please contact us if you wish to update an order that has passed the "Processing" status.

Return On success, returns the "result" object containing order information and an "error" attribute with the value null, exactly like the return from making a successful order.

      
{
  "recipient": {
    "name": "Miles Prower",
    "phone": "1-800-34-TAILS",
    "email": "tails@greenhillzone.com",
    "company": "Prower Enterprises",
    "address1": "493 Emerald Hill Zone",
    "address2": "Ste. Green Hill Zone",
    "city": "Sega",
    "state": "Kyoto",
    "country": "JP",
    "zip": "91502"
  },
  "items": [
    {
      "print_job": 85,
      "item_id": 2,
      "qty": 0
    },
    {
      "print_job": 86,
      "item_id": 3,
      "name": "Lots o Gloss",
      "finish": "gloss",
      "file_id": 0,
      "notes": "Action figures"
    },
    {
      "print_job":87,
      "item_id": 3,
      "qty": 250,
      "name": "",
      "finish": "matte",
      "image": "http://yoursite.com/img2.jpg",
      "notes": "\"ACTION\" FIGURE'S"
    }
  ],
  "notes": "I JUST UPDATED!"
}

Canceling a specific order

Purpose Canceling a specific order.

Request DELETE https://www.cmarvel.com/api/order/ORDER_NUM_HERE

Parameters None

Return On success, returns a "result" of 1 with "notes" explaining which order was deleted. On failure, it will return an "errors" array of strings explaining why the request failed.

Please note that this method cannot be used to cancel an order with status "In Production" or "Shipped". Please contact us if you wish to cancel an order with those statuses.

      
{
  "result": 1,
  "notes": "Order CFRYIAMNSSK has been deleted."
}

Errors

If there are any errors from any of the requests, then there will be no "result" attribute. The only attribute will be "errors", which is an array of strings describing the points of failure. For example, a response that contains errors may look like:

		
{
  "errors": [
    "Item ID 45 does not exist. \"This is just a test run\" not queued to production.",
    "Item ID 6 needs to have a image.",
    "No items in the order were in the correct format."
  ]
}

Webhooks API

Webhooks can be set up to send a HTTP POST request to specified URLs. Currently, only one webhook is available: "order.status". The "order.status" webhook will trigger any time your order status is updated.

Get a list

Purpose Get a list of currently available webhooks.

Request GET https://www.cmarvel.com/api/webhooks/

Parameters None

Return On success, returns a "result" array of objects, containing a "webhook" string and "description" string, and an "errors" attribute with the value null.

		
{
  "result": [
    {
      "webhook": "order.status",
      "description": "Any time an order status is updated, the new status will be sent via HTTP POST in JSON format to the specified URL."
    }
  ],
  "errors": null
}

Setting

Purpose Setting up a webhook, use a POST request, specifying what webhook you want to set and what URL to POST to (notice the singular "webhook" in the request URL rather than "webhooks"). Webhooks are not distinguished between the production URL and sandbox URL - setting one up on either will retain it for production use.

Request POST https://www.cmarvel.com/api/webhook/

Parameters

Attribute	Type	Description
`webhook`	string enum	Which webhook to set up. Currently, there's only "order.status" available.
`url`	string	The target URL that our servers will POST back to when the webhook is triggered.

Return On success, will return a "result" object and "errors" with the value null.

Result Object:

Attribute	Type	Description
`webhook`	integer	The unique identifier for the webhook that was just set up.
`webhook`	string enum	Same as the request parameter "webhook".
`url`	string	Same as the request parameter "url".

		
{
  "webhook": "order.status",
  "url": "http://www.yoursite.com/hook/"
}

		
{
  "result": {
    "webhook_id": 13,
    "webhook": "order.status",
    "url": "http://www.yoursite.com/hook/"
  },
  "errors": null
}

Viewing currently active webhooks

Purpose Viewing currently active webhooks.

Request GET https://www.cmarvel.com/api/webhook/

Parameters None

Return On success, will return a "result" array containing each webhook that was set up, and "errors" with the value null. Each object in the "result" array is the same as the "result" object returned after setting up a webhook.

		
{
  "result": [
    {
      "webhook_id": 12,
      "webhook": "order.status",
      "url": "http://www.yoursite.com/some_url/"
    },
    {
      "webhook_id": 13,
      "webhook": "order.status",
      "url": "http://www.yoursite.com/hook/"
    }
  ],
  "errors": null
}

Viewing a single webhook that has already been set

Purpose Viewing a single webhook that has already been set.

Request GET https://www.cmarvel.com/api/webhook/WEBHOOK_ID_HERE

Parameters None

Return On success, will return a "result" object containing "webhook_id", "webhook", and "url", and "errors" with value null.

		
{
  "result": {
    "webhook_id": 13,
    "webhook": "order.status",
    "url": "http://www.yoursite.com/hook/"
  },
  "errors": null
}

Deleting a specific webhook

Purpose Deleting a specific webhook

Request DELETE https://www.cmarvel.com/api/webhook/WEBHOOK_ID_HERE

Parameters None

Return On success, will return a "result" object containing "webhook_id", "webhook", and "url", and "errors" with value null.

		
{
  "result": 1,
  "errors": null
}

Testing a webhook

Purpose Testing a webhook. Use a POST request with either a "webhook_id" to trigger a certain webhook that is already set up, OR use "webhook" and "url" to test a particular target URL:

Request POST https://www.cmarvel.com/api/webhook/test

Parameters

Attribute	Type	Description
`webhook_id`	integer
OR
`webhook`	string enum
`url`	string

Return On success, will return a "result" object and "errors" with value null.

If no "webhook_id" was provided, the return value for it would be 0. Additionally, the following "result" object will POST to the target URL of the specific "webhook_id", or the "url" parameter, to mimic how order statuses are updated.

Attribute	Type	Description
`webhook_id`	integer	Same as the "webhook_id" attribute in the Webhooks API.
`webhook`	string enum	Same as the "webhook" attribute in the Webhooks API.
`order_num`	string	Same as "order_num" attribute in the "order" object in the Orders API.
`cust_order_num`	string	Same as "cust_order_num" attribute in the "order" object in the Orders API.
`carrier`	string enum	Same as "carrier" attribute in the "order" object in the Orders API.
`tracking`	string	Same as "tracking" attribute in the "order" object in the Orders API.
`status`	string enum	Same as "status" attribute in the "order" object in the Orders API.

If there were errors communicating with the target URL, then the "errors" attribute will show what HTTP error code shows up:


{
  "errors": [
    "HTTP code 404 error."
  ]
}

A total of three attempts will be tried (with 15min to an hour between each attempt) if there is an error.

Note that the webhook POST response to the target URL does not include your API key. For security purposes, the information sent to the target URL is minimal. Should you require more information on the order or item whose status has been updated, you should send a GET request to retrieve the full details of the order and/or item.

		
{
  "webhook_id": 13
}

OR

{
  "webhook": "order.status",
  "url": "http://www.yoursite.com/hook/"
}

		
{
  "result": {
    "webhook_id": 13,
    "webhook": "order.status",
    "url": "http://www.yoursite.com/hook/",
    "httpcode": 200
  },
  "errors": null
}

Carrier Return Values

These are currently the string enum values for the "carrier" attribute:

DHLGlobalMail
FedEx
UPS
USPS

Promotional popup

Introduction

Authentication

Api Endpoints

Products Catalog API

Orders API

Return

Retrieving one Order

Retrieving latest 100 Orders

Updating a specific order

Canceling a specific order

Errors

Webhooks API

Get a list

Setting

Viewing currently active webhooks

Viewing a single webhook that has already been set

Deleting a specific webhook

Testing a webhook

Carrier Return Values