Merchant Fulfillment API v0 Use Case Guide

API Version: v0

What is the Merchant Fulfillment API?

Use the Merchant Fulfillment API to build applications for sellers to use Amazon's Buy Shipping services to purchase shipping for non-Prime and Prime orders.

You can build applications that can:

• Preview shipping service offers based on shipping requirements, such as ship date, must arrive by date, package size, and weight.
• Create shipments based on seller-selected shipping service offers.
• Automatically pay for shipping through the API service.
• Receive and print shipping labels.

📘

Check the roles you have linked to your profile

Your access to Amazon SP API data depends on the roles you have linked to your Developer Profile and Application. For more information, refer to Roles in the Selling Partner API.

Terminology

Tutorial 1: Fulfill Seller Fulfilled Prime and non-Prime orders

Amazon recommends that you use this Merchant Fulfillment service workflow to fulfill Seller Fulfilled 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. Refer to Authorizing Selling Partner API applications for more information.
• Approval for the Direct to Consumer Shipping (Restricted) role in 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 these columns to their order reports. They can use the optional columns area of the Add or remove order report columns in Seller Central.

❗️

Important

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 MFN Notifications, refer to Tutorial 5: Subscribe to MFN Notifications. 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, then select one that matches your priorities (for example, cheapest or 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, as this will unnecessarily limit the number of shipping service offers that are returned.
• Do save the ShippingServiceId value from each shipping service offer that is returned. You will use this 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 Tutorial 3: Manipulate shipping labels.

Code Samples:

Step 8. Create shipments for the remaining orders

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

Tutorial 2: Cancel a shipment

This tutorial demonstrates how to add functionality to the workflow described in How to fulfill Seller Fulfilled Prime orders.

Step 1. Call the cancelShipment operation

Call the cancelShipment operation and specify the ShipmentId value of the shipment you want to cancel.

This returns the details of a shipment, which includes the shipment status. It might also return one or more unexpected errors occurred during the cancelShipment operation.

Step 2. (Optional) Check the status of the canceled shipment

1. Call the getShipment operation and specify the ShipmentId value for the canceled shipment.
2. Get the cancellation status from the status element returned by the getShipment operation.

❗️

Errors

The service returns the LabelCancelWindowExpired error if the allotted time period for canceling a label has expired. Refer to Error codes.

Tutorial 3: Manipulate shipping labels

The createShipment and getShipment operations return a shipping label file in PDF, PNG, or ZPL format, depending on the carrier. Amazon compresses the document data before it returns it as a Base64-encoded string.

Extract document data from a compressed file

1. Decode the Base64-encoded string.
2. Save the decoded string with a .gzip extension.
3. Extract the PDF, PNG, or ZPL file from the GZIP file.

createShipment and getShipment also return a Base64-encoded MD5 hash to validate the document data.

Reprint a shipping label

1. Call the getShipment operation and include the ShipmentId for the shipment that requires the shipping label.
2. Extract and print the shipping label from the FileContents element that is returned by the getShipment operation.

Tutorial 4: Include additional seller input data

The getAdditionalSellerInputs operation returns a list of additional inputs that are required from the seller to purchase shipping for some shipping services. It is only required for shipment services that require additional seller inputs.

Step 1. Determine if the shipment service requires additional seller inputs

1. Call the getEligibleShipmentServices operation.
2. Retrieve the list of ShippingServices returned by the operation.
3. Check for the RequiresAdditionalSellerInputs attribute.
4. If RequiresAdditionalSellerInputs is true, it means the shipment service requires additional seller inputs.

Step 2. Call the getAdditionalSellerInputs operation

If the shipment service requires additional seller inputs, call the getAdditionalSellerInputs operation and include all required parameters. The response includes a list of required parameters that a seller must include if they want to purchase shipping services.

Step 3. Review the additional seller inputs required

1. Examine the response from the getAdditionalSellerInputs operation.
2. Identify the specific additional seller inputs that are required.

Step 4. Provide the required seller inputs

1. Collect the necessary information based on the additional seller inputs identified in the response.
2. Ensure the information provided meets the syntax requirements specified in the response.
3. Prepare the required seller inputs for the next step.

Step 5. Create the shipment

1. If the required seller inputs are collected and prepared, call the createShipment operation.
2. Use the necessary parameters and seller inputs with the createShipment operation.
3. Follow the appropriate syntax requirements for the seller inputs in the getAdditionalSellerInputs response.

Step 6: (Optional) Retrieve saved values

The getAdditionalSellerInputs operation returns saved values previously provided to Amazon. To access these saved values, examine the response from the getAdditionalSellerInputs operation.

Tutorial 5: Subscribe to MFN notifications

You can use the Selling Partner API for Notifications to subscribe to notifications that are relevant to a selling partner's business. With this API, you can create a destination to receive, subscribe, and delete notification subscriptions. Instead of polling for information, your application can receive information directly from Amazon when an event activates a notification to which you are subscribed.

🚧

Important

Sellers can subscribe to the ORDER_CHANGE notification, which is sent whenever there is an order availability status change.

The MFN_ORDER_STATUS_CHANGE and ORDER_STATUS_CHANGE notification types have been removed. Please update your applications to use the ORDER_CHANGE notification. [ORDER_CHANGE]((https://developer-docs.amazon.com/sp-api/docs/notifications-api-v1-use-case-guide#order_change) sends an order-level payload whenever there is an important change in the order. Important changes include order status changes and buyer requested cancellations. For detailed information about SP-API deprecation dates, refer to the deprecations table.

Step 1. Subscribe to the ORDER_CHANGE notification

To set up and subscribe to the ORDER_CHANGE notification, follow the Notifications API SQS Tutorial. The following figure provides an illustrated overview of the tutorial.

Step 2. Poll the queue to retrieve the latest ORDER_CHANGE messages

1. Retrieve the queue URL: Connect to the SQS service and retrieve the URL for the queue that receives the ORDER_CHANGE messages. This URL uniquely identifies the queue and is used to interact with it.
2. Configure polling parameters: Review the polling parameters to determine how frequently and how many messages to retrieve at a time. This includes the wait time between subsequent polling attempts and the maximum number of messages to retrieve in each request.
3. Poll the queue: To poll the queue, send the requests to retrieve the messages. Use the ReceiveMessage operation to retrieve the messages from the queue. When you call this operation, you can specify the queue URL, maximum number of messages to retrieve, and other optional parameters, such as visibility timeout.

Alternatively, you can configure event source mapping to automatically invoke a Lambda function when new messages arrive to the SQS queue. For more information on event source mapping, refer to Tutorial: Using Lambda with Amazon SQS.
4. Process the messages: When you receive the messages, you can process them according to your application's requirements. In the case of ORDER_CHANGE messages from the SP-API, you can extract the relevant information, such as the order ID, status change details, and timestamps.
5. Delete processed messages: After each message is successfully processed, make sure to delete it from the queue with the DeleteMessage operation provided by SQS. This step ensures that the processed messages are removed from the queue and won't be retrieved again in subsequent polling attempts.

Step 3. Process the order information and call shipment services

The ORDER_CHANGE notification returns high-level information related to the order, such as the OrderId, OrderItemId and the OrderStatus. To learn more about response attributes, refer to ORDER_CHANGE notifications.

To automate the fulfillment process, you must:

• Check notification messages with an OrderStatus of UpComing, Pending, or Unshipped. Check that MFN is within the FulfillmentChannel attribute.
• Retrieve order and shipping information with the getOrder operation.
• Pass this information to the getEligibileShipmentServices operation and follow the steps in Tutorial 1.

Error codes

The following table describes the Merchant Fulfillment error codes.