Home / API - New Order

API - New Order

POST /apis/send_order

In the POST request body, either XML or JSON is accepted for Order data

For XML, mime type should be application/xml

For JSON, mime type should be application/json

Order

  1. An Order consists of 4 parts: Order Info, Ship To Info, Order Items, and Order Attachments.
XML
<order>
  <order_info></order_info>
  <ship_to_info></ship_to_info>
  <order_items></order_items>
  <order_attachments></order_attachments>
</order>
JSON
{
  "order": 
  {
    "order_info": {},
    "ship_from_info": {},
    "ship_to_info": {},
    "order_items":
    {
      "order_item": []
    },
    "order_attachments": {}
  }
}

Order Info

  1. Partner order ID - Order number used in your store
  2. Username and Token - Your API credentials
  3. Order Datetime - Order timestamp
XML
<order_info>
  <partner_order_id>123456</partner_order_id>
  <username>partner_name</username>
  <token>1x98003kdjrrkjskey01x0090</token>
  <order_datetime>2018-01-30T21-10-53</order_datetime>
</order_info>
JSON
"order_info": {
  "partner_order_id": "123456",
  "username": "partner_name",
  "token": "1x98003kdjrrkjskey01x0090",
  "order_datetime": "2018-01-30T21-10-53"
}

Ship To Info

  1. Ship From - This is the return address that will be shown on the shipping label. All ship_from_xxx fields are optional
  2. Ship To - Your customer's address where the order will be shipped to
  3. Ship to Method and Code - See Shipping Codes
  4. ship_to_country should follow ISO 3166-1 Alpha-2 code (eg. US for United States of America)
  5. ship_to_country_name should follow ISO 3166-1 English short name
XML
<ship_from_info>
  <ship_from_company>ReturnCompanyName</ship_from_company>
  <ship_from_fname>John</ship_from_fname>
  <ship_from_lname>Doe</ship_from_lname>
  <ship_from_street1>1234 Printverse Ln</ship_from_street1>
  <ship_from_street2></ship_from_street2>
  <ship_from_street3></ship_from_street3>
  <ship_from_city>Fremont</ship_from_city>
  <ship_from_stateprov>CA</ship_from_stateprov>
  <ship_from_country>US</ship_from_country>
  <ship_from_country_name>United States</ship_from_country_name>
  <ship_from_zip>94538</ship_from_zip>
  <ship_from_phone>1234567890</ship_from_phone>
  <ship_from_email>support@yourcompany.com</ship_from_email>
</ship_from_info>
<ship_to_info>
  <ship_to_company></ship_to_company>
  <ship_to_fname>Jane</ship_to_fname>
  <ship_to_lname>Doe</ship_to_lname>
  <ship_to_street1>5678 Printverse Ln</ship_to_street1>
  <ship_to_street2></ship_to_street2>
  <ship_to_street3></ship_to_street3>
  <ship_to_city>Fremont</ship_to_city>
  <ship_to_stateprov>CA</ship_to_stateprov>
  <ship_to_country>US</ship_to_country>
  <ship_to_country_name>United States</ship_to_country_name>
  <ship_to_zip>94538</ship_to_zip>
  <ship_to_phone>1234567890</ship_to_phone>
  <ship_to_email>example@printverse.com</ship_to_email> 
  <ship_to_method>UPS</ship_to_method>
  <ship_to_code>02</ship_to_code>
</ship_to_info>
JSON
"ship_from_info": {
  "ship_from_company": "ReturnCompanyName",
  "ship_from_fname": "John",
  "ship_from_lname": "Doe",
  "ship_from_street1": "1234 Printverse Ln",
  "ship_from_street2": "",
  "ship_from_street3": "",
  "ship_from_city": "Fremont",
  "ship_from_stateprov": "CA",
  "ship_from_country": "US",
  "ship_from_country_name": "United States",
  "ship_from_zip": "94538",
  "ship_from_phone": "1234567890",
  "ship_from_email": "support@yourcompany.com"
},
"ship_to_info": {
  "ship_to_company": "",
  "ship_to_fname": "Jane",
  "ship_to_lname": "Doe",
  "ship_to_street1": "5678 Printverse Ln",
  "ship_to_street2": "",
  "ship_to_street3": "",
  "ship_to_city": "Fremont",
  "ship_to_stateprov": "CA",
  "ship_to_country": "US",
  "ship_to_country_name": "United States",
  "ship_to_zip": "94538",
  "ship_to_phone": "1234567890",
  "ship_to_email": "example@printverse.com",
  "ship_to_method": "UPS",
  "ship_to_code": "02"
}

Order Items

    1. Order Items - Contains a list of order_item
    2. Order Item - Each item differing in product and image must be its own order item. Quantity can be adjusted for order items with the same product and image.
    3. Product Code - Product code must match the Printverse product SKU.  Refer to our Catalog
    4. Image Specifications - Image must match the Printverse product dimensions exactly to prevent any imprinting issues. Refer to our Catalog
    5. Image - The image field can be either stored in a URL or FTP server (FTP credentials should be included). The URL/FTP address must point to a single image, not a preview of the image. Only one of either order_item_image_url or order_item_image_ftp field is required.
Parameter Description
order_item_image_url image url for Printverse server to retrieve
order_item_image_url_ftp image ftp url for Printverse server to retrieve - order_item_image_url_ftp will be used when order_item_image_url is not there.
XML
<order_items>
  <order_item>
    <order_item_product_code>21108−3</order_item_product_code>
    <order_item_partner_product_code>WhiteMug11oz</order_item_partner_product_code>
    <order_item_quantity>2</order_item_quantity>
    <order_item_image_url>http://yourdomain.com/p1.png</order_item_image_url>
    <order_item_image_ftp>ftp://user:password@ftp_server/p1.png</order_item_image_ftp>
  </order_item>
</order_items>
JSON
"order_items":
{
  "order_item":
  [
    {
      "order_item_product_code": "21108-3",
      "order_item_partner_product_code": "WhiteMug11oz",
      "order_item_quantity": "2",
      "order_item_image_url": "http://yourdomain.com/p1.png",
      "order_item_image_ftp": "ftp://user:password@your_ftp_server/p1.png"
    },
    {
      "order_item_product_code": "21504",
      "order_item_partner_product_code": "WhiteMug15oz",
      "order_item_quantity": "1",
      "order_item_image_url": "http://yourdomain.com/p2.png",
      "order_item_image_ftp": "ftp://user:password@your_ftp_server/p2.png"
    }
  ]
}

Order Attachments

    1. Order Packlist - A custom packing list can be included in the shipment. The file can be either stored in a URL or FTP server (FTP credentials should be included). The URL/FTP address must point to a single file, not a preview of the file. Only one of either order_packlist or order_packlist_ftp field is required.
    2. order_packlist can be set to 'no' or 'default'. 'no' indicates no packing list will be packed inside the package. 'default' means a default packing list will be used.
Parameter Description
order_packlist packing list url address for OpenPrint server to retrieve
order_packlist_ftp image ftp url for OpenPrint server to retrieve - order_packlist_ftp will be used when order_packlist is not there.
XML
<order_attachments>
  <order_packlist>http://yourdomain.com/packing1.pdf</order_packlist>
  <order_packlist_ftp>ftp://user:password@ftp_server/packing1.pdf</order_packlist_ftp>
  <inserts>coupon_a, marketing_insert_b</inserts>
</order_attachments>
JSON
"order_attachments": {
  "order_packlist": "http://yourdomain.com/packing1.pdf",
  "order_packlist_ftp": "ftp://user:password@your_ftp_server/packing1.pdf"
}

Constraints

  1. Text fields are no longer than 60 characters except for URLs which are no longer than 1024 characters.

  2. All fields are required, except for ship_from_xxx address fields and the inserts field.

  3. Only either one of url or ftp is required for order_item_image_url and order_item_image_ftp

  4. Only either one of url or ftp is required for order_packinglist and order_packinglist_ftp

  5. Inserts have to be set up and pre-inventoried

  6. A comma separated inserts field indicates what inserts should be packed inside the package. This field is optional.

Full Example

Full XML example

<order>
  <order_info>
    <partner_order_id>123456</partner_order_id>
    <username>partner_name</username>
    <token>1x98003kdjrrkjskey01x0090</token>
    <order_datetime>2018-01-30T21-10-53</order_datetime>
  </order_info>
  <ship_from_info>
    <ship_from_company>ReturnCompanyName</ship_from_company>
    <ship_from_fname>John</ship_from_fname>
    <ship_from_lname>Doe</ship_from_lname>
    <ship_from_street1>1234 Printverse Ln</ship_from_street1>
    <ship_from_street2></ship_from_street2>
    <ship_from_street3></ship_from_street3>
    <ship_from_city>Fremont</ship_from_city>
    <ship_from_stateprov>CA</ship_from_stateprov>
    <ship_from_country>US</ship_from_country>
    <ship_from_country_name>United States</ship_from_country_name>
    <ship_from_zip>94538</ship_from_zip>
    <ship_from_phone>1234567890</ship_from_phone>
    <ship_from_email>support@yourcompany.com</ship_from_email>
  </ship_from_info>
  <ship_to_info>
    <ship_to_company></ship_to_company>
    <ship_to_fname>Jane</ship_to_fname>
    <ship_to_lname>Doe</ship_to_lname>
    <ship_to_street1>5678 Printverse Ln</ship_to_street1>
    <ship_to_street2></ship_to_street2>
    <ship_to_street3></ship_to_street3>
    <ship_to_city>Fremont</ship_to_city>
    <ship_to_stateprov>CA</ship_to_stateprov>
    <ship_to_country>US</ship_to_country>
    <ship_to_country_name>United States</ship_to_country_name>
    <ship_to_zip>94538</ship_to_zip>
    <ship_to_phone>1234567890</ship_to_phone>
    <ship_to_email>example@printverse.com</ship_to_email> 
    <ship_to_method>UPS</ship_to_method>
    <ship_to_code>02</ship_to_code>
  </ship_to_info>
  <order_items>
    <order_item>
      <order_item_product_code>21108-3</order_item_product_code>
      <order_item_partner_product_code>WhiteMug11oz</order_item_partner_product_code>
      <order_item_quantity>2</order_item_quantity>
      <order_item_image_url>http://yourdomain.com/p1.png</order_item_image_url>
      <order_item_image_ftp>ftp://user:password@ftp_server/p1.png</order_item_image_ftp>
    </order_item>
    <order_item>
      <order_item_product_code>21504</order_item_product_code>
      <order_item_partner_product_code>WhiteMug15oz</order_item_partner_product_code>
      <order_item_quantity>1</order_item_quantity>
      <order_item_image_url>http://yourdomain.com/p2.png</order_item_image_url>
      <order_item_image_ftp>ftp://user:password@ftp_server/p2.png</order_item_image_ftp>
    </order_item>
  </order_items>
  <order_attachments>
    <order_packlist>http://yourdomain.com/packing1.pdf</order_packlist>
    <order_packlist_ftp>ftp://user:password@ftp_server/packing1.pdf</order_packlist_ftp>
    <inserts>coupon_a, marketing_insert_b</inserts>
  </order_attachments>
</order>

Return on Success

<result>
  <status>success</status>
  <message>new order has been created!</message>
  <order_id>7654321</order_id>
  <partner_order_id>123456</partner_order_id>
</result>

Return on Failure

<result>
  <status>failure</status>
  <message>invalid username or token</message>
</result>

Full JSON example

{
  "order":
  {
    "order_info":
    {
      "partner_order_id": "123456",
      "username": "partner_name",
      "token": "1x98003kdjrrkjskey01x0090",
      "order_datetime": "2018-01-30T21-10-53"
    },
    "ship_from_info":
    {
      "ship_from_company": "ReturnCompanyName",
      "ship_from_fname": "John",
      "ship_from_lname": "Doe",
      "ship_from_street1": "1234 Printverse Ln",
      "ship_from_street2": "",
      "ship_from_street3": "",
      "ship_from_city": "Fremont",
      "ship_from_stateprov": "CA",
      "ship_from_country": "US",
      "ship_from_country_name": "United States",
      "ship_from_zip": "94538",
      "ship_from_phone": "1234567890",
      "ship_from_email": "support@yourcompany.com"
    },
    "ship_to_info":
    {
      "ship_to_company": "",
      "ship_to_fname": "Jane",
      "ship_to_lname": "Doe",
      "ship_to_street1": "5678 Printverse Ln",
      "ship_to_street2": "",
      "ship_to_street3": "",
      "ship_to_city": "Fremont",
      "ship_to_stateprov": "CA",
      "ship_to_country": "US",
      "ship_to_country_name": "United States",
      "ship_to_zip": "94538",
      "ship_to_phone": "1234567890",
      "ship_to_email": "example@printverse.com",
      "ship_to_method": "UPS",
      "ship_to_code": "02"
    },
    "order_items":
    {
      "order_item":
      [
        {
          "order_item_product_code": "21108-3",
          "order_item_partner_product_code": "WhiteMug11oz",
          "order_item_quantity": "2",
          "order_item_image_url": "http://yourdomain.com/p1.png",
          "order_item_image_ftp": "ftp://user:password@your_ftp_server/p1.png"
        },
        {
          "order_item_product_code": "21504",
          "order_item_partner_product_code": "WhiteMug15oz",
          "order_item_quantity": "1",
          "order_item_image_url": "http://yourdomain.com/p2.png",
          "order_item_image_ftp": "ftp://user:password@your_ftp_server/p2.png"
        }
      ]
    },
    "order_attachments":
    {
      "order_packlist": "http://yourdomain.com/packing1.pdf",
      "order_packlist_ftp": "ftp://user:password@your_ftp_server/packing1.pdf"
    }
  }
}

Return on Success

{
  "result":
  {
    "status": "success",
    "message": "new order has been created!",
    "order_id": "7654321",
    "partner_order_id": "123456"
  }
}

Return on Failure

{
  "result":
  {
    "status": "failure",
    "message": "invalid username or token"
  }
}