Common challenges and best practices
In this section, we highlight some of the common challenges that developers face when creating MCF connector integrations, and explain some of the best practices that can help you overcome these challenges.
Getting order status updates
Common challenge: Developers sometimes have difficulty reading notifications for all order status updates.
Best practice: Use one of the following two methods to fetch order status updates:
1. Call the API: Regularly call the getOrder API for order status updates until a terminal status [Complete, CompletePartialled, Canceled, Unfulfillable] is achieved on the order. Tracking details are shared in the response when its available which could be during Processing, Complete, and PartiallyComplete status.
2. Subscribe to notifications: By subscribing to notifications and listening to the event FULFILLMENT_ORDER_STATUS. Every time there is change on the order status or a tracking number is generated, a notification is emitted that needs to be read from an SQS queue.
API calling is a pull mechanism and developers might not be aware of the frequency of API calling. The suggested practice is to read notifications and only call the getOrder API for full order details after the order is completed.
By following this approach, you can:
• Reduce the bandwidth required to call APIs frequently.
• Gain awareness of early tracking details.
• Get real-time notifications, as API calls may come with delays.
• Get notifications of updates to tracking numbers, if any.
Best practice: Use one of the following two methods to fetch order status updates:
1. Call the API: Regularly call the getOrder API for order status updates until a terminal status [Complete, CompletePartialled, Canceled, Unfulfillable] is achieved on the order. Tracking details are shared in the response when its available which could be during Processing, Complete, and PartiallyComplete status.
2. Subscribe to notifications: By subscribing to notifications and listening to the event FULFILLMENT_ORDER_STATUS. Every time there is change on the order status or a tracking number is generated, a notification is emitted that needs to be read from an SQS queue.
API calling is a pull mechanism and developers might not be aware of the frequency of API calling. The suggested practice is to read notifications and only call the getOrder API for full order details after the order is completed.
By following this approach, you can:
• Reduce the bandwidth required to call APIs frequently.
• Gain awareness of early tracking details.
• Get real-time notifications, as API calls may come with delays.
• Get notifications of updates to tracking numbers, if any.
Syncing inventory
Common challenge: Developers misread the inventory value in the inventory message or don’t know how to properly sync inventory, which can lead to overselling and stockouts or excess inventory.
Best practice: We recommend subscribing to FBA_INVENTORY_AVAILABILITY_CHANGES notification type, which enables real-time sync with Amazon Inventory and reflects any inventory changes. To avoid any missed notification, developers should call getInventorySummaries API once a day for a complete snapshot of inventory levels.
Calling the getInventorySummaries API more than once a day can lead to stale data between API calls and isn’t recommended.
For developers that only use API, we suggest:
• Maintaining your own internal record of inventory, based on orders placed and canceled. Then you can overwrite that record during the inventory sync process, which can be done once or twice a day.
• Operate with some safety stock settings, so that there is no overselling between inventory sync jobs.
If interested in IN-HAND only inventory (located in Amazon fulfillment centers), in the response developers should track for inventorySummaries.Fulfillable.
For developers interested in accounting for the items that are IN-TRANSIT/INBOUND, do the sum of: [inventoryDetails.Fulfillable + inventoryDetails.inboundWorkingQuantity+inventoryDetails.inboundShippedQuantity+inventoryDetails.inboundReceivingQuantity].
Note: IN-TRANSIT/INBOUND inventory might have longer estimated arrival date than in-hand inventory.
Best practice: We recommend subscribing to FBA_INVENTORY_AVAILABILITY_CHANGES notification type, which enables real-time sync with Amazon Inventory and reflects any inventory changes. To avoid any missed notification, developers should call getInventorySummaries API once a day for a complete snapshot of inventory levels.
Calling the getInventorySummaries API more than once a day can lead to stale data between API calls and isn’t recommended.
For developers that only use API, we suggest:
• Maintaining your own internal record of inventory, based on orders placed and canceled. Then you can overwrite that record during the inventory sync process, which can be done once or twice a day.
• Operate with some safety stock settings, so that there is no overselling between inventory sync jobs.
If interested in IN-HAND only inventory (located in Amazon fulfillment centers), in the response developers should track for inventorySummaries.Fulfillable.
For developers interested in accounting for the items that are IN-TRANSIT/INBOUND, do the sum of: [inventoryDetails.Fulfillable + inventoryDetails.inboundWorkingQuantity+inventoryDetails.inboundShippedQuantity+inventoryDetails.inboundReceivingQuantity].
Note: IN-TRANSIT/INBOUND inventory might have longer estimated arrival date than in-hand inventory.
Accessing early tracking information
Common challenge: Tracking numbers are now available without the order being Shipment Complete.
Best Practice: For developers calling the getOrder API, don’t assume that tracking details are only available when the order is in Complete or CompletePartialled status. Tracking details will now be available when the order is in the Processing stage.
For developers listening to order notifications, a notification is explicitly emitted with early tracking details with the order status as Processing, which has the carrier, package number, and tracking number.
Often developers calling getOrder API mark their order Fulfilled after consuming tracking details, but there could always be updates to tracking details when Re-SLAMs(modifications) happen at a fulfillment center. If you mark the orders as Fulfilled, you will not be aware of any updates and will have invalid tracking details.
Be sure to read FULFILLMENT_ORDER_STATUS notifications, which send an event for early tracking details and also for any updates to tracking details, if any. This approach will ensure sellers always have the correct tracking details on orders.
Best Practice: For developers calling the getOrder API, don’t assume that tracking details are only available when the order is in Complete or CompletePartialled status. Tracking details will now be available when the order is in the Processing stage.
For developers listening to order notifications, a notification is explicitly emitted with early tracking details with the order status as Processing, which has the carrier, package number, and tracking number.
Often developers calling getOrder API mark their order Fulfilled after consuming tracking details, but there could always be updates to tracking details when Re-SLAMs(modifications) happen at a fulfillment center. If you mark the orders as Fulfilled, you will not be aware of any updates and will have invalid tracking details.
Be sure to read FULFILLMENT_ORDER_STATUS notifications, which send an event for early tracking details and also for any updates to tracking details, if any. This approach will ensure sellers always have the correct tracking details on orders.
Using unbranded packaging (Blank Box) and Block Amazon Logistics features
Common challenge: Developers don’t know how to configure the unbranded packaging and Block Amazon Logistics features.
Best practice: MCF delivers most orders in unbranded packaging within the US region, but some sellers might have requirements that all orders be delivered in unbranded packages.
Unbranded packages (Blank Box or BB):
1. Maintain a flag at the SKU level to mark unbranded packaging as BlankBox (BB)-Only SKUs. You can view your BlankBox eligible products by calling getFeatureInventory API.
2. For BB-Only SKUs, be sure to track both unbranded packaging (BlankBox or BB) and regular inventory.
3. Set the toggle at sales channel level and ensure required sales channels are always looking at BB inventory. Create BB orders and relay BB inventory to these sales channels.
4. At the order working level, call PREVIEW Order and CREATE Order operations with the feature constraint Blank_Box=Required, to ensure items are delivered in unbranded packages only.
Block Amazon Logistics (Block AMZL or BAMZL):
Seller Central and Supply chain portal each offer a Block AMZL setting at a seller account’s marketplace level, which can be turned on for all orders, and comes with a surcharge of 5%. Developers who have a requirement of Block AMZL for specific orders can use the following configuration steps:
1. Set the toggle at the sales channel level to ensure the required sales channels’ orders are not delivered by Amazon Logistics. Create BAMZL orders for these channels.
2. At the order working level, call PREVIEW Order and CREATE Order operation with the feature constraint Block_AMZL=Required to ensure another carrier besides Amazon Logistics is shipping the items.
Best practice: MCF delivers most orders in unbranded packaging within the US region, but some sellers might have requirements that all orders be delivered in unbranded packages.
Unbranded packages (Blank Box or BB):
1. Maintain a flag at the SKU level to mark unbranded packaging as BlankBox (BB)-Only SKUs. You can view your BlankBox eligible products by calling getFeatureInventory API.
2. For BB-Only SKUs, be sure to track both unbranded packaging (BlankBox or BB) and regular inventory.
3. Set the toggle at sales channel level and ensure required sales channels are always looking at BB inventory. Create BB orders and relay BB inventory to these sales channels.
4. At the order working level, call PREVIEW Order and CREATE Order operations with the feature constraint Blank_Box=Required, to ensure items are delivered in unbranded packages only.
Block Amazon Logistics (Block AMZL or BAMZL):
Seller Central and Supply chain portal each offer a Block AMZL setting at a seller account’s marketplace level, which can be turned on for all orders, and comes with a surcharge of 5%. Developers who have a requirement of Block AMZL for specific orders can use the following configuration steps:
1. Set the toggle at the sales channel level to ensure the required sales channels’ orders are not delivered by Amazon Logistics. Create BAMZL orders for these channels.
2. At the order working level, call PREVIEW Order and CREATE Order operation with the feature constraint Block_AMZL=Required to ensure another carrier besides Amazon Logistics is shipping the items.
Testing authorize flow on a public app
Common challenge: Developers don’t know how to test their seller authentication flow without publishing or listing the app in Seller Central.
Best practice: Developers can validate the auth flow of a Test Seller account without having to publish the app. Test your auth flow by adding “version=beta” to the Seller Central consent URL for both Seller Central auth flow and Webstore auth flow. Note: In beta mode, no more than 25 sellers can authorize the app as this is intended only for validation purposes.
Example:
https://sellercentral.amazon.com/apps/authorize/consent?application_id=appidexample&state=stateexample&version=beta
Best practice: Developers can validate the auth flow of a Test Seller account without having to publish the app. Test your auth flow by adding “version=beta” to the Seller Central consent URL for both Seller Central auth flow and Webstore auth flow. Note: In beta mode, no more than 25 sellers can authorize the app as this is intended only for validation purposes.
Example:
https://sellercentral.amazon.com/apps/authorize/consent?application_id=appidexample&state=stateexample&version=beta
Extracting essential reports for MCF developers
Common challenge: Developers are not aware of the reports that can be extracted using our Reports API.
Best practice: Use the call information below to extract the key reports for MCF developers.
Key reports for MCF developers:
Listings reports - To get product listings data of a seller account.
GET_FLAT_FILE_OPEN_LISTINGS_DATA and GET_MERCHANT_LISTINGS_ALL_DATA
Inventory reports - To keep track of inventory movements at Amazon fulfillment centers.
GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA and GET_LEDGER_SUMMARY_VIEW_DATA
Orders/Sales reports - To fetch all orders and shipments data, fulfilled by Amazon.
GET_XML_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL, GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL, and GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL
Best practice: Use the call information below to extract the key reports for MCF developers.
Key reports for MCF developers:
Listings reports - To get product listings data of a seller account.
GET_FLAT_FILE_OPEN_LISTINGS_DATA and GET_MERCHANT_LISTINGS_ALL_DATA
Inventory reports - To keep track of inventory movements at Amazon fulfillment centers.
GET_FBA_MYI_UNSUPPRESSED_INVENTORY_DATA and GET_LEDGER_SUMMARY_VIEW_DATA
Orders/Sales reports - To fetch all orders and shipments data, fulfilled by Amazon.
GET_XML_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL, GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL, and GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL
Maintaining credentials for Sandbox access
Common challenge: Developers want to maintain different app credentials for the Dynamic Sandbox environment and the Production environment.
For both private and public apps, there is way to limit access only for the Dynamic Sandbox environment. Any production-approved app will have access to both Production and Sandbox endpoints and there is no way to restrict access.
Best practice: To solve the problem, developers can create different private apps in DRAFT status for the Sandbox and Production environments and list products only in Production, if they intend to keep two separate sets of client credentials.
For both private and public apps, there is way to limit access only for the Dynamic Sandbox environment. Any production-approved app will have access to both Production and Sandbox endpoints and there is no way to restrict access.
Best practice: To solve the problem, developers can create different private apps in DRAFT status for the Sandbox and Production environments and list products only in Production, if they intend to keep two separate sets of client credentials.
