getShopReceipts: Proposed design change for getShopReceipts for post-sale activities

[Gareth064]

Is there an existing issue for this?

• I have searched the existing tickets

Current Endpoint Design

When using the min_last_modified & max_last_modified query parameters on this endpoint, the response does not include receipts where the following activities have happened within the stated parameters timespan.

• Receipt Cancelled
• Receipt Refunded Fully (Not Cancelled)
• Receipt Refunded Partially
• Expected Ship\Dispatch Date on Receipt Changed

Proposed Endpoint Design Change

When using the min_last_modified & max_last_modified query parameters on this endpoint, the response should include receipts where the following activities have happened within the stated parameters timespan.

• Receipt Cancelled
• Receipt Refunded Fully (Not Cancelled)
• Receipt Refunded Partially
• Expected Ship\Dispatch By Date on Receipt Changed

Other possibilities

1. Add Query Params like was_cancelled, was_fullyrefunded, was_partiallyrefunded. Not sure how to handle the Ship\Dispatch date with a boolean.
2. Add brand new endpoints for these very specific activities.

Why are you proposing this change?

The following issues were considered closed because they said the updated_timestamp on a Receipt was not updated to reflect post-sale activities. And you "fixed" those bugs via 3.0.0-general-release-2022-07-19 where you replace the updated_timestamp in the "response" with the latest updated_timestamp from related objects in the Receipt.

Previous issues: https://github.com/etsy/open-api/issues/513, https://github.com/etsy/open-api/issues/339, https://github.com/etsy/open-api/issues/232

But what we all wanted and expected, was yes, the updated_timestamp on the Receipt reflected that things have happened post-sale, but also that we can use the min_last_modified & max_last_modified query parameters on the getShopReceipts endpoint.

Based on the previous issues raised about this, these are the post-sale activities which we expect to be able to pick up using the getShopReceipts endpoint along with the min_last_modified & max_last_modified query parameters.

• Receipt Cancelled
• Receipt Refunded Fully (Not Cancelled)
• Receipt Refunded Partially
• Expected Ship\Dispatch Date on Receipt Changed

[chrisrogala]

I completely agree with this. By the end of next month, we will have over 1000 orders in our queue. Currently, the only way to identify if the order has been cancelled is if we sent a GET request to check the status on those 1000 orders individual. There is nothing in the documentation that states this endpoint would exclude these Receipts, so I would think they would be included.

[etsyachristensen]

This has been logged for discussion in our group.

[sowsinsk]

These are great suggestions, and would be helpful to us as well.

[KushGoyal]

I really need this feature too. Finding out cancelled orders is a huge headache.

[maurasz]

hello, any updates regarding this issue?

[benjymouse]

+1 this be great for us too

[JoannSellerServices]

This makes a lot of sense

[Gareth064]

@nateswart As we no longer have Andrew to ask for updates on things, can you get us one about this particular discussion please.

[Gareth064]

@nateswart @capndesign @ataetsy @pma-etsy Can anyone give us an update on this please?
I have nearly made and sent out 2 orders this week where they were cancelled in Etsy but not in my app, because when I do a refresh of receipts, these types of updates to receipts are not getting picked up!

[JoannSellerServices]

@Gareth064 does your application utilize the pubsubhubbub? We are concerned that there will not be an effective workaround for the sunsetting of this feed for updating user shop data and I was wondering if you are currently using this or have some other workaround prior to the release (if and when) of webhooks.

[Gareth064]

Hey. No we don't use anything like that. My app is built from scratch using v3 so never had access to the pusubhubbub thing.

Do you have any stats you can use to figure out if "polling" the Etsy API wouldn't work for you?

Wrbhooks are very convenient, but for me and my app 10k API calls per day per shop is more than enough for now.

Would need to know more about your app and it's usage before I could think up how to help with possible workarounds etc.

[JoannSellerServices]

Thanks for the quick reply! Most of what we do involves Syncing data for our users and the Etsy API. As such, it is important for us to be as close to real time as possible when orders happen, inventory levels change, listings are updated / deleted , etc. Essentially any activity on a user's Etsy account, we need to know about it as close to the moment of update / creation / deletion as possible.

[Gareth064]

Correct me if I'm wrong, but wasn't the only thing you could pubsubhub to in the v2 API was the listing changes? I didn't think you could for Orders? But anyway, if your requirement is as close to real-time as possible then you're not going to be able to achieve that from v3 in it's current state.

I also noticed that you mentioned "deleted" in your last message. There is no way to know from the API to know if something has been deleted in Etsy without making a call to see if an item exists.

Using listings as an example, you would have to do the leg work in you're app to figure out if something has been deleted by doing the following.

• Call getListingsByListingIds passing in a comma separated list of every listing ID (for that shop) you hold in your system.
• Take the returned data (probably after going through the paging system to get the full list) and compare the returned Listing ID's with the ones you have
• If any Listing IDs are missing from the results form Etsy then you need to assume that it was deleted.

Although it's not the subject of this discussion (but it is here #28) I really do hope Etsy bring Webhooks or Event Subscription. trying to figure out what data has change using the current API setup is very long winded and hard to achieve within the API Rate limits when you have shops with large numbers of Listings and orders.

[Gareth064]

I have emailed Etsy Devs asking for an update on this discussion.

[JoannSellerServices]

Just so I can understand the scope of this: Do these (cancelled, refunded, partially refunded) receipts come back when the query params are NOT used, or is it regardless of whether the params are used or not there is no way to pull receipts with this status?

[chrisrogala]

Just so I can understand the scope of this: Do these (cancelled, refunded, partially refunded) receipts come back when the query params are NOT used, or is it regardless of whether the params are used or not there is no way to pull receipts with this status?

When you make a call the the receipts endpoint, they are excluded in the results. The only way to access them is calling for the specific receipt id.

Here is an example. Receipt 2243699927 is cancelled in store 7974117. It's update_timestamp is 1639446775 and it's create_timestamp is 1636563548. The query below returns no results:

curl --location --request GET 'https://openapi.etsy.com/v3/application/shops/7974117/receipts?limit=100&offset=0&max_created=1636563550&min_created=1636563540' \
--header 'x-api-key: {REMOVED}' \
--header 'Authorization: Bearer {REMOVED}' 

Results:

{
    "count": 0,
    "results": []
}

I'm not sure who thought it was a good idea to exclude them, but it is a major flaw in the design.

[chrisrogala]

Just so I can understand the scope of this: Do these (cancelled, refunded, partially refunded) receipts come back when the query params are NOT used, or is it regardless of whether the params are used or not there is no way to pull receipts with this status?

Also, to be clear, this was the only reason we did not move to v3 and we have been waiting for Etsy to address this. Now our service is down with v2 being deprecated and we have to manually handle each order in Etsy. Not a bit deal for smaller sellers, but this is a major issue for us. If someone can remove the filter on that service, it would fix a lot of issues. I wish this was addressed 7 months ago when it was brought up as an issue. Etsy just pushed forward with the plan to turn v2 off. I wonder how many other sellers this is impacted. I would imagine this could affect Etsy's bottom line.

[JoannSellerServices]

Ok, so even when these params are not utilized, refunded / cancelled receipts do no populate in the count?

[Gareth064]

Correct, they are not returned with this endpoint. You'd have to query them directly one at a time to get their latest data.

[chrisrogala]

Hopefully they respond quickly. We postponed our transition to v3 because of this issue. Our new sync is based on min_created/max_created and min_last_modified/max_last_modified, but since cancelled orders do not appear in the query for the receipts, the cancelled orders do not update. Outside of looping through all orders, which is not realistic, we don't have an easy way to get recent changes. I don't see a point in even providing min/max values if all receipts in that range are not returned. We have to go manual now and customer orders will be delayed.

[Gareth064]

Curiously, I haven't even had the automated response to say they received my email. 🤔

[nateswart]

Hello everyone - we have reprioritized this work (up) and are investigating how we can support you best. I hope to have some info to share shortly.

[Gareth064]

That would be seriously appreciated @nateswart

Not to push our luck or anything, but would you be able to give any update on whether Webhooks/Events are also being discussed or investigated? I would tag the issue where it was discussed heavily but it appears you have now deleted/hidden the issues. Btw, lots of them were still open and had not yet been transferred to discussions 😢

[nateswart]

https://github.com/etsy/open-api/releases/tag/3.0.0-general-release-2023-04-18 😊

[Gareth064]

That's brilliant @nateswart will test this out shortly.

I assume these cancelled orders will work with the min_last_modified & max_last_modified filters on this endpoint?

And just want to double check that you are also going to be looking into the other Post-Sales Events as well?

• Receipt Refunded Fully (Not Cancelled)
• Receipt Refunded Partially
• Expected Ship\Dispatch By Date on Receipt Changed

[Gareth064]

I have tried this out and it appears to honor min_last_modified and max_last_modified

[nateswart]

yes, we are looking to add additional statuses as part of the breaking change coming next month

[Gareth064]

Best news in a long time.

If you sort this out and then look to implement webhooks, you're onto a winner.

[Gareth064]

Small quirk I noticed from a bug in my app after allowing cancelled orders to come through... The expected ship date is null on cancelled orders, and my system enforced it to be mandatory on all order objects.

A simple fix, but it makes me wonder what other data is different between an open order and a cancelled order, other than it's status

[Gareth064]

@nateswart great news about announcement #982

That means you guys will have delivered 3 of the 4 requested features on this discussion 🥳🥳 (assuming it works as we hope it will)

Just to set expectations, are you still looking into the final request?

• Expected Ship\Dispatch Date on Receipt Changed

[chrisrogala]

Hey there,

I hope everyone is doing well. Is there any update on final request in this comment? We are now in the holiday season, and with custom orders, the ship by date may change if a customer fails to send the necessary information in time to create the artwork. Right now, the update_timestamp does not change when the expected_ship_date was modified in the transactions so these updates to the receipt are not returned when the min_last_modified and max_last_modified are set. Any status update would be greatly appreciated.

Chris