Vendor Direct Fulfillment Orders API v1 reference

Programmatic access to a direct fulfillment vendor's order data.

Overview

The Selling Partner API for Direct Fulfillment Orders provides programmatic access to a direct fulfillment vendor's order data.

Version information

Version : v1

Contact information

Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html

License information

License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0

URI scheme

Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS

Consumes

  • application/json

Produces

  • application/json

Operations

getOrders
getOrder
submitAcknowledgement

Paths

GET /vendor/directFulfillment/orders/v1/purchaseOrders

Operation: getOrders

Description

Returns a list of purchase orders created during the time frame that you specify. You define the time frame using the createdAfter and createdBefore parameters. You must use both parameters. You can choose to get only the purchase order numbers by setting the includeDetails parameter to false. In that case, the operation returns a list of purchase order numbers. You can then call the getOrder operation to return the details of a specific order.

Usage Plans:

Plan typeRate (requests per second)Burst
Default1010
Selling partner specificVariableVariable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

Parameters

TypeNameDescriptionSchemaDefault
QueryshipFromPartyId
optional
The vendor warehouse identifier for the fulfillment warehouse. If not specified, the result will contain orders for all warehouses.string-
Querystatus
optional
Returns only the purchase orders that match the specified status. If not specified, the result will contain orders that match any status.enum (Status)-
Querylimit
optional
The limit to the number of purchase orders returned.
Minimum : 1
Maximum : 100
integer (int64)-
QuerycreatedAfter
required
Purchase orders that became available after this date and time will be included in the result. Must be in ISO-8601 date/time format.string (date-time)-
QuerycreatedBefore
required
Purchase orders that became available before this date and time will be included in the result. Must be in ISO-8601 date/time format.string (date-time)-
QuerysortOrder
optional
Sort the list in ascending or descending order by order creation date.enum (SortOrder)-
QuerynextToken
optional
Used for pagination when there are more orders than the specified result size limit. The token value is returned in the previous API call.string-
QueryincludeDetails
optional
When true, returns the complete purchase order details. Otherwise, only purchase order numbers are returned.string (boolean)"true"

Responses

HTTP CodeDescriptionSchema
200Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrdersResponse
400Request has missing or invalid parameters and cannot be parsed.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrdersResponse
403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.
Headers :
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrdersResponse
404The resource specified does not exist.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrdersResponse
415The request payload is in an unsupported format.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrdersResponse
429The frequency of requests was greater than allowed.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrdersResponse
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrdersResponse
503Temporary overloading or maintenance of the server.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrdersResponse

For additional error status codes, descriptions and schemas, see Error responses and schemas.

GET /vendor/directFulfillment/orders/v1/purchaseOrders/{purchaseOrderNumber}

Operation: getOrder

Description

Returns purchase order information for the purchaseOrderNumber that you specify.

Usage Plans:

Plan typeRate (requests per second)Burst
Default1010
Selling partner specificVariableVariable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

Parameters

TypeNameDescriptionSchema
PathpurchaseOrderNumber
required
The order identifier for the purchase order that you want. Formatting Notes: alpha-numeric code.string

Responses

HTTP CodeDescriptionSchema
200Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrderResponse
400Request has missing or invalid parameters and cannot be parsed.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrderResponse
403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.
Headers :
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrderResponse
404The resource specified does not exist.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrderResponse
415The request payload is in an unsupported format.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrderResponse
429The frequency of requests was greater than allowed.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrderResponse
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrderResponse
503Temporary overloading or maintenance of the server.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
GetOrderResponse

For additional error status codes, descriptions and schemas, see Error responses and schemas.

POST /vendor/directFulfillment/orders/v1/acknowledgements

Operation: submitAcknowledgement

Description

Submits acknowledgements for one or more purchase orders.

Usage Plans:

Plan typeRate (requests per second)Burst
Default1010
Selling partner specificVariableVariable

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation. Rate limits for some selling partners will vary from the default rate and burst shown in the table above. For more information, see "Usage Plans and Rate Limits" in the Selling Partner API documentation.

Parameters

TypeNameDescriptionSchema
Bodybody
required
The request schema for the submitAcknowledgement operation.SubmitAcknowledgementRequest

Responses

HTTP CodeDescriptionSchema
202Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
SubmitAcknowledgementResponse
400Request has missing or invalid parameters and cannot be parsed.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
SubmitAcknowledgementResponse
403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.
Headers :
x-amzn-RequestId (string) : Unique request reference identifier.
SubmitAcknowledgementResponse
404The resource specified does not exist.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
SubmitAcknowledgementResponse
415The request payload is in an unsupported format.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
SubmitAcknowledgementResponse
429The frequency of requests was greater than allowed.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
SubmitAcknowledgementResponse
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
SubmitAcknowledgementResponse
503Temporary overloading or maintenance of the server.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string) : Unique request reference identifier.
SubmitAcknowledgementResponse

For additional error status codes, descriptions and schemas, see Error responses and schemas.

Error Responses and Schemas

This table contains HTTP status codes and associated information for error responses.

HTTP CodeDescriptionSchema
401The request's Authorization header is not formatted correctly or does not contain a valid token.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
GetOrderResponse
413The request size exceeded the maximum accepted size.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
SubmitAcknowledgementResponse

Definitions

GetOrdersResponse

The response schema for the getOrders operation.

NameDescriptionSchema
payload
optional
A list of purchase orders.OrderList
errors
optional
A list of error responses returned when a request is unsuccessful.ErrorList

GetOrderResponse

The response schema for the getOrder operation.

NameDescriptionSchema
payload
optional
The payload for the getOrder operation.Order
errors
optional
A list of error responses returned when a request is unsuccessful.ErrorList

OrderList

NameSchema
pagination
optional
Pagination
orders
optional
< Order > array

Pagination

NameDescriptionSchema
nextToken
optional
A generated string used to pass information to your next request. If NextToken is returned, pass the value of NextToken to the next request. If NextToken is not returned, there are no more order items to return.string

Order

NameDescriptionSchema
purchaseOrderNumber
required
The purchase order number for this order. Formatting Notes: alpha-numeric code.string
orderDetails
optional
Purchase order details.OrderDetails

OrderDetails

Details of an order.

NameDescriptionSchema
customerOrderNumber
required
The customer order number.string
orderDate
required
The date the order was placed. This field is expected to be in ISO-8601 date/time format, for example:2018-07-16T23:00:00Z/ 2018-07-16T23:00:00-05:00 /2018-07-16T23:00:00-08:00. If no time zone is specified, UTC should be assumed.string (date-time)
orderStatus
optional
Current status of the order.enum (OrderStatus)
shipmentDetails
required
Shipment details required for the shipment.ShipmentDetails
taxTotal
optional
-taxTotal
sellingParty
required
PartyID of vendor code.PartyIdentification
shipFromParty
required
PartyID of vendor's warehouse.PartyIdentification
shipToParty
required
Name/Address and tax details of the ship to party.Address
billToParty
required
Name/Address and tax details of the bill to party.PartyIdentification
items
required
A list of items in this purchase order.< OrderItem > array


taxTotal

NameDescriptionSchema
taxLineItem
optional
Tax details.TaxLineItem

PartyIdentification

NameDescriptionSchema
partyId
required
Assigned identification for the party. For example, warehouse code or vendor code. Please refer to specific party for more details.string
address
optional
Address details of the party.Address
taxInfo
optional
Tax registration details of the entity.TaxRegistrationDetails

TaxRegistrationDetails

Tax registration details of the entity.

NameDescriptionSchema
taxRegistrationType
optional
Tax registration type for the entity.enum (TaxRegistrationType)
taxRegistrationNumber
required
Tax registration number for the party. For example, VAT ID.string
taxRegistrationAddress
optional
Address associated with the tax registration number.Address
taxRegistrationMessages
optional
Tax registration message that can be used for additional tax related details.string

Address

Address of the party.

NameDescriptionSchema
name
required
The name of the person, business or institution at that address.string
attention
optional
The attention name of the person at that address.string
addressLine1
required
First line of the address.string
addressLine2
optional
Additional address information, if required.string
addressLine3
optional
Additional address information, if required.string
city
optional
The city where the person, business or institution is located.string
county
optional
The county where person, business or institution is located.string
district
optional
The district where person, business or institution is located.string
stateOrRegion
required
The state or region where person, business or institution is located.string
postalCode
optional
The postal code of that address. It conatins a series of letters or digits or both, sometimes including spaces or punctuation.string
countryCode
required
The two digit country code. In ISO 3166-1 alpha-2 format.string
phone
optional
The phone number of the person, business or institution located at that address.string

OrderItem

NameDescriptionSchema
itemSequenceNumber
required
Numbering of the item on the purchase order. The first item will be 1, the second 2, and so on.string
buyerProductIdentifier
optional
Buyer's standard identification number (ASIN) of an item.string
vendorProductIdentifier
optional
The vendor selected product identification of the item.string
title
optional
Title for the item.string
orderedQuantity
required
Item quantity ordered.ItemQuantity
scheduledDeliveryShipment
optional
Details for the scheduled delivery shipment.ScheduledDeliveryShipment
giftDetails
optional
Gift message and wrapId details.GiftDetails
netPrice
required
Net price (before tax) to vendor with currency details.Money
taxDetails
optional
Total tax details for the line item.taxDetails
totalPrice
optional
The price to Amazon each (cost).Money


taxDetails

NameDescriptionSchema
taxLineItem
optional
Tax details.TaxLineItem

Money

An amount of money, including units in the form of currency.

NameDescriptionSchema
currencyCode
optional
Three digit currency code in ISO 4217 format. String of length 3.string
amount
optional
A decimal number with no loss of precision. Useful when precision loss is unacceptable, as with currencies. Follows RFC7159 for number representation.Decimal

Decimal

A decimal number with no loss of precision. Useful when precision loss is unacceptable, as with currencies. Follows RFC7159 for number representation.

Type : string

SubmitAcknowledgementResponse

The response schema for the submitAcknowledgement operation.

NameDescriptionSchema
payload
optional
The payload for the submitAcknowledgement operation.TransactionId
errors
optional
A list of error responses returned when a request is unsuccessful.ErrorList

TransactionId

NameDescriptionSchema
transactionId
optional
GUID assigned by Amazon to identify this transaction. This value can be used with the Transaction Status API to return the status of this transaction.string

ErrorList

A list of error responses returned when a request is unsuccessful.

Type : < Error > array

SubmitAcknowledgementRequest

The request schema for the submitAcknowledgement operation.

NameDescriptionSchema
orderAcknowledgements
optional
A list of one or more purchase orders.< OrderAcknowledgementItem > array

OrderAcknowledgementItem

Details of an individual order being acknowledged.

NameDescriptionSchema
purchaseOrderNumber
required
The purchase order number for this order. Formatting Notes: alpha-numeric code.string
vendorOrderNumber
required
The vendor's order number for this order.string
acknowledgementDate
required
The date and time when the order is acknowledged, in ISO-8601 date/time format. For example: 2018-07-16T23:00:00Z / 2018-07-16T23:00:00-05:00 / 2018-07-16T23:00:00-08:00.string (date-time)
acknowledgementStatus
required
Status of acknowledgement.AcknowledgementStatus
sellingParty
required
PartyID as vendor code.PartyIdentification
shipFromParty
required
PartyID as the vendor's warehouseId.PartyIdentification
itemAcknowledgements
required
Item details including acknowledged quantity.< OrderItemAcknowledgement > array

OrderItemAcknowledgement

NameDescriptionSchema
itemSequenceNumber
required
Line item sequence number for the item.string
buyerProductIdentifier
optional
Buyer's standard identification number (ASIN) of an item.string
vendorProductIdentifier
optional
The vendor selected product identification of the item. Should be the same as was provided in the purchase order.string
acknowledgedQuantity
required
Details of quantity acknowledged with the above acknowledgement code.ItemQuantity

ItemQuantity

Details of quantity ordered.

NameDescriptionSchema
amount
optional
Acknowledged quantity. This value should not be zero.integer
unitOfMeasure
optional
Unit of measure for the acknowledged quantity.enum (UnitOfMeasure)

TaxLineItem

A list of tax line items.

Type : < TaxDetails > array

TaxDetails

NameDescriptionSchema
taxRate
optional
A decimal number with no loss of precision. Useful when precision loss is unacceptable, as with currencies. Follows RFC7159 for number representation.Decimal
taxAmount
required
An amount of money, including units in the form of currency.Money
taxableAmount
optional
An amount of money, including units in the form of currency.Money
type
optional
Tax type.enum (Type)

AcknowledgementStatus

Status of acknowledgement.

NameDescriptionSchema
code
optional
Acknowledgement code is a unique two digit value which indicates the status of the acknowledgement. For a list of acknowledgement codes that Amazon supports, see the Vendor Direct Fulfillment APIs Use Case Guide.string
description
optional
Reason for the acknowledgement code.string

Error

Error response returned when the request is unsuccessful.

NameDescriptionSchema
code
required
An error code that identifies the type of error that occurred.string
message
required
A message that describes the error condition.string
details
optional
Additional details that can help the caller understand or fix the issue.string

ShipmentDetails

Shipment details required for the shipment.

NameDescriptionSchema
isPriorityShipment
required
When true, this is a priority shipment.boolean
isScheduledDeliveryShipment
optional
When true, this order is part of a scheduled delivery program.boolean
isPslipRequired
required
When true, a packing slip is required to be sent to the customer.boolean
isGift
optional
When true, the order contain a gift. Include the gift message and gift wrap information.boolean
shipMethod
required
Ship method to be used for shipping the order. Amazon defines ship method codes indicating the shipping carrier and shipment service level. To see the full list of ship methods in use, including both the code and the friendly name, search the 'Help' section on Vendor Central for 'ship methods'.string
shipmentDates
required
Shipment dates.ShipmentDates
messageToCustomer
required
Message to customer for order status.string

ShipmentDates

Shipment dates.

NameDescriptionSchema
requiredShipDate
required
Time by which the vendor is required to ship the order.string (date-time)
promisedDeliveryDate
optional
Delivery date promised to the Amazon customer.string (date-time)

ScheduledDeliveryShipment

Dates for the scheduled delivery shipments.

NameDescriptionSchema
scheduledDeliveryServiceType
optional
Scheduled delivery service type.string
earliestNominatedDeliveryDate
optional
Earliest nominated delivery date for the scheduled delivery.string (date-time)
latestNominatedDeliveryDate
optional
Latest nominated delivery date for the scheduled delivery.string (date-time)

GiftDetails

Gift details for the item.

NameDescriptionSchema
giftMessage
optional
Gift message to be printed in shipment.string
giftWrapId
optional
Gift wrap identifier for the gift wrapping, if any.string

Status

Returns only the purchase orders that match the specified status. If not specified, the result will contain orders that match any status.

Type : enum

ValueDescription
NEWStatus for newly created purchase orders.
SHIPPEDStatus for purchase orders that are already shipped.
ACCEPTEDStatus for purchase orders accepted by vendors.
CANCELLEDStatus for cancelled purchase orders.

OrderStatus

Current status of the order.

Type : enum

ValueDescription
NEWStatus for newly created orders.
SHIPPEDStatus for orders that are already shipped.
ACCEPTEDStatus for orders accepted by vendors.
CANCELLEDStatus for cancelled orders.

Type

Tax type.

Type : enum

ValueDescription
CONSUMPTIONTax levied on consumption spending on goods and services.
GSTTax levied on most goods and services sold for domestic consumption.
MwSt.Mehrwertsteuer, MwSt, is German for value-added tax.
PSTA provincial sales tax (PST) is imposed on consumers of goods and particular services in many Canadian provinces.
TOTALCombined total of all the applicable taxes.
TVATaxe sur la Valeur Ajoutée (TVA) is French for value-added tax.
VATValue-added tax.

UnitOfMeasure

Unit of measure for the acknowledged quantity.

Type : enum

ValueDescription
EachUnit of measure to represent individual piece.

TaxRegistrationType

Tax registration type for the entity.

Type : enum

ValueDescription
VATValue-added tax.
GSTGoods and Services tax.

SortOrder

Sort the list in ascending or descending order by order creation date.

Type : enum

ValueDescription
ASCSort in ascending order by order creation date.
DESCSort in descending order by order creation date.