Merchant Fulfillment API v0 Use Case Guide

API Version: v0

What is the Merchant Fulfillment API?

The Merchant Fulfillment API helps you to build applications that allows 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, and more.
• 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 that retrieves scheduled order reports using the Reports service. Incoming orders that are not fulfilled using the workflow described here must be fulfilled by the seller using some other method.

Prerequisites

To successfully complete this tutorial, you must have:

• 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 using an application that you develop based on this workflow must add these columns to their order reports using the Optional columns area of the Add or remove order report columns in Seller Central.

📘

Order reports must contain IsPrime and LatestShipDate elements

Important: The success of this workflow requires that incoming order reports contain the optional IsPrime and LatestShipDate elements for XML order reports or the optional is-prime and latest-ship-date fields for flat file order reports.

Step 1. Identify orders and retreive information

Identify new orders by keeping up with incoming ORDER_CHANGE notifications. If you haven't already, subscribe to this notification by following Tutorial 5: Subscribe to MFN Notifications. Alternatively, you can identify new orders from incoming Order Reports.

Fetch the order information through the Orders API. Prime orders have the IsPrime attribute marked as true. Also 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 to be fulfilled.

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 according to your priorities (cheapest, fastest, or something else).

📘

Dos and Donts when fulfilling Seller Fulfilled Prime and non-Prime orders

• For the ShipDate parameter, use the LatestShipDate attribute from Orders API or the latest-ship-date value from the order report.
• Do not specify the MustArriveByDate parameter, as this will unnecessarily limit the number of shipping service offers that are returned.
• Save the ShippingServiceId value from each shipping service offer that is returned. You will use this for subsequent calls to the createShipment operation when creating shipments for specific shipping service offers.

Code Samples:

Step 5. Create a shipment

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

Use the following parameter values:

• ShipmentRequestDetails: Use the same values that were included in the call to the getEligibleShipmentServices operation in the previous step.
• ShippingServiceId: Use the value associated with this shipping service offer.

Calling the createShipment operation will trigger payment for shipping, which is deducted from the seller’s Amazon seller account, and confirm the shipment. Shipping is deducted from the seller's Amazon seller account and the seller does not have to confirm the shipment by other means.

📘

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 6. 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 details, refer to Tutorial 3: Manipulating shipping labels.

Code Samples:

Step 7. Create shipments for the remaining orders

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

Tutorial 2: Cancel a shipment

This tutorial shows you 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, specifying the ShipmentId value of the shipment to be canceled.

This will return the details of a shipment, including 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, specifying the ShipmentId value of 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 window 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 returning 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, specifying the ShipmentId value of the shipment for which you want to reprint the shipping label.
2. Extract and print the shipping label from the FileContents element returned by the getShipment operation.

Tutorial 4: Include the 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

1. If the shipment service requires additional seller inputs, call the getAdditionalSellerInputs operation.
2. Provide the necessary parameters required by the operation.
3. Receive a response that includes a list of additional inputs required from the seller for purchasing 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 all required seller inputs are collected and prepared, proceed to call the createShipment operation.
2. Pass the necessary parameters, including the seller inputs, to the createShipment operation.
3. Follow the appropriate syntax requirements for the seller inputs as mentioned in the getAdditionalSellerInputs response.

Step 6: (Optional) Retrieve saved values

The getAdditionalSellerInputs operation also returns saved values that you previously provided to Amazon. If you need to access these saved values, examine the response from the getAdditionalSellerInputs operation.

Tutorial 5: Subscribe to MFN Notifications

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

🚧

Use the new ORDER_CHANGE notification

The MFN_ORDER_STATUS_CHANGE and the ORDER_STATUS_CHANGE notification types have been deprecated. Please update your applications to use the new ORDER_CHANGE notification. This new notification 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 more detailed information about SP-API deprecation dates, refer to the Deprecations table.
Sellers can subscribe to this ORDER_CHANGE notification, which is sent whenever there is a change to the status of order availability.

Step 1. Subscribe to the ORDER_CHANGE Notification

Follow the Notifications API SQS Tutorial to set up and subscribe to the ORDER_CHANGE notification.
Below is a figure that illustrates the high level steps of the tutorial.

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

1. Retrieve the queue URL: Once connected to the SQS service, retrieve the URL of the queue where the ORDER_CHANGE messages are being sent. This URL uniquely identifies the queue and will be used to interact with it.
2. Configure polling parameters: Decide on some polling parameters to determine how frequently and how many messages to fetch at a time. This includes specifying the wait time between subsequent polling attempts, the maximum number of messages to retrieve in each request, and other relevant parameters.
3. Poll the queue: Start polling the queue by sending requests to retrieve messages. Use the ReceiveMessage API provided by SQS to fetch the messages from the queue. When calling this API, you can specify the queue URL, maximum number of messages to retrieve, and other optional parameters such as visibility timeout.

Alternatively, you can configure an 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: Once you receive the messages, you can process each message 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, timestamps, and any other pertinent data.
5. Delete processed messages: After successfully processing each message, make sure to delete it from the queue using the DeleteMessage API provided by SQS. This step ensures that the processed messages are removed from the queue and won't be fetched 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 which attributes can be returned, refer to ORDER_CHANGE notifications.

To automate the fulfillment process, you will need to:

• Check notification messages that have an OrderStatus of UpComing, Pending or Unshipped and check that MFN is within the FulfillmentChannel attribute.
• Fetch Order and Shipping information through the getOrder operation.
• Pass this information to the getEligibileShipmentServices operation and follow the steps in Tutorial 1.

Error codes

The following table describes the various error codes that the Merchant Fulfillment service can return.