open-api
open-api copied to clipboard
etsy
[ENDPOINT] Proposed schema change for https://openapi.etsy.com/v3/application/receipts/{receipt_id}
Current Endpoint Schema No ability to update the status of an order. For example, changing an order from "New" to "In progress"
Proposed Endpoint Schema Add "status" property that can be updated via POST.
Why are you proposing this change? This functionality is available in Etsy's Shop Manager and works for stores with small amount of orders. If you have many orders to process, this gets tedious to manually move an order from "New" to "In progress". I would like to automate this via the API.
We can automate everything else with the Esty store we run but this is something the API doesn't let us do :( Status change automation options via an endpoint would enable us to update customers the moment a change has happened to the order they have with us. We would really like to be able to do this and I think the customers would also appreciate regular feedback on the status and change to the order as it is being made.
Thanks for taking the time to look into this.
Crazy this functionality is still missing from the v3 API as it was on the v2. Every other platform I've worked with has some way of flagging orders as "imported" or "processing" or "accepted" to allow filtering of only new orders to be processed. For some reason Etsy forces you to paginate through page after page of active orders checking to make sure nothing new has appeared. This is basic order management functionality.
Even weirder when Etsy forces you to be so wasteful with requests that look over orders you've already "seen" and then has harsh restrictions on allowed daily requests that limit scalability.
To be clear, what you'd normally have here is a way of updating a form of order "status" via the API. Then a way of filtering any checks for "new/unprocessed" orders via this status (for Etsy this would be on something like the "findAllShopReceipts" endpoint). This allows you to quickly and reliably import all new orders, marking them as imported as you add the data into your own OMS.
@Mike-LA-UK I appreciate this issue is more around the ability to update the order in Etsy to one of the custom statuses you can create in a shop and then use the API to get orders at the 'New' status, but this statement For some reason Etsy forces you to paginate through page after page of active orders checking to make sure nothing new has appeared. doesn't make sense to me.
Are you saying in order to look for new orders you are hitting the API to get all open orders then processing them over and over again to find new and updated ones? If so, then why aren't you keeping track (in your system) the last datetime you hit the API and then just ask Etsy for Open orders >= the last date? That way you just get anything that has been updated or added new? This is what I have been doing (In v2 might I add) and it's never failed me yet.
If you only want to get NEW orders and ignore anything that has been updated, then add a filter to the query to return only orders with a min_created >= the last date you hit the API.
@Mike-LA-UK @Gareth064, part of the issue is that Etsy doesn't have webhooks that we can use when a new order is added. My current workaround is to use Zapier to process Etsy transaction emails as they come in. This way, it acts a bit like a webhook, and I can get the transaction ID of the new order. I then use that to make a request to the Etsy API for the specific order, rather than having to parse through a big collection of orders or deal with tracking timestamps.
Also, I've completely given up hope that Etsy will support updating "status" via their API. It's simply not a high priority for the Etsy dev team, which seems to be really under-resourced. @capndesign
I personally don't think tracking timestamps is an issue. Its a very common and accepted integration pattern when you don't have any decent control over the source system you are trying to get data from.
As for the adding updating the status thing. These aren't standard data sets for Etsy to expose easily. Everyone can setup whatever status they want (Assuming your talking about the tabs you can add to you shop to move orders about in?)
For example my shop has the following
So they will have to build some sort of endpoint for you to call to get the statuses associated to that individual shop <- the lengthy piece of work, then add that ID into the receipt model <- the easier piece of work.
Just to be clear - I would love them to add this feature too so I can manage orders completely from my custom app, but until they do I unfortunately manage some data & processes in my app and things like this status stuff in the Etsy Web App.
Also, I like your idea for using Etsy Emails for new transactions as a way to simulate a webhook for new orders
What's interesting about this topic is that Etsy have their own "mission-control" api which contains the following endpoints GET: https://www.etsy.com/api/v3/ajax/shop/<your_shop_id>/mission-control/order-states POST: https://www.etsy.com/api/v3/ajax/shop/<your_shop_id>/mission-control/order-state/move-orders
Order-States - gets a list of States from your shop. Here is what it gets for mine which aligns with my screenshot further up
Order-State/Move-Orders - does a post with the State ID and list of orders to move to that state.
So it feels like what ever this "mission-control" api is they use for their Website, and probably mobile app, needs to have this functionality exposed or copied to the API being given to us.
@Gareth064 that's the frustrating part is that it already exists as a private API!
I suppose we could argue that everything exists in the private API 😄 I think for now we have to accept that the API we get to use is not their private one and their "small" team have to try to prioritise what it is they can do. At the moment there are things missing from returned payloads in V3 that used to exist in V2 that I'd prefer them to focus on sorting, then start looking at new features.
Btw - mine are just the opinions of a private app owner. I appreciate that most peoples concerns and issues in here are related to public apps that have customers and generate revenue, so anything that is a bug in the new API can be critical for most.
Are you saying in order to look for new orders you are hitting the API to get all open orders then processing them over and over again to find new and updated ones? If so, then why aren't you keeping track (in your system) the last datetime you hit the API and then just ask Etsy for Open orders >= the last date? That way you just get anything that has been updated or added new? This is what I have been doing (In v2 might I add) and it's never failed me yet.
You've never had orders where the payment takes longer to authorise? I've had orders that took over 24h before Etsy "released" them into the "was_paid" => true pool. For us they'll be off page 1 in a matter of hours at 100 orders per page. Are you just importing orders that haven't even validated payment? Then you'd still need to keep checking for the payment to have released before you can start to process them... I tried having it just load the most recent 100 orders of status paid => true and quickly started getting messages from our CS about orders the system had missed as soon as it got "busy" - which for us is still our smallest channel!
Here' the NOTHS API - https://sandbox.notonthehighstreet.com/swagger ...you fetch orders that aren't yet accepted then mark them accepted either individually or in bulk
Here's the HTF API - https://hardtofind.github.io/docs/order-management/#get-orders ...you fetch orders of a specified status "READY" then update them to "PROCESSED" when you import them
The same goes for Next (submit to /acknowledgements), Ebay (update to IN_PROGRESS), Amazon (submitAcknowledgement), Faire (post to /processing)... etc etc.
And yes those tabs in your screenshot are how the team managed them when we first trialled Etsy... so I was pretty dumbfounded that you couldn't just move orders in the same manner when I built our v2 integration.
But now we'd like to scale it and that "new" tab is already 5 figures when we dispatch within two days. ;_;
You've never had orders where the payment takes longer to authorise? I've had orders that took over 24h before Etsy "released" them into the "was_paid" => true pool
Can't say I've experienced or noticed this before myself.
For us they'll be off page 1 in a matter of hours at 100 orders per page.
This must be a crazy handmade busy you got there if you are taking and processing 100's per day, never mind in a few hours. 😄 For the majority of us it takes time to make our products so there is always a backlog before we start processing a new order. I think we process and dispatch on average 200 per week. So I'm afraid I can't relate to this problem you have but I can appreciate how it can get hard to process at your end if the volumes are that high and this was_paid flag is now important.
Thinking about your specific issue and working with what we got from the API currently, I would try the following:
- Call the getShopReceipts endpoint for open orders
- Do what you need to do in your app with the orders data
- Store the timestamp of the oldest order where the was_paid = false.
- Next time you call the getShopReceipts endpoint for open orders, include the filter for where min_updated >= of the timestamp captured in step 3. Then repeat going forward.
Off the top of my head, this means that going forward, any time you query for open orders, the earliest order should include any which were at the Was_paid = false state and if they have changed then you can update them appropriately internally.
Out of curiosity, how often to you poll for new orders? If you are processing the number of orders you appear to be then you must be hitting rate limits fairly quickly are you not?
So the issue is that is_paid isn't an action that updates anything about the order. Which means that it's not coupled to the sorting and orders won't appear in the API in the order that they were placed when you're using the filter. They'll just appear nestled away within other orders once the payment goes through. If you've a slow turnaround that might not be a problem but for us that means that orders appear randomly slotted between other orders and sometimes not even on page 1. The only way to ensure you don't miss any? Iterate over all the orders Etsy accepted today. This isn't how any of the other integrations we have work as you just filter explicitly by what needs to be imported in that round of processing. We poll every 15 minutes. For a bigger channels we import orders as frequently as every 5 minutes as there's not really any reason not to... due to the way their API is designed :D Also on other channels we might offer next day delivery which can make getting the order in quickly after placement important to not miss a collection.
For Etsy every time I make a request I store the rate limit remaining to keep track of how low it's going which alerts me at a threshold and then I can adjust if needed but I'll probably need to contact the team and ask for a limit increase for next year as there's other components we've still not implemented on things like product management. The lowest we went last year was 3000/10000 mid December but this year already looks like it'll be busier. The every 15 minutes is a "short one". Then periodically I have it check over everything from the last 7 days to ensure nothing was missed in either importing or automated dispatch (all happens automatically as an order is packed with the label being generated via the respective courier API, sent to the packing desk, and tracking sent to the partner API in one action).
Lastly yup at this time of year our handmade department operates near 24/7. Not sure which Norfolk you're in but we're in Norfolk UK so there's a reasonable chance you can guess the company. haha
Ah well yes, if things changing on a receipt is not then causing the updated timestamp to change then that is a big issue 😅
We were Norfolk, but since moved slightly over the border to Suffolk 😛 I had a look to see if I could figure out who you were based on your name but came up with nothing lol
Hey all. Sorry I haven't been able to weigh in on this. Having a specific "status" change has been off limits for external API partners. The running thought is that the status of a receipt/transaction would be changed automatically by specific actions happening, such as a payment received, shipment being created, being marked as shipped etc. I will have to run this up the flagpole with the internal API team here to discuss alternatives, but with the holidays coming and deadlines coming near we are not really able to put any time on this right at the moment.
Hello - any update on this issue? Do we have an ETA on when this could be completed @etsyachristensen
There's no ETA at this point. We haven't had the internal discussions about whether we can allow it or not. We will update the ticket when we have progress.
Ok - appreciate the update.
I suppose I don't understand why Etsy wouldn't allow users to change the internal order status, "New" --> "In Progress", etc. I'm a shop owner doing a significant amount of business on Etsy and definitely agree with @chanpory - it gets tedious to manually move an order from "New" to "In progress"...as far as I know it doesn't trigger any downstream actions or (potentially annoying) customer communications. Happy to discuss my use case with the Etsy team if helpful.
Anyway, looking forward to an update, hopefully sometime in the not-so-distant future.
Really would love to see this implemented soon. I don't fully understand the rationale for why this has been off-limits for external partners. We already can change status manually in the Etsy dashboard, and this co-exists successfully with automated status changes as such as a payment received, shipment being created, being marked as shipped etc.
As an initial first step, we have implemented the new endpoint updateShopReceipt with the ability to mark a receipt as paid or shipped. See documentation: https://developers.etsy.com/documentation/reference#operation/updateShopReceipt
Future development on this endpoint may come later. For the moment, this is meant to bring this feature on par with V2's updateReceipt endpoint.
Hi Andrew, good work. Will there be the possibility to ad a comment/message for the buyer along with the update? This would be very helpful for good customer care...