Back to home

Help Center

Integrations

Printer integrations

Print vendor API

Use the print API to connect to our services and receive orders. Note that this must be authorized first by our service team.

GET /api/printOrders?statuses=[statusList]

Description

Query a list of print orders.

Query string parameters

- statuses: a comma-separated list of order statuses

Valid status values

- SentToVendor
- ReceivedByVendor
- Printing
- Shipping
- OnHold
- Cancelled

Response format

A JSON list of pending print orders. The format for a print order is:

{
    "orderId": number,
    "printJobs": array[PrintJob],
    "rushOrder": boolean,
    "reprint": boolean,
    "contactInfo": ContactInfo,
    "notes": string
}

In special cases where users do not pay for the order through Marq, but are instead billed directly by the print vendor, the following values will also be included in the print order:

"shippingPrice": number,
"totalPriceWithoutTax": number,

The format for ContactInfo is:

{
    "name": string,
    "email": string,
    "billingCodes": string
}

The format for a print job is:

{
    "jobId": string,
    "title": string,
    "projectURL": string,
    "csvURL": string (optional),
    "quantity": number,
    "shippingAddress": ShippingAddress,
    "shippingMethod": string,
    "jobOptions": JobOptions,
    "notes": string,
    "externalProductId": string
}

The jobId will be a string representation of the print job's ID, or of the form [jobId]-addon for add-on jobs. Add-on jobs include envelopes, banner stands, etc.

The shippingMethod will be one of the following:

USPS First Class
USPS Priority
UPS Ground
UPS 2nd Day Air
UPS Next Day Air
Direct mailer
FedEx Ground
FedEx Priority
FedEx Saturday

The format for a shipping address is:

{ 
    "name": string,
    "address1": string,
    "address2": string (optional), 
    "city": string,
    "state": string,
    "country": string,
    "zipcode": string
}

The format for job options is:

{
    "width": number,
    "height": number,
    "units": string,
    "description": string,
    "productType": string,
    "media": string,
    "duplex": boolean (optional),
    "pageCount": number,
    "coating": string (optional),
    "folds": string (optional),
    "finish": string (optional),
    "coverMedia": string (optional),
    "upgrades": Upgrades
}

description is a human-friendly description of the print product

productType represents the general type of print

folds, if present, will be of the format (h|v);(\d+.\d+,)+. The first character denotes whether the folds are horizontal or vertical. The decimal numbers after the semicolon are comma-separated and denote the distance (in inches) from the bottom/left edge of the page

The format for upgrades is:

{   
    "description": string
}

Example response

[
  {
    "orderId": 1,
    "printJobs": [
      {
        "jobId": 1,
        "projectURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 4,
          "height": 6,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      }
    ]
  },
  {
    "orderId": 2,
    "printJobs": [
      {
        "jobId": 1,
        "projectURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 5,
          "height": 7,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      },
      {
        "jobId": 2,
        "projectURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 5,
          "height": 7,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      },
      {
        "jobId": 3,
        "projectURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 4,
          "height": 6,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      }
    ]
  },
  {
    "orderId": 3,
    "printJobs": [
      {
        "jobId": 1,
        "projectURL": "cloudfront.pdf.csv.zip",
        "shippingAddress": "",
        "shippingMethod": "First-Class Mail",
        "jobOptions": {
          "width": 4,
          "height": 6,
          "productType": "Postcard",
          "media": "110# Matte Cover",
          "duplex": true,
          "pageCount": 2,
          "coating": "GlossUV"
        }
      }
    ]
  }
]

Authentication

You no longer need to use a vendor code to connect to the API. Going forward, the endpoint is /api/printOrders?statuses=X,Y,Z where X, Y, and Z are substituted with valid status values. If you would like to access this endpoint from outside the browser via cURL or Postman, you need to copy the lucidauth cookies form the browser and send it with the request. For example:

1. Sign in to Marq.

2. Copy the value of the lucidauth cookie under the app.Marq.com domain.

3. Decode this value using decodeURIComponent(cookieValueHere)

4. Use https://print.app.Marq.com/api/printOrders?statuses=SentToVendor for the URL in Postman.

5. Set the Authorization header in the request in Postman. The value should be the result of step 3.

POST /api/printOrders

Description

Send a list of updates for print jobs and orders

Body parameters

A JSON list of order updates

Order update format:

{  
    "orderId": number,
    "jobId": number,
    "status": string,
    "trackingNumber": string (optional),
    "shippingCarrier": string (optional),
    "shippingMethod": string (optional),
    "dateShipped": string (optional) 
}

Note: currently, only one status update per order is accepted. The jobId can be the ID of any job in the order.

Note: Status updates for "add-on" jobs are not needed and will not be accepted

Valid status values are:

SentToVendor
ReceivedByVendor
Printing
Shipping
OnHold
Cancelled

The optional keys (trackingNumber, shippingCarrier, shippingMethod, and dateShipped) are only required when the status is Shipping

The format for the shipping date is MM/DD/YYYY HH:MM:SS [AM|PM]

A status update on a job will only be accepted if the new status is a valid transition from the current status. Valid transitions are:

SentToVendor -> ReceivedByVendor, Printing, Shipping, OnHold, or Cancelled
ReceivedByVendor -> Printing, Shipping, OnHold, or Cancelled
Printing -> OnHold or Shipping
Shipping -> Shipping (terminal state, but updates to shipping information are allowed)
OnHold -> ReceivedByVendor, Printing, Shipping, or Cancelled
Cancelled -> N/A (terminal state)

Response-format

A multistatus JSON object:

{
    "multistatus": [
        {...},
        {...},
        {...},
        ...
    ]
}

Status object format:

{  
    "id": string,
    "Status": string,
    "Reason": string
}

The id will be of the form [orderId]-[jobId]

The Status will be a string representation of an HTTP status code

200 for a successful status update
400 for invalid data
500 for an internal server error

The Reason will give additional information. Examples of reasons are:

"Success"
"Invalid order id"
"Invalid job id"
"No existing status for [id]"
"Attempted to set status of [id] to invalid status [status]"
"Attempted to make invalid status transition from [currentStatus] to [attemptedStatus]"

Example request body data

[
  {
    "orderId": 1,
    "jobId": 1,
    "status": "Shipping",
    "trackingNumber": "9400000000000000000000",
    "shippingCarrier": "USPS",
    "shippingMethod": "USPS Priority",
    "dateShipped": "04/17/2018 11:00:00 AM"
  },
  {
    "orderId": 2,
    "jobId": 1,
    "status": "Printing"
  },
  {
    "orderId": 2,
    "jobId": 2,
    "status": "SomeInvalidStatus"
  },
  {
    "orderId": 2,
    "jobId": 3,
    "status": "Printing"
  },
  {
    "orderId": 3,
    "jobId": 1,
    "status": "ReceivedByVendor"
  },
  {
    "orderId": 3,
    "jobId": 2,
    "status": "ReceivedByVendor"
  },
  {
    "orderId": 4,
    "jobId": 1,
    "status": "Printing"
  }
]

Example response

{
  "multistatus": [
    {
      "id": "1-1",
      "Status": "200",
      "Reason": "Success"
    },
    {
      "id": "2-1",
      "Status": "200",
      "Reason": "Success"
    },
    {
      "id": "2-2",
      "Status": "400",
      "Reason": "Attempted to set status of 2-2 to invalid status SomeInvalidStatus"
    },
    {
      "id": "2-3",
      "Status": "200",
      "Reason": "Success"
    },
    {
      "id": "3-1",
      "Status": "200",
      "Reason": "Success"
    },
    {
      "id": "3-2",
      "Status": "400",
      "Reason": "Invalid job id"
    },
    {
      "id": "4-1",
      "Status": "500",
      "Reason": "Invalid order id"
    }
  ]
}