Vendor Direct Fulfillment Orders API v1 reference

AmazonSPAPI

# Overview

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

# Version information

Version : v1

# Operations

getOrders
getOrder
submitAcknowledgement

# Paths

# getOrders

GET /vendor/directFulfillment/orders/v1/purchaseOrders

# 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 type Rate (requests per second) Burst
Default 10 10
Selling partner specific Variable Variable

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

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-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
429 The 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
500 An 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
503 Temporary 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.

# getOrder

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

# Description

Returns purchase order information for the purchaseOrderNumber that you specify.

Usage Plans:

Plan type Rate (requests per second) Burst
Default 10 10
Selling partner specific Variable Variable

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

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-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
429 The 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
500 An 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
503 Temporary 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.

# submitAcknowledgement

POST /vendor/directFulfillment/orders/v1/acknowledgements

# Description

Submits acknowledgements for one or more purchase orders.

Usage Plans:

Plan type Rate (requests per second) Burst
Default 10 10
Selling partner specific Variable Variable

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

Type Name Description Schema
Body body
required
The request schema for the submitAcknowledgement operation. 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-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
429 The 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
500 An 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
503 Temporary 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 Code Description Schema
401 The 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
413 The 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.

Name Description Schema
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.

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

# OrderList

Name Schema
pagination
optional
Pagination
orders
optional
< Order > array

# Pagination

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

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
- 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

Name Description Schema
taxLineItem
optional
Tax details. TaxLineItem

# PartyIdentification

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. 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

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

taxDetails

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

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

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

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.
Last Updated: 10/11/2022, 9:45:34 PM