Merchant API: purchase orders

About this article

This article is about how to manage purchase orders via the Merchant API.

Table of contents

Introduction

Requirements

Limitations

Setup

Available endpoints

• Create a shipment to an Amazon warehouse
• Import purchase orders from Amazon Vendor
• Acknowledge purchase orders
• Get purchase order shipments
• Update purchase order shipments

Shipment request body

Shipment examples

Introduction

Processing purchase orders follows a different workflow from processing regular sales orders. If you ship a shipment that contains purchase orders, you need to include special documents in the shipment. In addition, one purchase order shipment can ship parts of multiple orders. Meanwhile, you generally ship sales orders as one package per order.

Requirements

Your Amazon Vendor channel plugin must already be authorized. Complete the Authorization step in your Amazon Vendor channel plugin.

Limitations

It is not possible to import purchase orders that are linked to a specific vendor code. All purchase orders for all vendor codes that are linked to the Vendor Central account that you use in a given Amazon Vendor channel plugin are imported into ChannelEngine.

Setup

Contact the ChannelEngine Support team or your customer success advisor to set up managing your Amazon Vendor purchase orders via ChannelEngine.

Available endpoints

Create a shipment to an Amazon warehouse

• Create a purchase order shipment: POST /v2/purchase-orders/shipments

When you create your initial shipment, decide which items go on a pallet and which items go into a carton. Additionally, one shipment can ship parts of multiple orders. Therefore, you can optimize the space on your pallets and in your cartons before shipping.

Take advantage of the PUT method to gradually update your shipment until it is accurate and complete.

For guidance on creating your shipment request, check out the sections Shipment request body and Shipment examples below.

Import purchase orders from Amazon Vendor

• Retrieve purchase orders: GET /v2/purchase-orders

Based on the response, you decide if you can deliver the items in the purchase order.

Then, acknowledge which lines you accept and reject.

Acknowledge purchase orders

• Acknowledge purchase orders POST /v2/purchase-orders/lines/acknowledge

On each line, accept or reject a purchase order. In the body of your request, the following values are accepted for the AcknowledgementCode:

Acknowledgement codes

Get purchase order shipments

• Retrieve already-created purchase order shipments: GET /v2/purchase-orders/shipments/merchant

Use a set of filters to reference shipments that you have already started while you begin to pick and pack your pallets and cartons.

Update purchase order shipments

• Update already-created shipments: PUT /v2/purchase-orders/shipments

Fill out your pallets and cartons with more items as you process more purchase orders. Update your shipment without limit, but as soon as the given shipment arrives at the Amazon warehouse, you can no longer update it. You may face a penalty from Amazon if you update your shipment after delivery.

Shipment request body

The fields below are accepted in your shipment request. In the descriptions of each field, follow the requirements that pertain to Amazon.

General fields

• ChannelId - required. To locate the ChannelID, check out ChannelEngine: where can I find the ChannelName, ChannelID, and ChannelReference?
• Model - the main shipment model object.
• MerchantShipmentNo - required.
• CarrierShipmentNo - optional. For Amazon, it is required for the US, CA, and MX.
• ChannelShipmentNo - optional.
• BillOfLadingNo - optional. For Amazon, required if ShipmentType = TRUCK_LOAD or LESS_THAN_TRUCK_LOAD.
• ShipmentType - optional. Values: TRUCK_LOAD, LESS_THAN_TRUCK_LOAD, SMALL_PARCEL.
• TransportationMode - optional. Values: ROAD, AIR, OCEAN.
• CarrierName - optional.
• ShipmentDate - optional. Default: GETDATE().
• EstimatedDeliveryDate - optional.
• SellingPartyId - optional. For Amazon, required (and should be a valid party).
• ShipFromPartyId - optional. For Amazon, required (and should be a valid party).
• ShipToPartyId - optional. For Amazon, required (and should be a valid party).

Overall dimensions

• Dimensions - optional. If provided, include:
  • Height - optional. For Amazon, required if any dimensions are provided.
  • Width - optional. For Amazon, required.
  • Length - optional. For Amazon, required.
  • Unit - required. Values: FEET, INCH, METER, YARD.

Overall weight

• Weight - optional. If provided, include:
  • Value - required.
  • Unit - required. Values: GRAM, KILOGRAM, OUNCE, POUND.

Lines

You must include line items in your shipment. Follow these basic guidelines: do not put a pallet in a carton, and do not put a carton in an item. Items go into cartons; items and cartons go onto pallets.

• Lines - required.
• Type - required. Values: ITEM, CARTON, PALLET.
• IdentifierType - required. Values: SSCC, SKU, GTIN. SSCC is only allowed for Type = CARTON or PALLET. SKU is only allowed for Type = ITEM.
• IdentifierValue - required. Either an SSCC or a SKU (which should be known on ChannelEngine).
• LayersPerPallet - optional. Only allowed when Type = PALLET. Required when Type = PALLET.
• ItemsPerLayer - optional. Only allowed when Type = PALLET. Required when Type = PALLET. Could refer to the number of cartons or the number of items (if they are not in a carton).
• Dimensions - optional. For Amazon, only relevant when Type = CARTON or Type = PALLET.
  • Height - optional. For Amazon, required.
  • Width - optional. For Amazon, required.
  • Length - optional. For Amazon, required.
  • Unit - required. Values: Feet, Inches, Meter, Yard.
• Weight - optional. If provided, include:
  • Value - required.
  • Unit - required. Values: Grams, Kilograms, Ounces, Pounds.
• Quantity - optional. For Amazon, only allowed and required when Type = ITEM. If Type = PALLET or CARTON, the value is always 1; if ITEM, the value is always more than 1.
• QuantityUnitOfMeasure - required. Values: CASE, ITEM. Default: ITEM.
• UnitsPerCase - optional. Only allowed and required when QuantityUnitOfMeasure = CASE.
• ChannelPurchaseOrderNo - optional. Only allowed and required when Type = ITEM. The value comes from an existing purchase order; inspect the response of GET /v2/purchase-orders/shipments/merchant.
• LotNo - optional. Only allowed when Type = ITEM.
• ExpiryDate - optional. Only allowed when Type = ITEM.
• HandlingCode - optional. Values: OVERSIZED, FRAGILE, FOOD, HANDLE_WITH_CARE.
• Lines - an array of Lines, e.g.: your top-level line is the pallet, and in the array, you include multiple cartons that sit on your pallet. For Amazon, the following validation applies:
  • A pallet is not allowed in pallet/carton/item (only at the top level). 
  • A carton is allowed inside a pallet but not allowed inside a carton/item, and also allowed as top level.
  • An item is allowed inside a pallet/carton, but not allowed as the top level. The lowest level should always be an item.

Shipment examples

The examples below show how to use the POST or PUT methods of this endpoint: /v2/purchase-orders/shipments.

Example shipment #1

A shipment containing one item on a pallet.

{
  "ChannelId": 1,
  "Model": 
  {
    "MerchantShipmentNo": "SPN-56291003",
    "BillOfLadingNo": "SO157817/001",
    "ShipmentType": "LESS_THAN_TRUCK_LOAD",
    "TransportationMode": "ROAD",
    "ShipmentDate": "2025-05-23T00:00:00.000Z",
    "EstimatedDeliveryDate": "2025-05-24T00:00:00.000Z",
    "SellingPartyId": "ABCDE",
    "ShipFromPartyId": "ABCDE",
    "ShipToPartyId": "IBA9",
    "Lines": 
    [
      {
        "Type": "PALLET",
        "IdentifierType": "SSCC",
        "IdentifierValue": "000000000000000203",
        "Lines": 
        [
          [
            {
              "Type": "ITEM",
              "IdentifierType": "SKU",
              "IdentifierValue": "PRD-55678-C40",
              "Quantity": 1400,
              "QuantityUnitOfMeasure": "ITEM",
              "ChannelPurchaseOrderNo": "8G5Z2E1X",
              "LotNo": "000000",
              "ExpiryDate": "2027-12-10T10:04:50.242Z"
            }
          ]
        ]
      }
    ]
  }
}

Example shipment #2

A shipment containing several pallets, with items on the pallets.

{
  "ChannelId":1,
  "Model":
  {
    "MerchantShipmentNo":"SPN-56291004",
    "BillOfLadingNo":"XT291847/003",
    "ShipmentType":"LESS_THAN_TRUCK_LOAD",
    "TransportationMode":"ROAD",
    "ShipmentDate":"2026-03-21T00:00:00.000Z",
    "EstimatedDeliveryDate":"2026-03-21T00:00:00.000Z",
    "SellingPartyId":"ABCDE",
    "ShipFromPartyId":"ABCDE",
    "ShipToPartyId":"BHX4",
    "Lines": 
    [
      {
        "Type":"PALLET",
        "IdentifierType":"SSCC",
        "IdentifierValue":"050139197040009741",
        "Lines":
        [
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C400",
            "Quantity":"96",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"L000476799",
            "ExpiryDate":"2027-03-21T17:35:19.379Z"
          }
        ]
      },
      {
        "Type":"PALLET",
        "IdentifierType":"SSCC",
        "IdentifierValue":"050139197040009750",
        "Lines": 
        [
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C401",
            "Quantity":"96",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"L000476810",
            "ExpiryDate":"2027-03-21T17:35:19.379Z"
          }
        ]
      },
      {
        "Type":"PALLET",
        "IdentifierType":"SSCC",
        "IdentifierValue":"050139190001719363",
        "Lines":
        [
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C402",
            "Quantity":"90",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"L000480788",
            "ExpiryDate":"2027-03-21T17:35:19.379Z"
          }
        ]
      },
      {
        "Type":"PALLET",
        "IdentifierType":"SSCC",
        "IdentifierValue":"050139190001719387",
        "Lines":
        [
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C403",
            "Quantity":"18",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"T018455766",
            "ExpiryDate":"2027-03-21T17:35:19.379Z"
          },
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C404",
            "Quantity":"1",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"T018668883",
            "ExpiryDate":"2027-03-21T17:35:19.379Z"
          },
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C405",
            "Quantity":"40",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"L000487913",
            "ExpiryDate":"2027-03-21T17:35:19.379Z"
          },
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C406",
            "Quantity":"40",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"L000482482",
            "ExpiryDate":"2027-03-21T17:35:19.380Z"
          },
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C407",
            "Quantity":"18",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"T018780714",
            "ExpiryDate":"2027-03-21T17:35:19.380Z"
          },
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C408",
            "Quantity":"5",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"T018847264",
            "ExpiryDate":"2027-03-21T17:35:19.380Z"
          },
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C409",
            "Quantity":"80",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"L000468751",
            "ExpiryDate":"2027-03-21T17:35:19.380Z"
          },
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C410",
            "Quantity":"5",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"T018844737",
            "ExpiryDate":"2027-03-21T17:35:19.380Z"
          }
        ]
      },
      {
        "Type":"PALLET",
        "IdentifierType":"SSCC",
        "IdentifierValue":"050139190001719370",
        "Lines":
        [
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C411",
            "Quantity":"1",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"T018668883",
            "ExpiryDate":"2027-03-21T17:35:19.379Z"
          },
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C412",
            "Quantity":"21",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"L000485512",
            "ExpiryDate":"2027-03-21T17:35:19.380Z"
          },
          {
            "Type":"ITEM",
            "IdentifierType":"SKU",
            "IdentifierValue":"PRD-55678-C413",
            "Quantity":"10",
            "QuantityUnitOfMeasure":"EACHES",
            "ChannelPurchaseOrderNo":"256NSHHD",
            "LotNo":"L000473592",
            "ExpiryDate":"2027-03-21T17:35:19.380Z"
          },
          {...}
        ]
      }
    ]
  }
}