Vendor Direct Fulfillment Orders API v1 Reference
Access 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 Plan:
| Rate (requests per second) | Burst |
|---|---|
| 10 | 10 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema | Default |
|---|---|---|---|---|
| Query | shipFromPartyId optional | The vendor warehouse identifier for the fulfillment warehouse. If not specified, the result will contain orders for all warehouses. | string | - |
| Query | status 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) | - |
| Query | limit optional | The limit to the number of purchase orders returned. Minimum : 1 Maximum : 100 | integer (int64) | - |
| Query | createdAfter 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) | - |
| Query | createdBefore 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) | - |
| Query | sortOrder optional | Sort the list in ascending or descending order by order creation date. | enum (SortOrder) | - |
| Query | nextToken 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 | - |
| Query | includeDetails optional | When true, returns the complete purchase order details. Otherwise, only purchase order numbers are returned. | string (boolean) | "true" |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | GetOrdersResponse |
| 400 | Request 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 |
| 403 | Indicates 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 |
| 404 | The 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 |
| 415 | The request payload is in an unsupported format. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | GetOrdersResponse |
| 429 | The frequency of requests was greater than allowed. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | GetOrdersResponse |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | GetOrdersResponse |
| 503 | Temporary overloading or maintenance of the server. Headers : 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 Plan:
| Rate (requests per second) | Burst |
|---|---|
| 10 | 10 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Path | purchaseOrderNumber required | The order identifier for the purchase order that you want. Formatting Notes: alpha-numeric code. | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | GetOrderResponse |
| 400 | Request 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 |
| 403 | Indicates 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 |
| 404 | The 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 |
| 415 | The request payload is in an unsupported format. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | GetOrderResponse |
| 429 | The frequency of requests was greater than allowed. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | GetOrderResponse |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | GetOrderResponse |
| 503 | Temporary overloading or maintenance of the server. Headers : 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 Plan:
| Rate (requests per second) | Burst |
|---|---|
| 10 | 10 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | body required | The request body that contains the order acknowledgement. | SubmitAcknowledgementRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 202 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | SubmitAcknowledgementResponse |
| 400 | Request 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 |
| 403 | Indicates 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 |
| 404 | The 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 |
| 415 | The request payload is in an unsupported format. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | SubmitAcknowledgementResponse |
| 429 | The frequency of requests was greater than allowed. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | SubmitAcknowledgementResponse |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers : x-amzn-RequestId (string) : Unique request reference identifier. | SubmitAcknowledgementResponse |
| 503 | Temporary overloading or maintenance of the server. Headers : 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 Code | Description | Schema |
|---|---|---|
| 401 | The request's Authorization header is not formatted correctly or does not contain a valid token. Headers: x-amzn-RequestId (string):Unique request reference identifier. | GetOrderResponse |
| 413 | The request size exceeded the maximum accepted size. Headers: x-amzn-RequestId (string):Unique request reference identifier. | SubmitAcknowledgementResponse |
Definitions
GetOrdersResponse
The response schema for the getOrders operation.
GetOrderResponse
The response schema for the getOrder operation.
OrderList
A purchase orders list returned as a response.
| Name | Description | Schema |
|---|---|---|
| pagination optional | The pagination elements required to retrieve the remaining data. | Pagination |
| orders optional | Represents a purchase order within the OrderList. | < Order > array |
Pagination
The pagination elements required to retrieve the remaining data.
| Name | Description | Schema |
|---|---|---|
| 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
Represents a purchase order.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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 | The total tax object within the shipment that relates to the order. | 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 |
| Name | Description | Schema |
|---|---|---|
| taxLineItem optional | Tax details. | TaxLineItem |
PartyIdentification
Name, address, and tax details of a party.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| name required | The name of the person, business, or institution at that address. For Amazon label only vendors, this field will have the value xxxxx within the object shipToParty. | string |
| attention optional | The attention name of the person at that address. For Amazon label only vendors, this field will have the value xxxxx within the object shipToParty. | string |
| addressLine1 required | First line of the address. For Amazon label only vendors, this field will have the value xxxxx within the object shipToParty. | string |
| addressLine2 optional | Additional address information, if required. For Amazon label only vendors, this field will have the value xxxxx within the object shipToParty. | string |
| addressLine3 optional | Additional address information, if required. For Amazon label only vendors, this field will have the value xxxxx within the object shipToParty. | string |
| city optional | The city where the person, business, or institution is located. For Amazon label only vendors, this field will have the value xxxxx within the object shipToParty. | string |
| county optional | The county where the person, business, or institution is located. For Amazon label only vendors, this field will have the value xxxxx within the object shipToParty. | string |
| district optional | The district where the person, business, or institution is located. For Amazon label only vendors, this field will have the value xxxxx within the object shipToParty. | 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. For Amazon label only vendors, this field will have the value xxxxx within the object shipToParty. | string |
OrderItem
An order item.
| Name | Description | Schema |
|---|---|---|
| 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 |
| Name | Description | Schema |
|---|---|---|
| taxLineItem optional | Tax details. | TaxLineItem |
Money
An amount of money, including units in the form of currency.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| payload optional | The payload for the submitAcknowledgement operation. | TransactionId |
| errors optional | A list of error responses returned when a request is unsuccessful. | ErrorList |
TransactionId
Response that contains the transaction ID.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| orderAcknowledgements optional | A list of one or more purchase orders. | < OrderAcknowledgementItem > array |
OrderAcknowledgementItem
Details of an individual order being acknowledged.
| Name | Description | Schema |
|---|---|---|
| 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
Individual item details within the acknowledged order.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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
The order's tax details.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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.
| Name | Description | Schema |
|---|---|---|
| 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
| Value | Description |
|---|---|
| NEW | Status for newly created purchase orders. |
| SHIPPED | Status for purchase orders that are already shipped. |
| ACCEPTED | Status for purchase orders accepted by vendors. |
| CANCELLED | Status for cancelled purchase orders. |
OrderStatus
Current status of the order.
Type : enum
| Value | Description |
|---|---|
| NEW | Status for newly created orders. |
| SHIPPED | Status for orders that are already shipped. |
| ACCEPTED | Status for orders accepted by vendors. |
| CANCELLED | Status for cancelled orders. |
Type
Tax type.
Type : enum
| Value | Description |
|---|---|
| CONSUMPTION | Tax levied on consumption spending on goods and services. |
| GST | Tax levied on most goods and services sold for domestic consumption. |
| MwSt. | Mehrwertsteuer, MwSt, is German for value-added tax. |
| PST | A provincial sales tax (PST) is imposed on consumers of goods and particular services in many Canadian provinces. |
| TOTAL | Combined total of all the applicable taxes. |
| TVA | Taxe sur la Valeur Ajoutée (TVA) is French for value-added tax. |
| VAT | Value-added tax. |
UnitOfMeasure
Unit of measure for the acknowledged quantity.
Type : enum
| Value | Description |
|---|---|
| Each | Unit of measure to represent individual piece. |
TaxRegistrationType
Tax registration type for the entity.
Type : enum
| Value | Description |
|---|---|
| VAT | Value-added tax. |
| GST | Goods and Services tax. |
SortOrder
Sort the list in ascending or descending order by order creation date.
Type : enum
| Value | Description |
|---|---|
| ASC | Sort in ascending order by order creation date. |
| DESC | Sort in descending order by order creation date. |
Updated 4 months ago