[DOCS]: Details on Receipt Statuses

[NathanConroyOrd]

Is there an existing issue for this?

• [X] I have searched the existing issues

Link to Documentation Issue

https://developers.etsy.com/documentation/reference/#operation/getShopReceipts

What would you like to change?

In the description of a 200 response from the getShopReceipts method, an enum is given listing the possible receipt statuses.

I can't find a detailed description of what each receipt status means and how one status can change into another. For instance, the difference between paid receipts and open receipts isn't clear to me. And how can a paid receipt become an open receipt (or vice-versa)?

Would Etsy add these details to the docs? Or if the details are documented somewhere else, would it be possible to link to it in the response description?

Why are you proposing this change?

It would help in understanding the API and how to design a system to use it.

[etsyachristensen]

We can work on adding something, but the open status means an order that is placed, but not yet paid. This likely won't happen unless the seller has some offline method of payment. I'm honestly not sure if this is even possible anymore so it may just be legacy.

Orders typically start out as 'open', then go to 'payment processing' (which again is a very short-lived status), to paid and finally to completed once shipped.

At the moment, there is no mechanism for 3rd party apps to change the order status. Stores do have the ability to create custom order statuses and they are able to change orders to those statuses via the Etsy UI. We are investigating the possibility of adding the ability to change status to those custom statuses, but there's no timeline on that at the moment.

[NathanConroyOrd]

Thank you!

[NathanConroyOrd]

@etsyachristensen

This leads me to another question. For users who are migrating from the v2 API to the v3 API, it would be helpful to know the definitions of the v2 receipt statuses as well.

As far as I can tell, v2 receipt statuses are listed here https://www.etsy.com/developers/documentation/reference/receipt#method_findallshopreceiptsbystatus, but I cannot find exactly what these statuses mean. For instance, what's the difference between an unpaid receipt and an open one here? Is the v2 open receipt status equivalent to the v3 open receipt status?

Thank you!