Clarification on order.paid Webhook Payload

[janedyachenko]

Hi,

Could you please clarify the expected payload structure for the order.paid event?

The documentation page (https://developers.etsy.com/documentation/essentials/webhooks/#payload-structure) indicates that the payload should have a nested structure with a /data field containing the event-related information.

However, based on the webhook testing feature and manual testing by completing purchases in a shop, the payload appears to be much simpler:

{
"event_type": "order.paid",
"resource_url": "https://openapi.etsy.com/v3/application/shops/12345/receipts/54321",
"shop_id": 42
}
Could you please advise whether we should account for both payload formats, or if one of them is outdated?

[openapi-support[bot]]

Hi,

Thanks for flagging this — really appreciate you taking the time to point it out.

You’re absolutely right in your observation. The payload structure shown in the documentation was outdated, and we’ve now updated the docs to reflect the current, simplified payload format that you’re seeing in practice (like in your example).

Going forward, you should rely on the flatter structure:

• event_type
• resource_url
• shop_id

There’s no need to account for the previously documented nested /data format.

Thanks again for bringing this to our attention — it helped us improve the documentation.

Best,
The OpenAPI Team