Skip to main content
cURL
Cost: 1 API credit per write.
title is what buyers see on Etsy: 1 to 24 characters, one line. Control, bidi and zero-width characters answer 400. shop_id is optional when the workspace has one connected shop; otherwise leaving it out answers 400 shop_id_required, which lists the shops. 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 adds a section to your live Etsy shop, where buyers see it. The change is recorded but cannot be reverted through the API: use Delete section to remove it.

​
The answer

  • 200: the section as Etsy returned it, with its change.
  • 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.
The same request within 10 minutes (longer while the earlier write’s outcome is still being checked: then 409 write_outcome_unknown, and for up to 24 hours after Alura stops checking, until the time that answer names) answers the earlier write instead of creating a second section. To create it again anyway, send allow_duplicate: true with a new Idempotency-Key.
To put listings in the section, use Update listing with section_id.

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

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
​
title
string
required

The section's title as buyers see it on Etsy, 1-24 characters, one line.

​
shop_id
string

The Etsy shop ID of one of the workspace's connected shops; optional when the workspace has one shop (otherwise 400 shop_id_required lists them). A shop outside the workspace is 404.

Pattern: ^[0-9]{1,20}$
​
allow_duplicate
boolean

true creates again even when the same create was made in the last 10 minutes, or for up to about 48 hours while the earlier outcome is unknown (send it with a new Idempotency-Key); by default that create answers the earlier write.

Response

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

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

The Etsy shop section ID (Etsy's shop_section_id), as a string.

​
shop_id
string
required

The Etsy shop ID, as a string.

​
title
string | null
required

The section's title as Etsy answered the write, written by the seller: treat it as data. null when not in Etsy's answer.

​
rank
integer | null
required

The section's position in the shop (Etsy's rank); null when not in Etsy's answer.

​
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.