Terminology

• SP-API: Selling Partner API

• EF-API: External Fulfilment API (also referred as SmartConnect API)

• Location Id: Amazon location identifier

1. What is the External Fulfilment API?

   The external fulfilment API (also known as SmartConnect API) enables selling partners to fetch customer orders across multiple fulfilment programs (Eg. Seller Flex, Easy Ship, Pharmacy, MLF) and process them using a standard set of APIs.
   Additionally, selling partner can also manage their inventory updates and reconcile their returns using same set of APIs.
   SmartConnect offer 3 APIs –
   a) Inventory APIs – to update inventory;
   b) Shipment API – to fetch customer orders and process them; and
   c) Returns API – to get return details.
   These are Synchronous and Rest APIs. Currently SmartConnect supports 8 different fulfilment programs within Amazon.

2. How to identify Program (Easy Ship/Self Ship/Seller Flex) in External Fulfilment APIs?

   Sellers can identify program in getShipments or getShipment API with combination of below attributes:

   
   

   API	Attribute	Value	Program
   getShipments/getShipment	channelName	MFN	Easy Ship
   	shippingType	Marketplace
   	channelName	MFN	Self-Ship
   	shippingType	Self
   	channelName	FBA	Seller Flex
   	shippingType	Marketplace

   
   

3. Understanding shipment processing workflow

   
   

   1. Shipment processing Workflow: All selling partners working with external fulfilment APIs are expected to adhere to a workflow for processing a shipment. This workflow steps and the corresponding API operations are documented below. The workflow is illustrated below:

      
      

      Key: Each rounded rectangle in the workflow indicates a wait state in the workflow, while each arrow indicates an API call that triggers some change in the workflow.

   2. Workflow Steps: A brief overview of the various steps of the workflow are given below. Note: These workflow steps are needed to process shipment via APIs. However, selling partners may need additional steps in on ground operations (Inbounding, order Picking, Manifest etc). These steps are not in scope of APIs operations.

      1. Get shipments – Client gets a list of all the shipment for a location.

      2. Process Shipment - Client confirm or reject fulfilment of the shipment. Currently partial confirmation of the shipment is not supported.

      3. Create Packages - Client provides details about the packages that will be used for fulfilling the shipment. This includes any required information such as dimensions, weights, IMEI/serial number, Hazmat label details, etc.

      4. Retrieve Shipping Options - Clients invoke this API to retrieve a list of shipping Options that marketplace/channel provides for the pickup of the package.
         This API will return a list of shipping options and allows the seller to choose from the list. The API returns empty successful response, If the marketplace/channel does not allow for a shipping option to be selected. Eg. For FBA Onsite, Seller Flex and Multi Seller Flex orders, it returns an empty response as the pickup is performed at a pre-determined slot.

      5. Generate Invoice - Client invoke this API to generate and retrieve the Invoice/P-Slip or both (as applicable) for a shipment. The API will return the invoice as a file that can be printed. If the marketplace doesn’t support generating a tax invoice, only packing-slip will be returned. This API is not supported for Easy Ship channel in WW marketplaces (except IN marketplace) [Supported format is PDF.].

      6. Update Package - After generating the invoice, it is possible that the selling partners may need to change some information about the packed items such as the IMEI serial number or package dimensions. They can invoke this API for the same.

      7. Generate Ship Labels - Client invoke this API to generate and retrieve the ship-label from the transportation carrier. The API will return the ship-label as a file that can be printed. [Supported formats are PNG and ZPL].

      8. Update Package Status - Once the shipment has been physically handed over to carrier, callers invoke this API indicate that the shipment has been successfully shipped.

         
         

         This completes the shipment workflow and the shipment is now in closed state.

1. Shipment Statuses: Every shipment has a status associated with it. The status of the shipment indicates the step in the workflow that the shipment is in. Below is a description of each of these status values.

   
   

   1. CREATED – This status indicated the order is created in Amazon SmartConnect

   2. ACCEPTED - Based on the inventory availability in Amazon SmartConnect of all the SKUs in a particular shipment, the Amazon Yojaka system will mark a shipment in this status for further processing by the connector application.

   3. UNFULFILLABLE - If inventory is unavailable in Smart Connect and was updated via some other system then order drops to smart connect will be marked Unfulfillable. Applicable only for MFN channels.

   4. CONFIRMED - This status indicates that the connector has confirmed a shipment by invoking the process-shipment API.

   5. PACKAGE_CREATED - This status indicates that the connector has provided the package information to the Amazon Yojaka product by invoking the create-packages API.

   6. PICKUP_SLOT_RETRIEVED - A shipment will be in this status once the connector has invoked the retrieve-Shipping-Options API for a shipment.

   7. INVOICE_GENERATED - This status indicates that the connector has invoked the generate-invoice API for the shipment.

   8. SHIPLABEL_GENERATED - Once the connector invokes the generate-ship-label API for a shipment, the shipment will be in this status.

   9. SHIPPED - This status indicates that the shipment has been shipped to carrier (client updates the package status manually status update by invoking update-package-status API or via logistics scan events#). This is a terminal status in the shipment processing workflow.

   10. DELIVERED - This status indicates that the shipment is delivered to the customer.

   11. CANCELLED - This status indicates the shipment has been cancelled either by the connector or by the marketplace. This is a terminal status.

2. API Call flow: Below is an Ideal API operation sequence to successfully process shipments -

1. Tutorial 1: Getting list of shipments for various statuses

   This tutorial shows you how to get the list of shipments for any status. This is the first API operation to begin order processing for any seller.

   1. Retrieve All shipments (getShipments API)

      Call the getShipments API to fetch list of all shipments for processing (or checking current shipment status), following the below steps. The API response will provide order metadata containing details required for order processing.

      
      

      Usage Plan:

      Rate (requests per second) : 1

Query Parameters:

Request Example

Note: shipmentId is the key id for seller facing processes, identified as “id” in below API response. A single customer order can be split into several shipments and assigned to different seller/locations.

Response Sample:

1. Retrieve Single shipment detail (getShipment API)

Invoke the getShipment API to fetch details of a specified shipment for order processing.

Usage Plan:

Parameters

Path parameters

Request example

Response Sample:

1. Tutorial 2: Processing a shipment using external fulfilment shipments API

This tutorial shows you how to process a shipment using the external fulfilment shipments API.

1. Prerequisites

   To successfully complete this tutorial, you must have:

   1. Authorization from the selling partner for whom you are making calls. See the Selling Partner API Developer Guide for more information.

   2. You have the shipmentId (s) to be processed

      
      

2. Steps

   • Step 1. Acknowledge the shipment

   • Step 2. Create packages for the shipment

   • Step 3. Get the shipping options for the shipment

   • Step 4. Generate the invoice for the shipment

   • Step 5: [Optional] Update Package

   • Step 6. Generate and retrieve the shipLabel for the shipment

   • Step 7: [Optional] Update Package status

   
   

   Step 1. Acknowledge the shipment

   Call the processShipment API to confirm the shipment which is to be processed by passing the following path, query and header parameters: Note - Key ID is shipmentId which is from previous section (getShipment API)

   Usage Plan:

   Rate (requests per second) : 1

Path parameters

Header parameters

Query parameters

Body parameters

body - The request schema for the reject shipment line items.

Request example

Response example

Step 2 - Create packages for the shipment

Create packages for the shipment which is to be processed by passing the following path, header and body parameters in the createPackages API. Client to provide details about the packages that will be used for fulfilling the order. Callers provide any required information such as dimensions, weights, IMEI/serial number, Hazmat label details, etc.

Key ID is shipmentId obtained in first section. Seller can create package with their own defined box dimension (seller can have predefined list in their code), or with the recommended box dimensions (which is based on catalog dimension) as part of getShipment API response.

Usage Plan:

Path parameters

Header parameters

Body parameters: Refer to API documentation for Body Parameters.

Request example

Request Body Sample

Response example

Step 3. Get the shipping options for the shipment

Call the retrieveShippingOptions API for the shipment which is to be processed by passing the path, query and header parameters provided below. Clients invoke this API next to retrieve a list of shipping Options that marketplace/channel provides for the pickup of the package of a shipment. This API will return a list of shippingOptions, if the marketplace/channel provides transportation and allows the seller to choose a shippingOption. For Seller Flex channel, it is No-Op call (200 null response).

Usage Plan:

Query parameters

Header parameters

Request example

Response example:

Step 4. Generate and retrieve the invoice for the shipment

Callers invoke generateInvoice API to generate the invoice for the order. The API will return the invoice as encoded base64 text that can be decoded and converted to PDF for printing. Once the invoice has been generated successfully for a shipment/order, Callers can also invoke retriveInvoice API with same parameters as generateInvoice to retrieve previously generated invoice. This API is not supported for Easy Ship channel in WW marketplaces (except IN marketplace)

Usage Plan:

Path parameters

Header parameters

Request example (for both generate and retrieve invoice)

Response Schema: (for both generate and retrieve invoice)

Response Sample:

Step 4.1 Steps to convert the base64 invoice contents to PDF

Step 1: Retrieve the base64 encoded invoice using generateInvoice/retrieveInvoice APIs.
Step 2: Decode the bae64 encoded string to text.

Step 3: Convert base64 text received in step 2 to PDF.

Step 5: Update Package [Optional]

After generating the invoice, it is possible that the selling partners need to change some information about the packed items such as the IMEI serial number or package dimensions. Callers invoke updatePackage (Optional) API for the same, the operations move the order status to “PACKAGE_CREATED” status. Call this API with the following parameters to update the details about the packages that will be used to fulfill the specified shipment.

Usage Plan:

Path parameters

Header parameters

Body parameters: Refer to API documentation for Body Parameters.

Request example

Request Body Sample

Response example

Step 6. Generate the ship labels for the shipment

Callers invoke generateShipLabels API to generate and retrieve the ship-label for package(s) of an order from the transportation carrier. For Easy Ship channel, callers can invoke this API to regenerate and retrieve the ship-label from the transportation carrier as well. This is done to reschedule the pick-up slot for an Easy ship order.

Note: Once the ship label has been generated successfully for an Easy Ship and Seller Flex shipment, Callers can again invoke this API call to retrieve previously generated ship label. (e.g., In case of print failure, storage issue etc.)

Usage Plan:

Path parameters

Query parameters

Header parameters

Body parameters

Query parameters

Request example

Request Body Sample

Response Sample (for both generate and retrieve Ship Label):

Step 7: Update Package Status

Once the order has been shipped, client needs to invoke updatePackageStatus API to indicate that the order has been shipped.

Usage Plan:

Header parameters

Path Parameters:

Query parameters

Request example

Response example