Getting Personalisation Text Out of the Etsy API

If you have come from Amazon, where personalisation lives behind a restricted token inside a ZIP at the end of an expiring URL, Etsy is going to feel almost too easy.

You call getShopReceipts with the transactions_r scope and the personalisation is simply there, in the same response as the order. That is the whole retrieval story.

Which means the interesting part of this post is not how to fetch it. It is the three ways teams get the reading of it wrong.

The variations array carries everything the buyer selected, not just free text they typed. Size, colour and material choices sit in the same structure as the engraving field.

So you cannot simply take the first variation, or concatenate all of them, and call it personalisation. You are matching on the specific property that represents the personalisation field on that listing.

And listings differ. One seller calls it "Personalisation", another calls it "Engraving", a third calls it "Name on plaque". If you key on the display label, a seller renaming their field silently breaks your pipeline — and it breaks for one listing at a time, which is the hardest kind of failure to notice.

Etsy receipts carry a separate field, message_from_buyer — the note the buyer leaves at checkout. It is not part of variations.

And buyers use it. Constantly. Even on listings that have a perfectly good personalisation field, you will get orders where the engraving text arrives as "hi, please put 'In Loving Memory, 1943-2021' on this, thank you!" in the checkout note, with the personalisation field left empty or filled in with something contradictory.

If your fulfilment depends on getting this right, read both fields and surface both to whoever produces the item. Do not try to parse intent out of the note automatically — show it to a human. A note that contradicts the structured field is exactly the case where an automated guess produces an expensive mistake.

This is the one that survives longest in production, because nothing throws.

It is easy to write a variation parser that keys off the wrong identifier field. It will not error. It will produce empty personalisation for a subset of orders and correct text for the rest — which reads to everyone as a data problem on Etsy's side, not a bug in your code.

Meanwhile your production team quietly receives blank engravings for some orders and has to chase them manually, which they will assume is just how the system works.

Two defences, both cheap:

• Assert non-empty on orders you know are personalised. If a line item is for a made-to-order SKU and the personalisation came back blank, that is an exception that must reach a human before production.
• Keep the raw transaction payload for a retention window. When a parse turns out to be wrong, you can re-derive history instead of asking the seller to look up hundreds of orders.

Two things to get right when you set this up:

• You need the transactions_r scope, and scopes are frozen at consent — you cannot add it later without sending every connected shop back through the consent screen. Decide before you launch.
• Personalisation can change after the order is placed. Buyers message sellers with corrections, and the receipt can be updated. If your pipeline snapshots line items at sync time and never looks again, a corrected engraving never reaches production. Keep refreshing line items until the item actually enters the production stage.

If you have not set up API access yet, start with how to get Etsy API access, and note that Etsy's rotating refresh token is its own operational trap.

How does the Etsy API return personalisation text?

Inline on the receipt, in transactions[].variations as name and value pairs, returned by getShopReceipts with the transactions_r scope. There is no additional call, download or restricted token.

What is the difference between variations and message_from_buyer?

variations holds the buyer's selections on the listing, including any personalisation field. message_from_buyer is the free-text note left at checkout. Buyers frequently put engraving instructions in the note even when a personalisation field exists, so read both.

Why is personalisation empty for some Etsy orders but not others?

Usually a parser keyed on the wrong field, or on the seller-editable display label rather than the stable property identifier. It fails silently for the listings that do not match, which looks like a data problem rather than a bug.

Can personalisation change after an Etsy order is placed?

Yes. Buyers message sellers with corrections and the receipt can be updated, so keep refreshing line items until the item enters production rather than snapshotting once at sync time.

Which scope do I need for Etsy personalisation data?

transactions_r. Scopes are fixed at consent time, so adding it later requires every connected shop to re-authorise.