amazon services Europe Merchant Fulfilment API Seller Fulfilled Prime Developer Guide

Developer Guide

This document aims to guide the developers to implement the Merchant Fulfilment API and Seller Fulfilled Prime program. It provides the necessary links to documentations, prerequisites, implementation steps, test scenarios and notes to be considered. The implementation steps explain WHAT to do rather than HOW. The developer should understand his system flow and structure in order to decide the HOW.

**1. Merchant Fulfilment API

**

This feature allows you to automatically buy a shipping service from Amazon partnered carriers via API. You can:
• Choose a third-party carrier from the available options that comply with your requirements (Delivery date, Pickup, etc.).
• Pay for delivery and related services conveniently through API.
• Print delivery labels using your standard printer.

**1.1 Prerequisites

**

In order to use the Merchant Fulfilment API, you should:
• Have a technical resource to make the necessary development of the new feature
• Be registered to Merchant Web Services in the target marketplace using a professional Seller account: UK – DE
• Carefully review and agree to the Amazon contractual terms and conditions for participation in the Merchant Shipping Services program, as well as the carrier terms and conditions
• Read and understand the charges conditions

**1.2 API Documentation

**

The Merchant Fulfilment API documentation is accessible along with other Amazon MWS API documentation. It provides explanations of the process, inputs, and responses of each method, data types description, and error codes explanation.
Amazon MWS Scratchpad (UK – DE) can be a helpful tool for your development. It automatically generates and displays the inputs that are required in a query request to Amazon MWS, you can see how these inputs look when they are correctly formed. Examining the Amazon MWS responses that Amazon MWS Scratchpad displays for each of your query requests can help you build successful parsing logic. You can also download the Client library for PHP, C# and Java.

1.3 Workflow

The following steps assume a full automation of the process. In a fully automated implementation, the following steps should take around ten seconds from the time the order is received until the label is printed. The manual steps to buy a shipping label on Seller Central take approximately four minutes per order.
Step 1: Retrieve periodically the new orders
If you are already automating the orders management, then this step should be already implemented. It consists of retrieving automatically and periodically (every hour for example) the new orders. The best practise is to use the order report:
1. Schedule the order report:
a. Connect to the Seller Central account
b. From the menu, select Orders >> Order Reports
c. Click on Edit in the ‘Scheduled Order Report Settings’ section
d. Select the order periodicity and click on Submit
2. Schedule the API method GetReportList to be submitted in an interval that is similar to the schedule that you configured in Step 1. Ensure that the Acknowledged parameter is set to false. This step determines whether any new order reports have been created.
3. Capture any ReportId values that are returned by the GetReportList method. No ReportId values will be returned if no new order reports have been created since the last scheduled GetReportList request.
4. For each ReportId value that is returned, call the GetReport method, specifying the ReportId value. Amazon MWS returns the report.
5. Acknowledge the receipt of the report using the UpdateReportAcknowledgements method. Do this after downloading your report to ensure that the report is not downloaded the next time you call the GetReportList method (see Step 2).
Step 2: Select the shipping service offer for the orders
For each order retrieved:
1. Determine whether or not a shipping service needs to be created. For example, when the order is Prime or when the Order Fulfilment service level is next day, and so on.
2. Call the API method GetEligibleShippingServices  to retrieve a list of shipping service offers that satisfies the shipment request details that you specify.
3. Select the best shipping service based on your preferred criteria. For example, a preferred carrier, lowest price, with pick-up options, etc.
4. Save the S hippingServiceId  and the  ShippingServiceOfferId ** of your selected shipping service offer.
Step 3: Create the shipment
1. Call the API method CreateShipment to purchase the shipping service. You send the same parameters as for GetEligibleShippingServices , the  ShippingServiceId,  and the  ShippingServiceOfferId from previous step.
The  CreatShipment** method triggers the service payment. Charges for delivery of related services as calculated by the carrier are deducted from your Seller account. Carriers are not given access to your credit card information when you buy delivery services. Potential error code to be handled: InsufficientFunds
2. The CreateShipment method returns the details of the shipment, including the shipment status and tracking ID. Save this data in your database.
3. The CreateShipment method also returns the shipping label file in PNG or PDF format. Amazon compresses the document data before returning it as a Base64-encoded string. To obtain the actual PNG or PDF document:
a. Decode the Base64-encoded string
b. Save it as a binary file with a “.gzip” extension
c. Extract the PNG or PDF file from the GZIP file. You can use the GZIP decompression functionality included in most programming languages.
This operation also returns a Base64-encoded MD5 hash to validate the document data.
4. Print the shipping label on your standard printer.

**1.4 Other Operations

**

**1.4.1 Reprinting a label

**

To reprint a delivery label use the GetShipment method. It returns an existing shipment details for a given identifier including the label.

**1.4.2 Cancel a shipment

**

To cancel a shipment use the CancelShipment method. It cancels an existing shipment and requests a refund for the ShipmentId value that you specify. Canceling a shipment only succeeds if the cancellation window has not expired and if the shipment has not previously been canceled. Cancellation policies vary by carrier, please check them on their websites. Potential error code: LabelCancelWindowExpired.
Shipment created with AMZL or DPD cannot be cancelled or refunded through APIThe ShipmentId is only provided when you request the shipping service offers or create a shipment. There is no method available on the API to obtain it for a previously created shipment. You have to store the ShipmentId in your database once you have created the shipping. A new API method to list the merchant shipments will be added to the API in next releases.

**1.4.3 Print multiple labels

**

The Merchant fulfillment API doesn’t have a specific method to print labels in bulk. Sellers who want to print labels in bulk should adapt their implementation using existing methods. The best practice for bulk printing is to save the shipping label locally and add a feature to print saved labels. Downloading the label using  GetShipment  method while printing in bulk will slow down the printing process.

**1.4.4 Settlement report

**

The Settlement report will display a new Transaction type ‘Delivery labels purchased through Amazon’. Make sure that this transaction is captured by your system in order to display a correct balance.

**1.4.5 Order Confirmation

**

Orders shipped using Merchant Fulfilment API are auto-confirmed. When you call the CreateShipment method, the customer receives automatically an order confirmation. Only orders shipped by AMZL are confirmed to the customer when the label is scanned by the carrier.
Your system doesn’t have to send a shipping confirmation feed for those orders

**1.5 Test Scenarios

**

The below table lists the tests that should be considered when implementing the Merchant Fulfilment API. The steps of each test scenario depend on the interface that you built to implement this feature.

Test ID

|

Test Scenario

|

Expected Result

---|---|---

BS-1

|

Getting offers

|

List of offers for each carrier

BS-2

|

Create a shipment

|

Shipment details
Label downloaded and printed
Seller’s balance charged

BS-3

|

Cancelling a shipment

|

Shipment Cancelled
Refund triggered

BS-5

|

Re-download the label

|

Label downloaded

BS-6

|

Settlement Report Handling

|

New transaction is appearing

BS-7

|

Print multiple labels

|

Labels printed without delay

**2 Seller Fulfilled Prime

**

Seller Fulfilled Prime allows Sellers to list products with the Prime badge. Sellers who have proven their ability to meet Prime Customers’ expectations for service are now able to enroll in Seller Fulfilled Prime. Sellers who are approved and enroll items in Seller Fulfilled Prime need to:
• Provide Prime shipping benefits to Amazon Prime members on the SKUs that they enrolled into the program.
• Offer Free Standard Shipping for all Prime items.
• Purchase shipping labels for orders containing a Prime item through Amazon’s Merchant Fulfillment Service.
• Agree to all shipping, returns and Customer service requirements applicable to Prime items.

**2.1 Prerequisites

**

• Have a technical resource to make the necessary development of the new feature
• Be registered to the Merchant Web Services in the target marketplace: UK – DE
• Fulfil Eligibility for Seller Fulfilled Prime (Details)
• Fulfil Program Requirements (Details)
• Applied for Seller Fulfilled prime and agreed on terms and conditions (UK – DE)
• Use the Amazon Merchant Fulfilment service to deliver Prime orders

**2.2 Workflow

**

Step 1: Create a Prime shipping template
1. In your Seller Central account go to Settings >> Shipping Settings
2. If you are using the old shipping model then migrate to the new shipping model by clicking on “Migrate Now” to begin the process. Following this migration you will not be able to send override feeds on this Seller account.
3. After migrating, create a Prime-enabled shipping template. To do this, click on “Create New Template” on your shipping settings page. On the new template, click the checkbox marked “Prime settings” and then click the button labelled “Add New Prime Regions”. You should enable Prime for any regions where you would like Prime badging to display.
4. You can apply changes to the shipping template, but make sure that those changes stay compliant with the program requirement
Step 2: Assign the shipping template to the Prime products in your catalogue
You can skip the following steps 1 and 2 if you already use shipping templates in your feeds.
1. For Flat File product feed:
a. Download the latest product template. It has a new column labelled ‘merchant_shipping_group_name’
b. Use this column to set the shipping template name for a specific SKU
2. For XML product fees:
a. Download the latest product XSD. It has a new element labelled