Initial changes look good so far. :)

I'd like to restrict the scope of this PR to the create_fulfillment_order method for now. Reason being, there are several types of data structures - like Items, DeliveryWindow, Address, etc. - that are expected to be sent with the request, and expecting the user to send all of these as one massive method call can be overwhelming, especially if any one of those data types has some error or if we expect the user to know the exact key names to use.

As a starting point, refer to the methods in apis.inbound_shipments on develop branch that parse the structure of item dicts. This is one way we've tried to provide useful errors when the user submits data, before attempting to send requests to MWS that we know will fail ahead of time.

Ideally, these data structures can be codified as separate classes within apis.outbound_shipments. That would provide the best end-user experience, I think.

That all is optional, of course. We can make due with request methods that work and tests to cover them. :)

That makes sense! I (randomly) picked apis.merchant_fulfillment as my guide and I can see how the methods in api.inbound_shipments are preferable. I will put in some time soon on another PR with fancier validation. If there ends up being code that can be reused should that live in utils.py? For example parse_item_args looks like it could be reused in OutboundShipments with very little modification (or even a more generic key_config validator). Also are there any classes right now that have the data structures codified as separate classes?

For example parse_item_args looks like it could be reused in OutboundShipments with very little modification (or even a more generic key_config validator).

Perhaps, but given the different keys available between InboundShipmentItem and CreateFulfillmentOrderItem, and considering Amazon may choose to alter one or the other at any time, I think it best to keep them separated in their own API sections.

Also are there any classes right now that have the data structures codified as separate classes?

Very little. There is a ReportType enumeration available that simply defines the names of different reports, as defined here (MWS docs).

My suggestion here to write classes for these data types has me thinking I'll write one or more for InboundShipments sometime soon (after I finally get around to approving the other active PR we have (sorry, folks!)).

The idea to reuse parse_item_args would be to pass in an object and a key_config (set at the object level). This is kind of already done with Address and InboundShipmentItem something along the lines of:

def validate_obj_from_key_config(obj, key_config):
        # key_config is list of tuples: (input_key, output_key, is_required, default_value)
        if not all(k in obj for k in [c[0] for c in key_config if c[2]]):
        # Required keys of an obj line missing
        raise MWSError((
            "dict missing required keys: {required}."
            "\n- Optional keys: {optional}."
        ).format(
            required=', '.join([c[0] for c in key_config if c[2]]),
            optional=', '.join([c[0] for c in key_config if not c[2]]),
        ))

and then could even create the base dict from the obj

        return {c[1]: obj.get(c[0], c[3]) for c in key_config }

Anyway, I obviously will follow your lead on this -- this just stood out to me as refactor-able in my ~30 mins of looking at the code :)

Once you have classes for datatypes on InboundShipments I will follow that as an example try to do the same for OutboundShipments

That is definitely workable. All that would need doing at that point is defining the key configs for specific data types, which are essentially constants at the api module level.

Ok cool. Do those type of changes belong on a separate PR? Should I fill in the other methods for OutboundShipments on this one?