Vendor Direct Fulfillment Transaction Status API v2021-23-28 Use Case Guide

Programmatic access to a direct fulfillment vendor's transaction status.

API Version: 2021-12-28

What is the Direct Fulfillment Transaction Status API?

Vendors can use this API to check the transaction status of their POST transactions.

The following operation is included:

OperationHTTP MethodPathDescription
getTransactionStatusGET/vendor/directFulfillment/transactions/2021-12-28/transactions/{transactionId}Returns the status of the transaction indicated by the specified transactionId.

getTransactionStatus

Vendors can use the getTransactionStatus operation to check the status of a POST transaction. When a request is posted to Amazon using certain POST operations in the vendor APIs, such as submitAcknowledgement or submitShipmentConfirmations, for example, a successful response contains a transaction ID that uniquely identifies the transaction. Amazon will process the transaction asynchronously, and the final response will be available via the getTransactionStatus operation.

Amazon offers the final processed status for POST transactions such as submitAcknowledgement and submitShipmentConfirmations via this API. We highly recommend that vendors check the status using this API to ensure that transactions were processed successfully. If an error occurred you will receive the error details so you can correct the transaction and resubmit it.

Transaction StatusDefinition
ProcessingThe API transaction was received by Amazon is being processed. The processing is not completed yet. Check the SLA for each API operation for the expected time to complete processing.
SuccessThe API transaction was successfully processed by Amazon.
FailureThe API transaction failed during processing. The error details will be provided in the getTransactionStatus response body.

The transaction status is supported for the following Direct Fulfillment APIs:

DescriptionAPI SectionOperation
Acknowledge OrderDirect Fulfillment OrderssubmitAcknowledgement
Submit Shipment ConfirmationsDirect Fulfillment ShippingsubmitShipmentConfirmations
Shipping Label RequestDirect Fulfillment ShippingsubmitShippingLabelRequest
Shipping Status UpdatesDirect Fulfillment ShippingsubmitShipmentStatusUpdates
Inventory UpdateDirect Fulfillment InventorysubmitInventoryUpdate
InvoiceDirect Fulfillment PaymentssubmitInvoice

If the transaction status is Processing and not updated to Failure or Success after 15 minutes, then the transaction has not successfully completed. The Success status will appear if the transaction is successful and an error code will be provided for Failure.

You cannot use this API for invoice messages as they are not supported and the status will be always be Processing. For any payment related queries, go to Vendor Central, select Contact Us, and select the relevant queue if the status is not updated in the vendor central portal within a day. Please ensure the data submitted is correctly formatted before opening the case.

For shipping label requests, if the transaction is failed with a terminal error reason code such as Internal server error, go to Vendor Central and select Contact Us to get the cause investigated. This generally happens due to operational constraints. For data related failures, you can correct the data and resubmit the payload to get the order fulfilled.

getTransactionStatus Request

To return the transaction status, call the getTransactionStatus operation and pass the following parameter:

Path parameter:

Name Description Required
transactionId Previously returned in the response to the POST request of a specific transaction.

Type: string

Yes

Request Example:

GET https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/transactions/2021-12-28/transactions/20190904190535-eef8cad8-418e-4ed3-ac72-789e2ee6214a

getTransactionStatus Response

A successful response includes the following:

Name Description Required
transactionId The unique identifier sent in the transactionId field in response to the post request of a specific transaction.

Type: string

Yes
status Current processing status of the transaction.

enum ( Status )

Yes
errors Error code and message for the failed transaction. Only available when transaction status is 'Failure'.

Type: ErrorList

No

Response Example:

{
  "transactionId": "20190918190535-eef8cad8-418e-456f-ac72-789e2ee6813c",
  "status": "Failure",
  "errors": [
    {
      "code": "INVALID_ORDER_ID",
      "message": "Invalid order ID.",
      "details": "Please verify that the order ID is correct."
    }
  ]
}

List of errors

The table below contains a list of all possible error codes for each message type. You should configure these error codes in your system and design a failure handling mechanism. Each error code has a message that explains the error and details that suggest how to resolve the error before retrying the transaction.

CodeMessageDetailsMessage Type
INVALID_ORDER_IDInvalid order ID.Please verify that the order ID is correct.Acknowledgment
ACK_ALREADY_PROCESSEDOrder confirmation already received for {orderId}No further action required.Acknowledgment
INTERNAL_SERVER_ERRORInternal error. Please try again.Acknowledgment
SHIP_METHOD_NOT_SUPPORTED{ship_method} not supported by this channelPlease get label for {ship_method}, using your existing setup.ShipLabel
SHIP_METHOD_CHANGEDShip method for this PO has changed from {old_ship_method} to {ship_method}.Please get the label for {ship_method}, using your existing setup.ShipLabel
INVALID_DIMENSION_UNITRequest Rejected: Order ID {shipmentId} has invalid units of measure for the package(s) dimension.Please ensure package dimensions are IN or CMShipLabel
INVALID_PACKAGE_IDTotal {count} Invalid or Duplicate VendorPackageIds.Please fix the Invalid or Duplicate VendorPackageIds and try again.ShipLabel
INVALID_ORDER_ID_WAREHOUSE_COMBINATIONShippingLabel Rejected: Order ID {shipmentId} doesn't belong to warehouse {warehouseCode}.Please send valid order ID and warehouse codeShipLabel
INVALID_ORDER_STATUSRequest Rejected: Order {shipmentId} has been canceled.Order can't be shipped because it's in canceled status, please don't try to print label(s) again. If you think this order status is wrong, please contact us.ShipLabel
INVALID_WAREHOUSE_CODEShippingLabel Rejected: Invalid warehouse code {warehouseCode}.Please make sure to send a valid warehouse codeShipLabel
SHIPMENT_NOT_MUTABLERequest Rejected : Package dimensions for Order ID {shipmentId} can not be updated with current status.No further action required.ShipLabel
NO_ITEMS_PRESENTRequest Rejected: Order ID {shipmentId} has items not assigned to any package(s).Please make sure all items are map to the package(s).ShipLabel
PACKAGE_DIMENSION_NOT_VALIDRequest Rejected: Order ID {shipmentId} has invalid dimension for the package(s).Please add valid dimensions for your package(s).ShipLabel
PACKAGE_WEIGHT_NOT_VALIDRequest Rejected: Order ID {shipmentId} has invalid weight for the package(s).Please add valid weight for your package(s).ShipLabel
NO_SHIP_METHOD_ASSIGNABLERequest Rejected: At this time no ship-method can be assigned to Order ID {shipmentId}.Unable to assign ship-method. Please check your package dimensions and weight are accurate and print the label closer to the expected shipDate.ShipLabel
INCONSISTENT_SHIP_METHODSRequest Rejected: Different ship methods assigned across different package(s).Please try to ship all the items in a single box, if its not possible please contact us.ShipLabel
INTERNAL_NON_RETRYABLE_FAILURERequest Rejected: We have encounter an issue while processing your request.Please contact us.ShipLabel
INTERNAL_RETRYABLE_FAILURERequest Rejected: We have encounter an issue while processing your request.Please try again in few minutes. Please try again. And if issue persist please contact us.ShipLabel
EMPTY_PACKAGESASN Alert! Order ID {shipmentId} has empty packages.For future shipments, ensure your order has package(s).Shipment
EMPTY_ITEMSASN Alert! Order ID {shipmentId} has empty items.For future shipments, please ensure you add items to your ASN.Shipment
INTERNAL_FAILUREInternal error. Please try again.Internal error. Please try again.Shipment
NO_SHIP_METHODASN Rejected! No shipmethod found for package(s) {packageIds}.Please add your shipmethod and try again.Shipment
SHIPMENT_UNSHIPPABLEASN Rejected: Order ID {shipmentId} has no tracking-id or it has not processed the prerequisite documents (label, p-slip etc.).Please ensure all the pre-requisite docs( label, p-slip etc.) are processed and a valid tracking id is provided.Shipment
SHIPMENT_IMMUTABLEASN Rejected! Shipment status does not allow to update shipment.No further action required.Shipment
NOT_ALL_ITEMS_PRESENTASN Rejected: Order ID {shipmentId} has shipped quantity in packages that does not match the order quantity, and some items may not have a assigned package.Please add items to packages with correct shipped quantity.For items - {fnSku}, the expected quantity is {expectedQuantity} but the provided quantity is {providedQuantity}.Shipment
NO_ITEMS_PRESENTASN Rejected: Order ID {shipmentId} has items not assigned to any package(s).Please add items to packages.Shipment
DIMENSION_OR_WEIGHT_NOT_VALIDASN Rejected: Order ID {shipmentId} has negative or zero weight package(s).ASN Rejected: Order ID {shipmentId} has negative or zero weight package(s).Shipment
SHIP_METHOD_UNASSIGNABLEASN Rejected: Order ID {shipmentId} has ship-method that cannot be processed for the package(s).Unable to process ship-method. Please check your package dimensions, weight and ship-method.Shipment
INVALID_MESSAGE_PAYLOADInvalid input field {fieldName}.Shipment
VOC_NO_CARRIER_DETAILSASN Rejected! For orderId: {shipmentId}, Carrier details are not present for package {packageId}.Please add carrier or SCACCode and try again.Shipment
WEIGHT_NOT_PRESENT_FOR_PACKAGEASN rejected! For Order {shipmentId}. No Package weight present for package {packageId}.Please add weight and try again.Shipment
INVALID_TRACKING_IDASN Rejected: Invalid tracking id for package {packageId}.Varies based on carrier and for Amazon Ship label vendors, carrier has to match the one in ship labelShipment
INVALID_WAREHOUSE_CODEASN Rejected: Invalid warehouse code {warehouseCode}.Please verify that the warehouse code is correct.Shipment
ASN_ALREADY_PROCESSEDASN already received for {shipmentId}.No action needed, ASN is already processed.Shipment
INVALID_ORDER_ID_WAREHOUSEASN Rejected: OrderID {orderId} doesn't belong to warehouse {warehouseCode}.Please verify that the warehouse code and Order Id are correct.Shipment
INTERNAL_SERVER_ERRORInternal error. Please try again.Internal error. Please try again.Shipment