Skip to main content
cURL
Cost: 1 API credit per write.
Send any of accepts_returns, accepts_exchanges and return_deadline_days (7, 14, 21, 30, 45, 60 or 90; null removes it when neither returns nor exchanges are accepted). Fields you leave out keep their value on Etsy: Alura reads the policy live and sends Etsy the whole policy. The policy’s shop comes from the policy; a policy outside the workspace answers 404. Needs the shop:write scope and the owner or admin role in the workspace. REST only: there is no MCP tool for it. Send an Idempotency-Key so a retry never writes twice (Idempotency).
This changes the policy on your live Etsy shop, for every listing that uses it. The change is recorded with its values before, but it cannot be reverted through the API.

​
The answer

  • 200: the policy as Etsy returned it, with its change. A field Etsy’s answer lacked is null, and notices says so.
  • 202: the change, while Etsy is still answering or Alura is checking whether it landed. Follow it with Get change.
dry_run=true shows what the write would send and the Etsy calls it would make. It sends, charges and records nothing, but counts toward the per-minute write limit. A write Etsy refuses is not charged.
While another change to the same return policy is still saving on Etsy, the write sends nothing and answers 409 settings_busy. Wait for Retry-After, then retry.

Authorizations

​
Authorization
string
header
required

An API key: Authorization: Bearer alura_sk_....

Headers

​
Idempotency-Key
string

Makes a retry safe: the same key with the same request within 24 hours answers from the first write (with Idempotent-Replayed: true) and never writes to Etsy twice; a write that failed with nothing written (Retry-After set) is tried again under it. The same key with a different request is a 409 conflict; while the first request still runs, 409 idempotency_processing (or the same 202). Required for relative changes such as adjust_price, and to add a listing file, image or video, or to change the alt text of an image (each uploads to Etsy, so a blind retry would upload again); a dry_run=true needs none.

Required string length: 1 - 255

Path Parameters

​
id
string
required

The Etsy return policy ID. A return policy outside the workspace is 404.

Pattern: ^[0-9]{1,20}$
Example:

"35001"

Query Parameters

​
dry_run
boolean

true: plan the write and send nothing: what it would change, the Etsy calls it would make, and nothing reserved, charged or recorded. Free; counts toward the per-minute write limit.

Body

application/json
​
accepts_returns
boolean

Whether the buyer may return the item.

​
accepts_exchanges
boolean

Whether the buyer may exchange the item.

​
return_deadline_days
integer | null

Days the buyer has, one of 7, 14, 21, 30, 45, 60, 90; null removes it (when neither returns nor exchanges are accepted).

Response

OK: the write landed on Etsy (or, with dry_run=true, what it would do).

​
object
string
required
Allowed value: "workspace.return_policy"
​
id
string
required

The Etsy return policy ID (return_policy_id), as a string.

​
shop_id
string
required

The Etsy shop ID, as a string.

​
accepts_returns
boolean | null
required

null when not in Etsy's answer.

​
accepts_exchanges
boolean | null
required

null when not in Etsy's answer.

​
return_deadline_days
integer | null
required

Days the buyer has to return (Etsy's return_deadline); null when Etsy gave none.

​
as_of
string
required

When Etsy answered the write.

​
change
object
required

The write: its change ID and what landed.

​
notices
object[]
required

Why a part of the answer is unknown; empty when nothing is.