InboundShipments¶
According to Amazon’s documentation:
With the Fulfillment Inbound Shipment API section of Amazon Marketplace Web Service (Amazon MWS), you can create and update inbound shipments of inventory in Amazon’s fulfillment network. You can also request lists of inbound shipments or inbound shipment items based on criteria that you specify. After your inventory has been received in the fulfillment network, Amazon can fulfill your orders regardless of whether you are selling on Amazon’s retail web site or through other retail channels.
InboundShipments API reference¶
-
class
mws.
InboundShipments
(*args, **kwargs)[source]¶ Amazon MWS FulfillmentInboundShipment API
MWS docs: FulfillmentInboundShipment Overview
-
set_ship_from_address
(address)[source]¶ DEPRECATED, remove later. Now an alias to assigning
from_address
property directly.- Parameters
address (Union[mws.models.inbound_shipments.Address, dict]) –
-
from_address_params
(from_address=None, prefix='')[source]¶ Converts a from address, either stored or passed as an argument, to params.
If provided as an argument, checks first that the arg is the correct type, raising TypeError if it’s not an instance of the Address model.
Providing a from_address as an argument will override any address stored on this API instance.
- Parameters
from_address (Optional[mws.models.inbound_shipments.Address]) –
prefix (str) –
- Return type
dict
-
get_inbound_guidance_for_sku
(skus, marketplace_id)[source]¶ Returns inbound guidance for a list of items by Seller SKU.
skus
expects some iterable of strings. If it is any other type of object, it will be treated as a single instance and wrapped in a list first, similar to passing[skus]
.MWS docs: GetInboundGuidanceForSKU
- Parameters
skus (Union[List[str], str]) –
marketplace_id (str) –
-
get_inbound_guidance_for_asin
(asins, marketplace_id)[source]¶ Returns inbound guidance for a list of items by ASIN.
asins
expects some iterable of strings. If it is any other type of object, it will be treated as a single instance and wrapped in a list first, similar to passing[asins]
.MWS docs: GetInboundGuidanceForASIN
- Parameters
asins (Union[List[str], str]) –
marketplace_id (str) –
-
create_inbound_shipment_plan
(items, country_code='US', subdivision_code=None, label_preference=None, from_address=None)[source]¶ Returns one or more inbound shipment plans, which provide the information you need to create inbound shipments.
items
expects a list ofInboundShipmentPlanRequestItem
model instances. Also supports a list of “legacy” dictionaries, in which the keys ‘sku’ and ‘quantity’ are required; and keys ‘asin’, ‘condition’, and ‘quantity_in_case’ are optional.Note that the dictionary format does not support adding
PrepDetails
, as theInboundShipmentPlanRequestItem
model does.
If
from_address
is not provided (with an instance of theAddress
model), then the.from_address
attribute of this class instance must be set before using this operation.MWS docs: CreateInboundShipmentPlan
- Parameters
items (List[Union[mws.models.inbound_shipments.InboundShipmentPlanRequestItem, dict]]) –
country_code (str) –
subdivision_code (Optional[str]) –
label_preference (Optional[str]) –
from_address (Optional[mws.models.inbound_shipments.Address]) –
-
create_inbound_shipment
(shipment_id, shipment_name, destination, items, shipment_status='WORKING', label_preference=None, case_required=False, box_contents_source=None, from_address=None)[source]¶ Creates an inbound shipment to Amazon’s fulfillment network.
items
expects a list ofInboundShipmentItem
model instances. Also supports a list of “legacy” dictionaries, in which the keys ‘sku’ and ‘quantity’ are required; and key ‘quantity_in_case’ is optional.Note that the dictionary format does not support adding
PrepDetails
, as theInboundShipmentItem
model does.The model also supports adding
release_date
, which the dictionary does not.
If
from_address
is not provided (with an instance of theAddress
model), then the.from_address
attribute of this class instance must be set before using this operation.MWS docs: CreateInboundShipment
- Parameters
shipment_id (str) –
shipment_name (str) –
destination (str) –
items (List[Union[mws.models.inbound_shipments.InboundShipmentItem, dict]]) –
shipment_status (str) –
label_preference (Optional[str]) –
case_required (bool) –
box_contents_source (Optional[str]) –
from_address (Optional[mws.models.inbound_shipments.Address]) –
-
update_inbound_shipment
(shipment_id, shipment_name=None, destination=None, items=None, shipment_status=None, label_preference=None, case_required=None, box_contents_source=None, from_address=None)[source]¶ Updates an existing inbound shipment in Amazon FBA.
items
expects a list ofInboundShipmentItem
model instances. Also supports a list of “legacy” dictionaries, in which the keys ‘sku’ and ‘quantity’ are required; and key ‘quantity_in_case’ is optional.Note that the dictionary format does not support adding
PrepDetails
, as theInboundShipmentItem
model does.The model also supports adding
release_date
, which the dictionary does not.
If
from_address
is not provided (with an instance of theAddress
model), then the.from_address
attribute of this class instance must be set before using this operation.MWS docs: UpdateInboundShipment
- Parameters
shipment_id (str) –
shipment_name (Optional[str]) –
destination (Optional[str]) –
items (Optional[List[Union[mws.models.inbound_shipments.InboundShipmentItem, dict]]]) –
shipment_status (Optional[str]) –
label_preference (Optional[str]) –
case_required (Optional[bool]) –
box_contents_source (Optional[str]) –
from_address (Optional[mws.models.inbound_shipments.Address]) –
-
get_preorder_info
(shipment_id)[source]¶ Returns pre-order information, including dates, that a seller needs before confirming a shipment for pre-order. Also indicates if a shipment has already been confirmed for pre-order.
- Parameters
shipment_id (str) –
-
confirm_preorder
(shipment_id, need_by_date)[source]¶ Confirms a shipment for pre-order.
- Parameters
shipment_id (str) –
need_by_date (datetime.datetime) –
-
get_prep_instructions_for_sku
(skus, country_code='US')[source]¶ Returns labeling requirements and item preparation instructions to help you prepare items for an inbound shipment.
MWS docs: GetPrepInstructionsForSKU
- Parameters
skus (Union[List[str], str]) –
country_code (str) –
-
get_prep_instructions_for_asin
(asins, country_code='US')[source]¶ Returns item preparation instructions to help with item sourcing decisions.
MWS docs: GetPrepInstructionsForASIN
- Parameters
asins (Union[List[str], str]) –
country_code (str) –
-
estimate_transport_request
(shipment_id)[source]¶ Requests an estimate of the shipping cost for an inbound shipment.
MWS docs: EstimateTransportRequest
- Parameters
shipment_id (str) –
-
get_transport_content
(shipment_id)[source]¶ Returns current transportation information about an inbound shipment.
- Parameters
shipment_id (str) –
-
confirm_transport_request
(shipment_id)[source]¶ Confirms that you accept the Amazon-partnered shipping estimate and you request that the Amazon-partnered carrier ship your inbound shipment.
MWS docs: ConfirmTransportRequest
- Parameters
shipment_id (str) –
-
void_transport_request
(shipment_id)[source]¶ Voids a previously-confirmed request to ship your inbound shipment using an Amazon-partnered carrier.
MWS docs: VoidTransportRequest
- Parameters
shipment_id (str) –
-
get_package_labels
(shipment_id, num_labels, page_type=None)[source]¶ Returns PDF document data for printing package labels for an inbound shipment.
- Parameters
shipment_id (str) –
num_labels (int) –
page_type (str) –
-
get_unique_package_labels
(shipment_id, page_type, package_ids)[source]¶ Returns unique package labels for faster and more accurate shipment processing at the Amazon fulfillment center.
shipment_id
must match a valid, current shipment.page_type
expected to be string matching one of following (not checked, in case Amazon requirements change):“PackageLabel_Letter_2”
“PackageLabel_Letter_6”
“PackageLabel_A4_2”
“PackageLabel_A4_4”
“PackageLabel_Plain_Paper”
package_ids
expects some iterable of strings or integers. If it is any other type of object, it will be treated as a single instance and wrapped in a list first, similar to passing[package_ids]
.MWS docs: GetUniquePackageLabels
- Parameters
shipment_id (str) –
page_type (str) –
package_ids (Union[Iterable[Union[str, int]], str, int]) –
-
get_pallet_labels
(shipment_id, page_type, num_labels)[source]¶ Returns
num_labels
number of pallet labels for shipmentshipment_id
of the givenpage_type
.Amazon expects
page_type
as a string matching one of following:“PackageLabel_Letter_2”
“PackageLabel_Letter_6”
“PackageLabel_A4_2”
“PackageLabel_A4_4”
“PackageLabel_Plain_Paper”
num_labels
is integer, number of labels to create.- Parameters
shipment_id (str) –
page_type (str) –
num_labels (int) –
-
get_bill_of_lading
(shipment_id)[source]¶ Returns PDF document data for printing a bill of lading for an inbound shipment.
- Parameters
shipment_id (str) –
-
list_inbound_shipments
(shipment_ids=None, shipment_statuses=None, last_updated_after=None, last_updated_before=None, next_token=None)[source]¶ Returns list of shipments based on statuses, IDs, and/or before/after datetimes.
Pass
next_token
to call “ListInboundShipmentsByNextToken” instead.MWS docs: ListInboundShipments
- Parameters
shipment_ids (Iterable[str]) –
shipment_statuses (Iterable[str]) –
last_updated_after (datetime.datetime) –
last_updated_before (datetime.datetime) –
next_token (str) –
-
list_inbound_shipments_by_next_token
(token)[source]¶ Alias for
list_inbound_shipments(next_token=token)
MWS docs: ListInboundShipmentsByNextToken
- Parameters
token (str) –
-
list_inbound_shipment_items
(shipment_id=None, last_updated_after=None, last_updated_before=None, next_token=None)[source]¶ Returns list of items within inbound shipments and/or before/after datetimes.
Pass
next_token
to call “ListInboundShipmentItemsByNextToken” instead.MWS docs: ListInboundShipmentItems
- Parameters
shipment_id (str) –
last_updated_after (datetime.datetime) –
last_updated_before (datetime.datetime) –
next_token (str) –
-
list_inbound_shipment_items_by_next_token
(token)[source]¶ Alias for
list_inbound_shipment_items(next_token=token)
MWS docs: ListInboundShipmentItemsByNextToken
- Parameters
token (str) –
-
Other tools¶
Note
The following classes and utility functions are attached to the
InboundShipments
class for convenient access. For example,
the Address
model can be accessed like so:
from mws import InboundShipments
my_address = InboundShipments.Address(...)
# or from an instance of InboundShipments:
inbound_api = InboundShipments(...)
my_address = inbound_api.Address(...)
Data models¶
-
class
mws.models.inbound_shipments.
Address
(name=None, address_line_1=None, address_line_2=None, city=None, district_or_county=None, state_or_province_code=None, country_code='US', postal_code=None)[source]¶ Postal address information.
-
classmethod
from_legacy_dict
(value)[source]¶ Create an Address from a legacy structured dict.
- Parameters
value (dict) –
- Return type
-
to_params
(prefix='')¶ Flattens all parameters and values of this model into a single key-value dictionary, suitable for use in a request to MWS.
- Parameters
prefix (str) –
- Return type
dict
-
classmethod
-
class
mws.models.inbound_shipments.
PrepDetails
(prep_instruction, prep_owner='SELLER')[source]¶ A preparation instruction, and who is responsible for that preparation.
MWS docs: PrepDetails Datatype
prep_instruction
accepts either a string or an instance of thePrepInstruction
enum, detailing the type of prep to perform.prep_owner
(optional) accepts a string, typically “AMAZON” or “SELLER”, to indicate who is responsible for the prep. You can usePrepDetails.AMAZON
orPrepDetails.SELLER
to fill in these values. Defaults to “SELLER”.-
to_params
(prefix='')¶ Flattens all parameters and values of this model into a single key-value dictionary, suitable for use in a request to MWS.
- Parameters
prefix (str) –
- Return type
dict
-
-
class
mws.models.inbound_shipments.
InboundShipmentPlanRequestItem
(*args, asin=None, condition=None, **kwargs)[source]¶ Item information for creating an inbound shipment plan. Submitted with a call to the CreateInboundShipmentPlan operation.
MWS docs: InboundShipmentPlanRequestItem Datatype
Adds the optional arguments
asin
(to include ASIN as needed) andcondition
(to add item condition information).condition
may be a string or an instance ofItemCondition
.-
to_params
(prefix='')¶ Flattens all parameters and values of this model into a single key-value dictionary, suitable for use in a request to MWS.
- Parameters
prefix (str) –
- Return type
dict
-
-
class
mws.models.inbound_shipments.
InboundShipmentItem
(*args, release_date=None, **kwargs)[source]¶ Item information for an inbound shipment. Submitted with a call to the CreateInboundShipment or UpdateInboundShipment operation.
MWS docs: InboundShipmentItem Datatype
-
classmethod
from_plan_item
(item, quantity_in_case=None, release_date=None)[source]¶ Construct this model from a shipment plan returned from a CreateInboundShipmentPlan request.
Expects a
DotDict
instance that can typically be found in the parsed response object by:Iterating
for plan in resp.parsed.InboundShipmentPlans.member:
; andIterating
for item in plan.Items.member:
.
Each
item
instance in the above example should work here [YMMV].quantity_in_case
must be passed manually for case-packed shipments, even when constructing from a shipment plan response, as this data is not typically returned in the plan details.release_date
is also not part of a shipment plan response, so this must be passed manually in order to add it to the item.- Parameters
item (mws.utils.collections.DotDict) –
quantity_in_case (Optional[int]) –
release_date (Optional[datetime.datetime]) –
- Return type
-
to_params
(prefix='')¶ Flattens all parameters and values of this model into a single key-value dictionary, suitable for use in a request to MWS.
- Parameters
prefix (str) –
- Return type
dict
-
classmethod
Enums¶
-
class
mws.models.inbound_shipments.
PrepInstruction
(value)[source]¶ Bases:
enum.Enum
Enumeration of preparation instruction types.
MWS docs: PrepInstruction Datatype
-
POLYBAGGING
= 'Polybagging'¶
-
BUBBLEWRAPPING
= 'BubbleWrapping'¶
-
TAPING
= 'Taping'¶
-
BLACKSHRINKWRAPPING
= 'BlackShrinkWrapping'¶
-
LABELING
= 'Labeling'¶
-
HANGGARMENT
= 'HangGarment'¶
-
-
class
mws.models.inbound_shipments.
ItemCondition
(value)[source]¶ Bases:
str
,enum.Enum
Condition value for an item included with a CreateInboundShipmentPlan request. Values are defined within the InboundShipmentPlanRequestItem Datatype documentation.
-
NEW_ITEM
= 'NewItem'¶
-
NEW_WITH_WARRANTY
= 'NewWithWarranty'¶
-
NEW_OEM
= 'NewOEM'¶
-
NEW_OPEN_BOX
= 'NewOpenBox'¶
-
USED_LIKE_NEW
= 'UsedLikeNew'¶
-
USED_VERY_GOOD
= 'UsedVeryGood'¶
-
USED_GOOD
= 'UsedGood'¶
-
USED_ACCEPTABLE
= 'UsedAcceptable'¶
-
USED_POOR
= 'UsedPoor'¶
-
USED_REFURBISHED
= 'UsedRefurbished'¶
-
COLLECTIBLE_LIKE_NEW
= 'CollectibleLikeNew'¶
-
COLLECTIBLE_VERY_GOOD
= 'CollectibleVeryGood'¶
-
COLLECTIBLE_GOOD
= 'CollectibleGood'¶
-
COLLECTIBLE_ACCEPTABLE
= 'CollectibleAcceptable'¶
-
COLLECTIBLE_POOR
= 'CollectiblePoor'¶
-
REFURBISHED_WITH_WARRANTY
= 'RefurbishedWithWarranty'¶
-
REFURBISHED
= 'Refurbished'¶
-
CLUB
= 'Club'¶
-
Utilities¶
-
mws.models.inbound_shipments.
shipment_items_from_plan
(plan, overrides=None)[source]¶ Given a shipment plan response, returns a list of
InboundShipmentItem
models constructed from the contents of that plan’sItems
set.Expects
plan
to be a node from a parsed MWS response from thecreate_inbound_shipment_plan
request, typically theresp.parsed.InboundShipmentPlans.member
node (which may be aDotDict
for a single plan or a list ofDotDict
instances for multiple; though both options should be natively iterable with the same interface).Providing
overrides
allows the addition of details that are not returned bycreate_inbound_shipment_plan
, such asquantity_in_case
andrelease_date
. Expects a dict where SellerSKUs are keys and the values are either instances ofExtraItemData
or dictionaries with the keysquantity_in_case
and/orrelease_date
. Only items matching a SellerSKU key inoverrides
will have data overridden this way.For example usage, see: Converting plan items to shipment items
- Parameters
plan (Union[mws.utils.collections.DotDict, List[mws.utils.collections.DotDict]]) –
overrides (Optional[Dict[str, mws.models.inbound_shipments.ExtraItemData]]) –
- Return type
-
class
mws.models.inbound_shipments.
ExtraItemData
(quantity_in_case=None, release_date=None)[source]¶ Dataclass used for providing overrides to individual SKUs when processing items from a planned shipment in bulk using
shipment_items_from_plan()
.To utilize this data, construct a dictionary that maps SellerSKUs to instances of this class, then pass that dictionary to the
overrides
argument forshipment_items_from_plan
.Example:
override_data = { # with a case quantity "MySku1": ExtraItemData(quantity_in_case=12), # a release date "MySku2": ExtraItemData(release_date=datetime.datetime(2021, 1, 28)), # or both (short version) "MySku3": ExtraItemData(24, datetime.datetime(2021, 1, 28)), } data = shipment_items_from_plan(plan, override_data)