API Version: v0
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.
|Shipping service||A carrier’s shipping service, such as “UPS Ground” or “FedEx Standard Overnight”. Identified with a |
|Shipping service offer||A shipping service offer made by a carrier. It is represented by the |
|Package||A parcel to be shipped by a carrier. A package includes metadata such as dimensions, weight, and item contents.|
|Shipment||A package and a shipping label. It is identified with a |
|Additional seller inputs||Additional seller-provided information that is required to purchase certain shipping services. You can call the |
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.
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
latest-ship-date fieldsfor flat file order reports.
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
Do not use the
FulfillmentServiceLevel attribute or the
ship-service-level column in order reports to identify Prime orders.
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.
Check the inventory number and make sure that the received order is ready to be fulfilled.
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
ShipDateparameter, use the
LatestShipDateattribute from Orders API or the
latest-ship-datevalue from the order report.
- Do not specify the
MustArriveByDateparameter, as this will unnecessarily limit the number of shipping service offers that are returned.
- Save the
ShippingServiceIdvalue from each shipping service offer that is returned. You will use this for subsequent calls to the
createShipmentoperation when creating shipments for specific shipping service offers.
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
getEligibleShipmentServicesoperation in the previous step.
ShippingServiceId: Use the value associated with this shipping service offer.
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
ShipmentIdvalue returned by the
createShipmentoperation. If the seller wants to print a new label, cancel a shipment, or check shipment status at a later time, the
ShipmentIdis used to identify the shipment. Save the item list along with each shipment ID.
For more details, refer to Tutorial 3: Manipulating shipping labels.
Repeat Steps 3 through 5 until you have created shipments for all the orders identified in Step 1.
This tutorial shows you how to add functionality to the workflow described in How to fulfill Seller Fulfilled Prime orders.
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
- Call the
getShipmentoperation, specifying the
ShipmentIdvalue of the canceled shipment.
- Get the cancellation status from the status element returned by the
The service returns the LabelCancelWindowExpired error if the window for canceling a label has expired. Refer to Error codes.
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.
- Decode the Base64-encoded string.
- Save the decoded string with a “.gzip” extension.
- Extract the PDF, PNG, or ZPL file from the GZIP file.
- Call the
getShipmentoperation, specifying the
ShipmentIdvalue of the shipment for which you want to reprint the shipping label.
- Extract and print the shipping label from the
FileContentselement returned by 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.
- Call the
- Retrieve the list of
ShippingServicesreturned by the operation.
- Check for the
RequiresAdditionalSellerInputsis true, it means the shipment service requires additional seller inputs.
- If the shipment service requires additional seller inputs, call the
- Provide the necessary parameters required by the operation.
- Receive a response that includes a list of additional inputs required from the seller for purchasing shipping services.
- Examine the response from the
- Identify the specific additional seller inputs that are required.
- Collect the necessary information based on the additional seller inputs identified in the response.
- Ensure the information provided meets the syntax requirements specified in the response.
- Prepare the required seller inputs for the next step.
- If all required seller inputs are collected and prepared, proceed to call the
- Pass the necessary parameters, including the seller inputs, to the
- Follow the appropriate syntax requirements for the seller inputs as mentioned in 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
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_STATUS_CHANGEnotification types have been deprecated. Please update your applications to use the new
ORDER_CHANGEnotification. 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_CHANGEnotification, which is sent whenever there is a change to the status of order availability.
Follow the Notifications API SQS Tutorial to set up and subscribe to the
Below is a figure that illustrates the high level steps of the tutorial.
- Retrieve the queue URL: Once connected to the SQS service, retrieve the URL of the queue where the
ORDER_CHANGEmessages are being sent. This URL uniquely identifies the queue and will be used to interact with it.
- 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.
- Poll the queue: Start polling the queue by sending requests to retrieve messages. Use the
ReceiveMessageAPI 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.
- 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 messagesfrom the SP-API, you can extract the relevant information such as the order ID, status change details, timestamps, and any other pertinent data.
- Delete processed messages: After successfully processing each message, make sure to delete it from the queue using the
DeleteMessageAPI 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.
ORDER_CHANGE notification returns high level information related to the order, such as the
OrderItemId and the
OrderStatus. To learn more about which attributes can be returned, refer to
To automate the fulfillment process, you will need to:
- Check notification messages that have an
Unshippedand check that
MFNis within the
- Fetch Order and Shipping information through the
- Pass this information to the
getEligibileShipmentServicesoperation and follow the steps in Tutorial 1.
The following table describes the various error codes that the Merchant Fulfillment service can return.
|Error Code||HTTP Status Code||Description|
|400||The requested shipping label purchase was rejected because of insufficient funds in the seller’s account.|
|400||Request has missing or invalid parameters and cannot be parsed.|
|400||The specified |
|400||The specified |
|400||The cancellation window for requesting a label refund has expired. Cancellation policies vary by carrier. For more information about carrier cancellation policies, refer to the Seller Central Help Hub.|
|400||The requested LabelFormat does not match the available formats.|
|400||One or more items specified in a call to the |
|400||The specified |
|400||The specified |
|404||The request cannot be applied to the shipment in its current state. For example, a shipment in the |
|404||Items specified in a call to the |
|404||The specified order is from a marketplace where the Merchant Fulfillment service is not supported.|
|404||The resource specified (such as |
|404||The shipping service specified does not exist or is not available for the specified parameters (for example, Weight).|
Updated 16 days ago