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=
OR
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 |
Example Response:
{
"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}
]
}
If any errors were encountered, "errors" will be an array of strings instead:
{
"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. |
Example Request:
{
"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 |
Example Response:
{
"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.
Example Response:
{
"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)
Example Response:
{
"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.
Example Request:
{
"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.
Example Response:
{
"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:
Example Response:
{
"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.
Example Response:
{
"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". |
Example Request:
{
"webhook": "order.status",
"url": "http://www.yoursite.com/hook/"
}
Example Response:
{
"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.
Example Response:
{
"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.
Example Response:
{
"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.
Example Response:
{
"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.
Example Request:
{
"webhook_id": 13
}
OR
{
"webhook": "order.status",
"url": "http://www.yoursite.com/hook/"
}
Example Response:
{
"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