0 Cart
Added to Cart
    You have items in your cart
    You have 1 item in your cart
    Total
    Check Out Continue Shopping

    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)

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

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

    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