This top paragraph is great!

"before the customer has completed the checkout process" implies there is always a checkout, I'd be a bit more generic and say something that means "before the order has been completed" perhaps? Before the price, and line items, and exact contents of the order are finalized? the point is, its a draft if you can still change what the contents of the order are and what the exact pricing and payment method is.

+1 on "before the order has been completed" as well. Though, in both ways it may get a little confusing with [Abandoned Checkouts] (https://help.shopify.com/api/reference/abandoned_checkouts)

A Draft Order represents the status of an order before the order is set to completed status.

Might be good to also add some more description content from the regular docs:
https://help.shopify.com/manual/orders/create-orders

Calculated typo

I'd add creating custom orders or including custom product orders for customers as a possible enabled use case.

As in, I'm creating a blue tshirt with this logo that I don't usually use just for you.

From the create orders docs:
use custom items to represent additional costs or products that aren't displayed in your inventory

Pretty much all of the examples from the create docs explain this really well:

• create new orders in Shopify for sales you've made by phone, in person, or elsewhere
• send invoices to customers to pay with a secure checkout link
• use custom items to represent additional costs or products that aren't displayed in your inventory
• re-create mistaken orders from any of your active sales channels
• sell products at discount or wholesale rates
• take pre-orders

will use that list of use cases :)

by creating*

Also, do any of the Alpha testers have access to the Sales Channel SDK? If not, should we remove reference to this for the alpha?

Hmm I have no idea, I'm pretty sure none of them are channels since most are still hand picked right?
I'm ok with in or out. Leaving it in might elicit some interesting discussion. Or some painful one. Whatever Jordan thinks!

Do we use store or shop usually?

should be store since the partners dashboard updated to "development stores"

This endpoint is used by any app that interacts with draft orders, not sure if calling out draft order printing makes sense. Also we don't call it draft order printing in shopify speak, since the shopify terminology is "creating orders" It would be for printing invoices

why is the line_item description here instead of on the line_item field?

For line_itemsyou can use the value of thecustom field (true/false) to differentiate between custom line items and product variant line items.

You can either have Shopify email them a link, or use a draft order's invoice_url property to provide that link to the customer directly via email, chat,your app or any means that you are already using to communicate with the custom.

These aren't implemented yet (the filters) we need a way to mark that they aren't there yet! They will be very soon, but not before alpha.

create orders, in a draft state, maybe? I worry about using create draft orders when the feature in shopify is to create an order. but you're creating a draft order on the endpoint, so maybe we have to call it this?

I would vote to keep it as "Create a draft order" - partly because the code examples will do just that, and the created resource will live in the Draft orders section of the admin.

I think we might actually let you create multiple line items with one variant id but it'll get rolled up automatically. would be good to test this for accuracy.

I'll test this in a few

BTW - using the same variant_id more than once does not automatically roll all into a single line item. So the above statement is 👍

I think the important point here from docs perspective is simply to state that each product variant line item must have a unique variant id.

Shipping rates might not always be tied to fulfillments, since you might have a product fulfilled by vendor XYZ but the rate is provided by USPS. It doesn't 100% work that way in shopify right now since we can't have multi location but there's something about the way 'fulfill' is used in this sentence that seems incorrect.

Also a custom shipping line means you're provicing a custom rate, when you go to the resulting order you can still create a shipping label for that order using canada post or whatever you have set up for your shop. This is what the customer pays, not necessary what you use to fulfilll.

order_id is read_only

name is read_only

All of these fields except for customer { id } are read_only

This has multiple fields, not just a string.
Billing address too. See the checkout API docs for examples.

must be a valid email address

currency is read only

invoice_sent_at is read only

custom is read only

read only

ok... so, the doc has a column for what's read only, I'm not marking up the rest. You should review the design doc and remove anything from the create POST which is read_only.

Really a basic create post has line items, with a variant id and quantity OR a title, price and quantity

You can also look at the examples in the checkout API to see what makes sense. Just keep in mind they don't support custom line items and custom shipping rates.

Typo on "returned"

I'd like to get others' opinions (@dominiquesr) on the definition of the Error object. To me this still kind of reads that the object I'd be getting back would look like:

{ key: <field name>, value: <error> }

since key and value are defined as properties of the error object (or rather, properties of the additionalProperties), although I know we've already chatted about this and we're not sure there's a better way...

@tanner-rutgers do you think its more clear like this where I actually provide some sample values? Otherwise we can probably just remove the error schema all together and go with a simple description.

@andrewjtech123 I don't think providing samples values in the schema makes it any more clear, just more confusing (now it makes me think there's always a property called shipping_line and a property called is_invalid)

I'm definitely leaning towards removing the error schema altogether and just having Errors with a good description of what they are (stating that it's just a list of key value pairs where the key is the field in error and the value is the error detail), along with an example, which I think can also just be in the description.

ok agreed

Send, not create.

their

draft order invoice isn't really an object, its a set of parameters to use to send the invoice

will call it a hash instead, as per design doc

If the draft order has no email address to use, then you must specify an email address, otherwise an error is returned.

Bad english, but the text right now implies an error exists all of the time.

May want to reconsider including this in the docs as we previously discussed, depends on @jordanliddle

Setting the 'custom_message' works fine for me!

Not sure if this description makes sense given that its not really an object?

read only...

applied_discount

Missing description.

description is included at the ref.

read only

should be described in a public document that the checkout API also references. Why is this required for our docs, we don't use this?

removed

required is invalid there's no such thing as a rate, only a line, right now.

tax_line sis read only and not required. A read only field cannot be mandatory, its completely impossible. Can you cross reference?

title and price are only mandatory when handle is not provided.

As previously requested, please remove. This is not implemented.