Tutorial: Create a shipment with an Amazon-partnered carrier (PCP)

Learn how to inbound Small Parcel Deliveries (SPD) or pallets (LTL/FTL) with an Amazon-partnered carrier using the Fulfillment Inbound API.

Step 1. Create an inbound plan

Operation

• createInboundPlan

Parameters

• destinationMarketplaces: Target marketplaces for shipment.
• sourceAddress: Address from which items are shipped.
• items:
  • prepOwner: Preparation owner.
  • labelOwner: Labeling owner.
  • msku: Merchant SKU.
  • itemQuantity: Quantity of items.

Response

• Includes inboundPlanId and operationId to check the status of inbound plan creation.

📘

Note

POST operations are asynchronous. Check the status of a POST operation by passing its operationId to getInboundOperationStatus.

Step 2. Generate packing options

Operation

• generatePackingOptions

Parameters

• inboundPlanId: Use the inbound plan ID created in Step 1.

Response

• operationId: An ID that you can use to check the status of packing options generation.

Step 3. List packing options

Operation

• listPackingOptions

Parameters

• inboundPlanId: Input the inbound plan ID.

Response

• Includes available packingOptions. Each packing option is represented by a packingOptionId.
• Each packing option contains one or more packingGroups, identified by packingGroupId. Each packing group includes a list of SKUs that should be packed together.

To view the SKU items in a packing group, call listPackingGroupItems with the packing group's packingGroupId.

📘

Note

Choose only one packing option (packingOptionId).

Step 4. Confirm packing option

Operation

• confirmPackingOption

Parameters

• inboundPlanId: The ID of the inbound plan.
• packingOptionId: The chosen packing option ID. You can only confirm one option per inbound plan.

Response

• operationId: An ID that you can use to check the status of the packing confirmation.

Step 5. Set packing information

Operation

• setPackingInformation

Parameters

• inboundPlanId: ID of the inbound plan.
• packingGroupId: ID for each packing group within the chosen packing option.
• boxes: Includes box contents source, box dimensions (weight and quantity), items with prep info, and item quantities matching the inbound plan.

Response

• operationId: An ID that you can use to check the status of the API call.

Request example

{
  "packageGroupings": [
    {
      "boxes": [
        {
          "contentInformationSource": "BOX_CONTENT_PROVIDED",
          "dimensions": {
            "height": 10,
            "length": 10,
            "unitOfMeasurement": "IN",
            "width": 10
          },
          "quantity": 1,
          "weight": {
            "unit": "LB",
            "value": 2
          },
          "items": [
            {
              "labelOwner": "AMAZON",
              "msku": "SKU12345",
              "prepOwner": "AMAZON",
              "quantity": 1
            }
          ]
        }
      ],
      "packingGroupId": "pg1xxxxxxxxxxxxxxxxxxx"
    },
    {
      "boxes": [
        {
          "contentInformationSource": "BOX_CONTENT_PROVIDED",
          "dimensions": {
            "height": 10,
            "length": 10,
            "unitOfMeasurement": "IN",
            "width": 10
          },
          "quantity": 1,
          "weight": {
            "unit": "LB",
            "value": 1
          },
          "items": [
            {
              "labelOwner": "SELLER",
              "msku": "SKU67890",
              "prepOwner": "SELLER",
              "quantity": 1
            }
          ]
        }
      ],
      "packingGroupId": "pg2yyyyyyyyyyyyyyyyyyy"
    }
  ]
}

Step 6. Generate placement options

Operation

generatePlacementOptions

Parameters

• inboundPlanId: ID of the inbound plan.

Response

• operationId: An ID that you can use to check the status of placement options generation.

Step 7. List placement options

Operation

• listPlacementOptions

Parameters

• inboundPlanId: ID of the inbound plan.

Response

• Includes available placementOptions, each represented by a placementOptionId.
• Each placementOptionId includes one or more shipmentIds and details on fees or discounts.

📘

Note

Choose only one placement option (placementOptionId).

Response example

"placementOptions": [
  {
    "fees": [
      {
        "description": "Placement service fee represents service to inbound with minimal shipment splits and destinations of skus",
        "type": "FEE",
        "value": {
          "amount": 1.10,
          "code": "USD"
        },
        "target": "Placement Services"
      }
    ],
    "shipmentIds": [
      "shxxxxxxxxxxxxxxx",
      "shxxxxxxxxxxxxxxx"
    ],
    "discounts": [],
    "expiration": "yyyy-mm-ddT00:00:00.00Z",
    "placementOptionId": "plxxxxxxxxxxxxxxx",
    "status": "OFFERED"
  }
]

The following code sample demonstrates how to choose the least expensive placementOption. Customize this code to fit your own selection criteria.

Step 8. Generate transportation options

Operation

• generateTransportationOptions

Parameters

• inboundPlanId: ID of the inbound plan.
• placementOptionId: The chosen placement option ID.
• shipmentTransportationConfigurations: Configuration details including:
  • shipmentId: Each shipment ID within the chosen placement option. Include all shipment IDs within the selected placement option.
  • readyToShipWindow: Start date for when shipments are ready for delivery.
  • freightInformation (only if you want to ship pallets): The declared value and freight class.
  • pallets (only if you want to ship pallets): Information about the pallets being shipped, including quantity, dimensions, weight, and stackability.

Response

• Includes an operationId that you can use to check the status of transportation options generation.

Request example for small parcel delivery

{
  "placementOptionId": "plxxxxxxxxxxxxxxxxxxxx",
  "shipmentTransportationConfigurations": [
    {
      "readyToShipWindow": {
        "start": "yyyy-mm-ddT00:00:00Z"
      },
      "shipmentId": "sh1xxxxxxxxxxxxxxx"
    },
    {
      "readyToShipWindow": {
        "start": "yyyy-mm-T00:00:00Z"
      },
      "shipmentId": "sh2xxxxxxxxxxxxxx"
    }
  ]
}

Request example for pallet (LTL/FTL) delivery

{
  "placementOptionId": "plxxxxxxxxxxxxxxxxxxxx",
  "shipmentTransportationConfigurations": [
    {
      "readyToShipWindow": {
        "start": "yyyy-mm-ddT00:00:00Z"
      },
      "shipmentId": "shxxxxxxxxxxxxxxxx",
      "freightInformation": {
        "declaredValue": {
          "amount": 200,
          "code": "USD"
        },
        "freightClass": "FC_XX"
      },
      "pallets": [
        {
          "quantity": 1,
          "dimensions": {
            "height": 48,
            "length": 48,
            "unitOfMeasurement": "IN",
            "width": 40
          },
          "stackability": "STACKABLE",
          "weight": {
            "unit": "LB",
            "value": 600
          }
        }
      ]
    }
  ]
}

Step 7. List transportation options

Operation

• listTransportationOptions

Parameters

• inboundPlanId: The ID of the inbound plan.
• placementOptionId: The ID of the chosen placement option.

Response

• Includes different available transportationOptions, each represented by transportationOptionId per shipmentId. Each transportation option contains details about:
  • carrier: Identifies the carrier.
  • shippingMode: Identifies the shipment type (for example, Small Parcel Delivery or pallets).
  • shippingSolution: Identifies whether the carrier is Amazon Partnered or your own transportation carrier.
  • preconditions: Conditions that must be met to provide the delivery window. Only applicable to your own carrier options.

📘

Note

If you have multiple shipmentIds from listPlacementOptions, choose a transportationOptionId for each shipmentId.

To ship using the Amazon Partnered Carrier in this tutorial, you must select the transportationOption based on your shipment type:

• For small parcel deliveries, choose the option where shippingMode is GROUND_SMALL_PARCEL.
• For pallet shipments, choose the option where shippingMode is FREIGHT_LTL.

In both cases, ensure that shippingSolution is AMAZON_PARTNERED_CARRIER.

Response example for small parcel delivery

"transportationOptions": [
  {
    "carrier": {
      "name": "United States Postal Service",
      "alphaCode": "USPS"
    },
    "preconditions": [
      "CONFIRMED_DELIVERY_WINDOW"
    ],
    "shipmentId": "shxxxxxxxxxxxxxx",
    "shippingMode": "GROUND_SMALL_PARCEL",
    "transportationOptionId": "toxxxxxxxxxxxxxx",
    "shippingSolution": "USE_YOUR_OWN_CARRIER"
  },
  {
    "carrier": {
      "name": "UPS",
      "alphaCode": "UPSN"
    },
    "quote": {
      "cost": {
        "amount": 19.6,
        "code": "USD"
      }
    },
    "preconditions": [],
    "shipmentId": "shxxxxxxxxxxxxxx",
    "shippingMode": "GROUND_SMALL_PARCEL",
    "transportationOptionId": "toxxxxxxxxxxxxxx",
    "shippingSolution": "AMAZON_PARTNERED_CARRIER"
  }
]

Response example for pallet delivery

{
  "carrier": {
    "name": "XXXXX",
    "alphaCode": "ABCD"
  },
  "carrierAppointment": {
    "startTime": "2024-10-11T00:00Z",
    "endTime": "2024-10-11T23:59Z"
  },
  "quote": {
    "cost": {
      "amount": 326.54,
      "code": "USD"
    },
    "expiration": "2024-10-09T22:40Z"
  },
  "preconditions": [],
  "shipmentId": "shxxxxxxxxxxxxxx",
  "shippingMode": "FREIGHT_LTL",
  "transportationOptionId": "toxxxxxxxxxxxxxx",
  "shippingSolution": "AMAZON_PARTNERED_CARRIER"
}

Step 8. Get shipment

Operation

• getShipment

Parameters

• inboundPlanId: ID of the inbound plan.
• shipmentId: ID of the shipment for which to retrieve details.

Response

• Includes the source address from which the shipment originates.
• Includes the destination warehouse address for the shipment.
• Includes the current status of the shipment.

📘

Note

If you are not satisfied with the chosen options, you can regenerate and select another placement option or transportation option before final confirmation.

Step 9. Confirm placement option

Operation

• confirmPlacementOption

Parameters

• inboundPlanId: ID of the inbound plan.
• placementOptionId: The chosen placement option ID to confirm.

Response

• operationId: An ID that you can use to check the status of the placement confirmation.

📘

Note

You can only confirm one placement option per inbound plan.

Step 10. Confirm transportation options

Operation

• confirmTransportationOptions

Parameters

• inboundPlanId: ID of the inbound plan.
• transportationSelections: A list of selected transportation options for each shipment, including:
  • shipmentId: The ID of the shipment.
  • transportationOptionId: The chosen transportation option ID for that shipment.

Response

• operationId: An ID that you can use to check the status of the transportation confirmation.

Important considerations

If your inbound plan includes multiple shipments:

• For small parcel deliveries, ensure that all shipments use the same carrier.
• For pallet deliveries, you can choose different carriers for each shipment.

Step 11. Get shipment

Operation

• getShipment

Parameters

• inboundPlanId: ID of the inbound plan.
• shipmentId: ID of the shipment.

Response

• Includes the following details of shipment:
  • sourceAddress: The origin address of the shipment.
  • destinationWarehouseAddress: The address of the destination warehouse.
  • amazonReferenceId: Amazon's reference ID for the shipment.
  • selectedTransportationOptionId: The chosen transportation option ID.
  • placementOptionId: The ID of the chosen placement option.
  • shipmentConfirmationId: The ID confirming the shipment.
  • trackingDetails: Information regarding the shipment tracking.
  • status: The current status of the shipment.

📘

Note

If your inbound plan includes multiple shipment IDs, call getShipment for each shipment ID.

Step 12. Get labels

Operation

• getLabels

Parameters

• shipmentConfirmationId: The ID that confirms the shipment, retrieved from the getShipment response.
• PageType: Specifies the type of page for the labels.
• LabelType: Specifies the type of label to retrieve.

For Pallet Shipments:

• NumberOfPallets: The total number of pallets included in the shipment.
• PageSize: The size of the label pages to retrieve.

Response

• Includes a URL that you can use to download the labels associated with each shipment ID within your inbound plan.

📘

Note

Call getLabels for each shipment ID and provide the necessary parameters based on whether the shipment is a small parcel delivery or involves pallets.

[Only for Pallet Shipments] Step 13. Get bill of lading

Operation

• getBillOfLading

Parameters

• shipmentConfirmationId: The ID that confirms the shipment, retrieved from getShipment response.

Response

• Includes a URL that you can use to download the bill of lading associated with the Less Than Truckload (LTL) or Full Truckload (FTL) pallet shipment.

This process completes the creation of your inbound plan, and sends your SKUs as either individual boxes (small parcel delivery) or pallets (LTL/FTL) using the Amazon Partnered Carrier. You can verify this inbound plan through the Seller Central Send to Amazon UI.