POST/v1/orders/create

Create Order

Having the ability to create orders is a key peice of the MPODx offering. On this page, we'll explore the Create Order endpoint and how it can be used to create orders in our system for both Print on Demand and Fulfillment orders.

Making a Request

Include the headers and order data in your request.

POST
/v1/orders/create
curl -X POST https://api.mpodx.com/v1/orders/create \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{  //... your order data  }'

The Create Order Model

The create order model contains all the information needed for you to create an order in our system against a variety of product types. See the default fields section for required fields and modify your items array depending on whether your items are POD or Fulfillment MPODx created product (No custom text), POD MPODx created product with custom text, or a non-MPODx created product & submitting your own printfiles.

Properties

  • Name
    Type
    string
    Description
    Your unique identifier for the order (required).
  • Name
    Type
    string
    Description
    An optional order note (optional).
  • Name
    Type
    timestamp
    Description
    The timestamp of when the order was created (required).
  • Name
    Type
    string
    Description
    The name for shipping (required).
  • Name
    Type
    string
    Description
    The phone number for shipping (required).
  • Name
    Type
    string
    Description
    The first line of the shipping address (required).
  • Name
    Type
    string
    Description
    The second line of the shipping address (optional).
  • Name
    Type
    string
    Description
    The city for shipping (required).
  • Name
    Type
    string
    Description
    The ZIP code for shipping (required).
  • Name
    Type
    string
    Description
    The state for shipping (required).
  • Name
    Type
    string
    Description
    The country for shipping (required).
  • Name
    Type
    string
    Description
    The name for returns (optional).
  • Name
    Type
    string
    Description
    The phone number for returns (optional).
  • Name
    Type
    string
    Description
    The first line of the return address (optional).
  • Name
    Type
    string
    Description
    The second line of the return address (optional).
  • Name
    Type
    string
    Description
    The city for returns (optional).
  • Name
    Type
    string
    Description
    The ZIP code for returns (optional).
  • Name
    Type
    string
    Description
    The state for returns (optional).
  • Name
    Type
    string
    Description
    The country for returns (optional).
  • Name
    {
    Type
    object
    Description
    The packing slip information (optional). Only submit this data if you want to overide your default packing slip from your MPODx store or you are submitting printfiles and need custom messaging on packing slips.
  • Name
    Type
    integer
    Description

    The unique identifier for the packing insert (optional). Including this field without a pre-agreed packing insert ID will return errors.

  • Name
    [
    Type
    array
    Description

    An array of the order items (required).

  • Name
    Type
    string
    Description
    The name of the custom text field (required).
  • Name
    Type
    string
    Description
    The text for the custom text field (required).

Data Structure

The data below contains all possible fields and should be only be used as a guide for structuring your data. You would never submit this combination of different item array structures together. Instead see the below for how to properly structure your items array depending on the type of API call you need to make.

Example data structure

{
   "external_ref": "PKG12345",
   "order_note": "Handle with care",
   "created_at": "2023-10-16T10:00:00Z",
   "shipping_name": "John Doe",
   "shipping_phone": "+1234567890",
   "shipping_address_1": "123 Main St",
   "shipping_address_2": "Apt 4B",
   "shipping_city": "New York",
   "shipping_zip": "10001",
   "shipping_state": "NY",
   "shipping_country": "USA",
   "return_name": "John Doe",
   "return_phone": "+1234567890",
   "return_address_1": "123 Main St",
   "return_address_2": "Apt 4B",
   "return_city": "New York",
   "return_zip": "10001",
   "return_state": "NY",
   "return_country": "USA",
   "packing_slip": {
      "branding_message": "At MPODx We are committed to providing you with the highest quality products and exceptional customer service. We're delighted to have you as part of our community.",
      "contact_message": "Need support? Contact us at support@mpodx.com or call us on 012345678910"
   },
   "insert_id": 3425,
   "items": [
      { //... For a standard product
         "sku": "product123",
         "quantity": 1
      },
      { //... For a product with custom text
         "sku": "product456",
         "quantity": 1,
         "print_areas": {
            "front": {
               "preview_image": "https://example.com/preview-images/front-preview2.png",
               "custom_text": [
                  {
                     "field_name": "customtext1",
                     "text": "Team Rocket"
                  },
                  {
                     "field_name": "customtext2",
                     "text": "Catch em all"
                  }
               ]
            },
            "back": {
               "preview_image": "https://example.com/preview-images/back-preview2.png",
               "custom_text": [
                  {
                     "field_name": "customtext1",
                     "text": "Team Rocket"
                  },
                  {
                     "field_name": "customtext2",
                     "text": "Catch em all"
                  }
               ]
            }
         }
      },
      { //... For a non MPODx created product, submitting your own printfiles
         "sku": "product789",
         "quantity": 1,
         "print_areas": {
            "front": {
               "print_file": "https://example.com/printfiles/front-print2.png",
               "preview_image": "https://example.com/preview-images/front-preview2.png"
            },
            "back": {
               "print_file": "https://example.com/printfiles/back-print2.png",
               "preview_image": "https://example.com/preview-images/back-preview2.png"
            }
         }
      }
   ]
}

Default Order Fields

The fields below should be included with every create order request. See the information in the sections below for details on how to structure the items array depending on what type of method you need to use. Quick jump: standard MPODx created, standard MPODx created with custom text or non-MPODx created & including printfiles.

Required Fields

{
  "external_ref": "PKG12345",
  "created_at": "2023-10-16T10:00:00Z",
  "shipping_name": "John Doe",
  "shipping_phone": "+1234567890",
  "shipping_address_1": "123 Main St",
  "shipping_city": "New York",
  "shipping_zip": "10001",
  "shipping_state": "NY",
  "shipping_country": "USA",
  "items": [
    //... the items array
  ]
}

Create Order (Standard)

Use this item array structure when adding an order line item for one of your MPODx products (No custom text)

This information shows you how to structure the items array to create an order line item against an MPODx product that you have previouly created in your account which doesn't have custom text. This data structure can be used to create orders against POD or Fulfillment products.

The data below shows the required fields for this API call. You do not need to include a print_areas object in your data. All printarea data is taken from your previously created product.

If you need to create an order line for products that have custom text or if you are submitting printfiles, instead see Create Order (Custom Text) or Create Order (Printfiles) for the correct item array structure to use.

This data structure should only be used to create order lines against products (POD or Fulfillment) that you have previously created in our MPODx platform.

Items array - Required Fields

{

  // ... Include default order fields

  "items": [
    {
      "sku": "product123",
      "quantity": 1,
    },
    {
      "sku": "product124",
      "quantity": 3,
    }
  ]
}

Response

{
"message":"Order created successfully",
"status":"success",
"data":{
  "order_ref":"PKG12345",
  "items":[
     {
        "item_ref":"1234567",
        "sku":"product123",
        "quantity":1
     },
     {
        "item_ref":"1234568",
        "sku":"product124",
        "quantity":3
     }
  ]
}
}

Create Order (Custom Text)

Use this items array structure when creating an order line item against one of your MPODx products that has custom text.

This information shows you how to strucuture your items array to create an order against a previously created MPODx product that has custom text. When you create an order with custom text, our system will take your submitted custom text and generate the printfiles before sending the order to be manufactured.

The data below shows the required fields for this API call. Submitting a preview image is optional but preffered. If you don't submit a preview image, we will use your default image from our MPODx platform during manufacturing/QA that contains the placeholder custom text you defined during product set-up.

If you need to create an order line item for products that have don't have custom text or if you are submitting printfiles, instead see Create Order (Standard) or Create Order (Printfiles) for the correct item array structure to use.

This data structure should be used to create orders against POD products that you have previously created in our MPODx platform that have custom text fields.

Items Array - Required Fields

{

  // ...Include default order data

  "items": [
    {
      "sku": "product123",
      "quantity": 1,
      "print_areas": {
        "front": {
          "preview_image": "https://example.com/preview-images/front-preview.png",
          "custom_text": [{"field_name": "customtext1", "text": "Team Rocket"}, {"field_name": "customtext2", "text": "Catch em all"}]
        },
        "back": {
          "preview_image": "https://example.com/preview-images/back-preview.png",
          "custom_text": [{"field_name": "customtext3", "text": "Blastoff"}]
        }
      }
    }
  ]
}

Response

{
   "message":"Order created successfully",
   "status":"success",
   "data":{
      "order_ref":"PKG12345",
      "items":[
         {
            "item_ref":"1234567",
            "sku":"product123",
            "quantity":1
         },
         {
            "item_ref":"1234568",
            "sku":"product124",
            "quantity":3
         }
      ]
   }
}

Create Order (Printfiles)

Use this item array structure when you want to submit your own printfiles

This information shows you how to structure your item array data to create an order when submitting printfiles without the need to have a previously created product in MPODx. A preview image is optional but preffered to ensure accurate QA during manufacturing, MPODx does not accept any manufacturing risk for orders that do not contain preview images.

If you need to create an order line item for standard MPODx products which you have created, instead see Create Order (Standard) or Create Order (Custom Text) for the correct item array structure to use.

This data structure should be used if you are submitting your own printfiles to us via the API without creating a product in MPODx.

Items Array - Required Fields

{

  // ... Include default order fields

  "items": [
    {
      "sku": "product123",
      "quantity": 1,
      "print_areas": {
        "front": {
          "print_file": "https://example.com/printfiles/front-print.png",
          "preview_image": "https://example.com/preview-images/front-preview.png"
        },
        "back": {
          "print_file": "https://example.com/printfiles/back-print.png",
          "preview_image": "https://example.com/preview-images/back-preview.png"
        }
      }
    }
  ]
}

Response

{
   "message":"Order created successfully",
   "status":"success",
   "data":{
      "order_ref":"PKG12345",
      "items":[
         {
            "item_ref":"1234567",
            "sku":"product123",
            "quantity":1
         },
         {
            "item_ref":"1234568",
            "sku":"product124",
            "quantity":3
         }
      ]
   }
}

Return Address

The return address fields are not required if you a) Have an MPODx account with connected stores, b) Are an enterprise client with a pre-agreed fixed return address. Including a return address in the API call will superceed all other settings and set the return address for the submitted order.

Return Address Fields

{

  // ...Other order fields

  "return_address_1": "123 Main St",
  "return_address_2": "Apt 4B",
  "return_city": "New York",
  "return_zip": "10001",
  "return_state": "NY",
  "return_country": "USA",

}

Packing Slips

You can submit an optional packing_slip array with messages to be printed on your packing slips. This is useful if you are submitting your own printfiles and need flexibility to customize packing slips for your clients. This feature may not be availiable for all product types, speak to your MPODx representative before using this option.

Packing Slip Fields

{

  // ...Other order fields

  "packing_slip": {
    "branding_message": "At MPODx We are committed to providing you with the highest quality products and exceptional customer service. We're delighted to have you as part of our community.",
    "contact_message": "Need support? Contact us at support@mpodx.com or call us on 012345678910"
	}

}

Marketing Inserts

Only include the 'insert_id' field if you have a pre-agreed arangement with us to provide marketing inserts during the packing process. Speak to your MPODx representative for more information.

Marketing Insert Fields

{

  // ...Other order fields

  "insert_id": 3245

}

Order Note

You can include the optional 'order_note' field when needed.

Order Note Field

{

  // ...Other order fields

  "order_note": "Handle with care"
}

Receiving Tracking

You can use our Get Tracking endpoint to poll for tracking numbers. If you would like us to post tracking numbers to your system instead, please speak to your MPODx representative and we will work with you to configure your required data structure and other details.

Was this page helpful?