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)

Amazon MWS FulfillmentInboundShipment API

MWS docs: FulfillmentInboundShipment Overview

set_ship_from_address(address)

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='')

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)

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)

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)

Returns one or more inbound shipment plans, which provide the information you need to create inbound shipments.

items expects a list of InboundShipmentPlanRequestItem 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 the InboundShipmentPlanRequestItem model does.

If from_address is not provided (with an instance of the Address 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)

Creates an inbound shipment to Amazon’s fulfillment network.

items expects a list of InboundShipmentItem 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 the InboundShipmentItem model does.

• The model also supports adding release_date, which the dictionary does not.

If from_address is not provided (with an instance of the Address 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)

Updates an existing inbound shipment in Amazon FBA.

items expects a list of InboundShipmentItem 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 the InboundShipmentItem model does.

• The model also supports adding release_date, which the dictionary does not.

If from_address is not provided (with an instance of the Address 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)

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.

MWS docs: GetPreorderInfo

Parameters

shipment_id (str) –

confirm_preorder(shipment_id, need_by_date)

Confirms a shipment for pre-order.

MWS docs: ConfirmPreorder

Parameters

• shipment_id (str) –

• need_by_date (datetime.datetime) –

get_prep_instructions_for_sku(skus, country_code='US')

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

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)

Requests an estimate of the shipping cost for an inbound shipment.

MWS docs: EstimateTransportRequest

Parameters

shipment_id (str) –

get_transport_content(shipment_id)

Returns current transportation information about an inbound shipment.

MWS docs: GetTransportContent

Parameters

shipment_id (str) –

confirm_transport_request(shipment_id)

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)

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)

Returns PDF document data for printing package labels for an inbound shipment.

MWS docs: GetPackageLabels

Parameters

• shipment_id (str) –

• num_labels (int) –

• page_type (str) –

get_unique_package_labels(shipment_id, page_type, package_ids)

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)

Returns num_labels number of pallet labels for shipment shipment_id of the given page_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.

MWS docs: GetPalletLabels

Parameters

• shipment_id (str) –

• page_type (str) –

• num_labels (int) –

get_bill_of_lading(shipment_id)

Returns PDF document data for printing a bill of lading for an inbound shipment.

MWS docs: GetBillOfLading

Parameters

shipment_id (str) –

list_inbound_shipments(shipment_ids=None, shipment_statuses=None, last_updated_after=None, last_updated_before=None, next_token=None)

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)

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)

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)

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)

Postal address information.

MWS docs: Address Datatype

classmethod from_legacy_dict(value)

Create an Address from a legacy structured dict.

Parameters

value (dict) –

Return type

mws.models.inbound_shipments.Address

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.PrepDetails(prep_instruction, prep_owner='SELLER')

A preparation instruction, and who is responsible for that preparation.

MWS docs: PrepDetails Datatype

prep_instruction accepts either a string or an instance of the PrepInstruction 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 use PrepDetails.AMAZON or PrepDetails.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)

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) and condition (to add item condition information).

condition may be a string or an instance of ItemCondition.

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)

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)

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:

1. Iterating for plan in resp.parsed.InboundShipmentPlans.member:; and

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

mws.models.inbound_shipments.InboundShipmentItem

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

Enums

class mws.models.inbound_shipments.PrepInstruction(value)

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)

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)

Given a shipment plan response, returns a list of InboundShipmentItem models constructed from the contents of that plan’s Items set.

Expects plan to be a node from a parsed MWS response from the create_inbound_shipment_plan request, typically the resp.parsed.InboundShipmentPlans.member node (which may be a DotDict for a single plan or a list of DotDict 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 by create_inbound_shipment_plan, such as quantity_in_case and release_date. Expects a dict where SellerSKUs are keys and the values are either instances of ExtraItemData or dictionaries with the keys quantity_in_case and/or release_date. Only items matching a SellerSKU key in overrides 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

List[mws.models.inbound_shipments.InboundShipmentItem]

class mws.models.inbound_shipments.ExtraItemData(quantity_in_case=None, release_date=None)

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 for shipment_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)