Fulfill seller-fulfilled Prime and non-Prime orders

Learn how to use the Merchant Fulfillment API to fulfill seller-fulfilled Prime and non-Prime orders. This workflow is meant to supplement an order fulfillment system. The order fulfillment system retrieves scheduled order reports that use the Reports service. Incoming orders that are not fulfilled using the workflow described here must be fulfilled by the seller using a different method.

Prerequisites

To complete this tutorial, you need:

• Authorization from the selling partner for whom you are making calls. For more information, refer to Authorizing Selling Partner API applications.
• The Direct-to-Consumer Shipping (Restricted) role assigned to your developer profile.
• The Direct-to-Consumer Shipping (Restricted) role selected in the app registration page for your application.
• Sellers who use an application that you develop based on this workflow must add the following columns to their order reports. To add this data, sellers can use the optional columns area of the Add or remove order report columns in Seller Central.
  • Incoming XML order reports must contain IsPrime and LatestShipDate.
  • Incoming flat file order reports must contain is-prime and latest-ship-date.

Step 1. Identify orders and retrieve information

Identify new orders by monitoring ORDER_CHANGE notifications. To subscribe to this notification, refer to Tutorial: Subscribe to the ORDER_CHANGE Notification. Alternatively, you can identify new orders from incoming order reports.

Retrieve the order information through the Orders API. Prime orders have the IsPrime attribute marked as true. Make sure that the FulfillmentChannels attribute is MFN.

Do not use the FulfillmentServiceLevel attribute or the ship-service-level column in order reports to identify Prime orders.

Code Sample:

Step 2. Determine the latest ship date for the Prime orders

Use the LatestShipDate attribute or the latest-ship-date column from a flat file order report to determine the date by which the Prime orders need to be shipped.

Step 3. Check inventory and validate order

Check the inventory number and make sure that the received order is ready for fulfillment.

Code Sample:

Step 4. Get shipping service offers

Call the getEligibleShipmentServices operation to get the shipping service offers for the orders identified in Step 1, and then select one that matches your priorities (for example, the least expensive or the fastest).

📘

Dos and Don'ts when fulfilling seller-fulfilled Prime and non-Prime orders

• Do use the LatestShipDate attribute from the Orders API or the latest-ship-date value from the order report for the ShipDate parameter.
• Don't specify the MustArriveByDate parameter, because this parameter limits the number of shipping service offers that are returned.
• Do save the ShippingServiceId value from each shipping service offer that is returned. You use this value for subsequent calls to the createShipment operation when you create shipments for specific shipping service offers.
• Do check the included and excluded Benefits before you select a shipping service offer.

Code Samples:

Step 5. (Optional) Declare dangerous goods

If your order contains dangerous goods, they must be declared so they can be handled properly. Dangerous goods attributes are collected on each item. As a shipper, you must provide these attributes. Amazon does not provide a way to find these attributes for your item.

📘

Note

Some carriers have additional requirements for shipping dangerous goods. Check with your carrier to ensure that your shipments meet their requirements.

Request

The following example is a request for Amazon Shipping that includes dangerous goods attributes. For more information on each attribute, refer to the Merchant Fulfillment API v0 reference.

Request example

{
    "ShipmentRequestDetails": {
        "AmazonOrderId": "903-3489051-5871062",
        "ItemList": [{
            "OrderItemId": "6220427528165",
            "Quantity": 1,
            "IsHazmat": true,
            "LiquidVolume": {
                "Unit": "C",
                "Value": 3
            },
            "DangerousGoodsDetails": {
                "UnitedNationsRegulatoryId": "UN1090",
                "TransportationRegulatoryClass": "3",
                "PackingGroup": "III",
                "PackingInstruction": "PI965_SECTION_IA"
            }
        }],
        "ShipFromAddress": {
            "Name": "John Doe",
            "AddressLine1": "300 Turnbull Ave",
            "Email": "[email protected]",
            "City": "Detroit",
            "StateOrProvinceCode": "MI",
            "PostalCode": "48123",
            "CountryCode": "US",
            "Phone": "7132341234"
        },
        "PackageDimensions": {
            "Length": 10.25,
            "Width": 10.25,
            "Height": 10.25,
            "Unit": "inches"
        },
        "Weight": {
            "Value": 10.25,
            "Unit": "oz"
        },
        "ShippingServiceOptions": {
            "DeliveryExperience": "DeliveryConfirmationWithoutSignature",
            "CarrierWillPickUp": false,
            "CarrierWillPickUpOption": "NoPreference"
        }
    }
}

Step 6. Create a shipment

After you choose the shipment service that best matches your use case, call the createShipment operation for one of the shipping service offers that was returned in the previous step.

Use the following parameter values:

• ShipmentRequestDetails: Use the same values that you included in your getEligibleShipmentServices call in Step 4.

🚧

Important

Make sure you include the dangerous goods attributes for your item (refer to Step 5). You must declare dangerous goods so that they can be properly handled.

• ShippingServiceId: Use the value associated with this shipping service offer.

The createShipment operation starts the payment process for shipping, which deducts from the seller's Amazon seller account and confirms the shipment.

📘

Save the item list and shipment ID

Save the ShipmentId value returned by the createShipment operation. If the seller wants to print a new label, cancel a shipment, or check shipment status at a later time, the ShipmentId is used to identify the shipment. Save the item list along with each shipment ID.

Code Sample:

Step 7. Extract and print the shipping label

Extract the shipping label from the Label attribute returned by the createShipment operation. Print or store the shipping label.

For more information, refer to Manipulate shipping labels.

Code Samples:

Step 8. Create shipments for the remaining orders

Repeat step 3 through step 5 until you have created shipments for the orders identified in step 1.