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 ordersIf 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 accountb. From the menu, select Orders >> Order Reportsc. Click on Edit in the ‘Scheduled Order Report Settings’ sectiond. Select the order periodicity and click on Submit2. 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 ordersFor 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 ShippingServiceId and the ShippingServiceOfferId of your selected shipping service offer.Step 3: Create the shipment1. 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: InsufficientFunds2. 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 stringb. Save it as a binary file with a “.gzip” extensionc. 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.

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 template1. In your Seller Central account go to Settings >> Shipping Settings2. 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 requirementStep 2: Assign the shipping template to the Prime products in your catalogueYou 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 SKU2. For XML product fees:a. Download the latest product XSD. It has a new element labelled <MerchantShippingGroupName>b. Use this element to set the shipping template name for a specific SKU3. Associate the Prime shipping template to all products that you wish to sell as prime by uploading the feed with the template information4. Download the feed report and make sure that your feed is successfully processedNote: Make sure that future product feeds do not overwrite the shipping template association.Step 3: Manage your orders with Prime productsDefinition: Order Cut-off Time: it is the time by which buyers must place an order to meet the one-day delivery promise. The default order cut-off time is 1:00 pm local time for buyers to place an order that will arrive in one business day. All Seller Fulfilled Prime orders must be shipped on the same day that the order is received as long as the buyer places the order before your cut-off time. All orders that arrive in your Seller system by 2:00 pm local time must be shipped on the same day. For orders that are delayed in fraud check and arrive in your system after 2:00 pm local time the Customer will be promised an updated guaranteed delivery date. If you would like to set a later cut-off time, send an email following this template:To: [email protected]  Subject: SELLER XYZ – NEW CUT-OFF TIMEBody:Hi Seller-fulfilled Prime team,I’d like to change my order cutoff time to the following:Seller Name: Seller XYZNew Order Arrives in Seller’s System Cut-off Time: 4:00 pm GMTCarrier with the Latest Expedited Pickup: Royal MailLast Carrier Pickup Time: 6:30 pm GMTYour last expedited carrier pick up must be at least 2 hours after the order cut-off time you choose and the cutoff time must be in 30-minute increments (e.g. the cut-off time can be 4:00 pm or 4:30 pm, but not 4:15 pm). The new cut-off time will take effect within five business days and you will be notified when the change is effective.1. Request New orders report. This step should already be implemented if you have automated your order management.2. Check whether the order is Prime. Seller-fulfilled Prime orders can be identified via the “IsPrime” column that has been added to the “Order Reports” and the “GetOrders” methods.DO NOT use the ‘FulfillmentServiceLevel’ or ‘Ship-Service-Level’ to  identify Prime ordersAll Prime orders should be shipped using the Merchant Fulfilment API3. Use the Merchant Fulfilment API to get shipping offers and buy the shipping label. It is mandatory to use DPD carrier for Prime orders in DE and to use AMZL carrier for Prime orders in UK if the shipping address is covered by AMZL, otherwise use another carrier.Use DPD carrier for Prime orders in DE Use AMZL carrier for Prime orders in UK if the shipping address is coveredNote: To receive the Prime carriers (DPD and AMZL), you should use the following Shipping Services options:ShippingServiceOptions.DeliveryExperience = DeliveryConfirmationWithoutSignature ShippingServiceOptions.CarrierWillPickUp = trueIn case you are not receiving any carriers when calling GetEligibleShippingServices or missing Prime carriers, please check the following:1. Check the Services options2. Check that T&C are accepted for all carriers.3. Check that Seller Central returns same eligible Sellers for this order4. Check the weight and dimension (Only Integer values – Maximum dimension/weight)5. Check the Must Arrive by date

2.3 Test Scenarios

The below table lists the tests that should be considered when implementing the Seller Fulfilled Prime. The steps of each test scenario depends on the interface that you built to implement this feature.

Where can I find Test Orders / Accounts for the API integration?FAQ

Amazon does not provide test environments/accounts. We recommend that you activate an offer as Prime and place a real order to test the API.Integrators accounts could be whitelisted for a short time to allow them test the reception of Prime orders.Would I get charged for printing a test label?Your account gets charged when you print a label. You can however cancel a label and get refunded.How do I get whitelisted for using the API? / I am getting error ‘Terms & Conditions Not Accepted’?Seller needs to agree on the terms and conditions for Shipping Services before using the API.How do I identify a Prime Order?The Amazon Marketplace Web Service Orders API and Orders Report XML returns the ‘IsPrime’ response to indicate the Prime orders. You need to be whitelisted into the Prime program for this flag to be returned in your Orders Report XML.Note: Please do not use the ‘FulfillmentServiceLevel’ or ‘Ship-Service-Level’ column in XML to identify Prime orders.Can I create multiple shipments for the same order?Yes. You can create more than one shipping label for one order, but not for the same product. Products of the same kind always need to be shipped together.My shipping is composed of many boxes. Can I download many labels for the same shipping?The API allows to download only 1 label per shipping. If a single product is shipped on multiple boxes then you should remove this product from your Prime offers.Can I create directly a shipment without calling GetEligibleShippingServices?If you know which shipping services you want to use then you can call the CreateShipment without specifying the ShippingServiceOfferId.How do I know whether an area is covered by AMZL?When you request the shipping services offers by calling GetEligibleShippingServices, Amazon will check the shipping address. If the area is covered by AMZL, then you will see AMZL among the available services, otherwise, you will get only other carriers’ services offers.I cancelled my label but the order still shows as shipped.Once an order has been marked as shipped, the ‘order’ remains in a ‘shipped’ state even if you cancel the label / shipment. However, you can cancel a shipment and re-purchase a label against the same order any number of times using Seller Central UI.Can I create new shipments after canceling existing shipments using the API?These are conditions where you can create new shipments after canceling existing shipments:• If only a single shipment was created to fulfill an order, you can cancel the shipment and then create a new shipment for that order using the CancelShipment operation.• If multiple shipments were created to fulfill an order, you can cancel the shipments, but cannot create new shipments using the Merchant Fulfillment API section. You will need to either create new shipments in Seller Central or arrange for shipping by contacting a carrier directly.How do we confirm shipments purchased through this API?All Shipments purchased through this API are auto-confirmed. You don’t need to separately confirm the same.

amazon services Europe Merchant Fulfilment API Seller Fulfilled Prime Developer Guide – amazon services Europe Merchant Fulfilment API Seller Fulfilled Prime Developer Guide –