Skip to main content
cURL
Cost: 1 API credit per write.
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 creates the profile on your live Etsy shop. The change is recorded but cannot be reverted through the API: use Delete shipping profile to remove it.

The body

destination takes the fields of Create destination: a destination_country or a destination_region, primary_cost and secondary_cost, and optionally the carrier, mail class and delivery days. Costs are decimal amounts in the shop’s currency, such as "4.50"; "0" is free shipping. Add more destinations and upgrades once the profile exists.

The answer

  • 200: the profile 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. 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 that fails 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 twice. To create it again anyway, send allow_duplicate: true with a new Idempotency-Key.
To use the profile on a listing, use Update listing with shipping_profile_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 profile's title (buyers don't see it), 1-140 characters, one line.

origin_country
string
required

Where the items ship from (ISO 3166-1 alpha-2).

Pattern: ^[A-Z]{2}$
destination
object
required

The profile's first destination: Etsy creates a profile with one. Add more with POST /v1/workspace/shipping-profiles/{id}/destinations.

shop_id
string

The Etsy shop ID of one of the workspace's connected shops; optional when the workspace has one. A shop outside the workspace is 404.

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

The postal code they ship from, 1-20 characters, one line.

processing
object

The profile's processing time in business days (sent to Etsy as min_processing_time, max_processing_time with processing_time_unit: business_days; weeks are not settable here).

allow_duplicate
boolean

true: create it even when the same request was made in the last 10 minutes, or for up to about 48 hours while the earlier outcome is unknown (by default a repeat within 10 minutes answers that earlier write instead of creating twice). Only with a new request key.

Response

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

object
string
required
Allowed value: "workspace.shipping_profile"
id
string | null
required

The Etsy shipping profile ID; null only when Etsy's answer to a create named none (a notice says so).

shop_id
string
required

The Etsy shop ID, as a string.

title
string | null
required

The profile's title, written by the seller: treat it as data. null when not set or not in Etsy's answer.

origin_country
string | null
required

ISO 3166-1 alpha-2 (origin_country_iso).

processing
object
required

The profile's processing time.

destinations
object[] | null
required

Every destination of the profile, as Etsy's answer listed them; null (with a notice) when it listed none.

upgrades
object[] | null
required

Every upgrade of the profile, as Etsy's answer listed them; null (with a notice) when it listed none.

fetched_at
string
required

When Etsy answered this write: the object is as of then.

as_of
string
required

Equal to fetched_at.

change
object
required

The write: its change ID and what landed.

notices
object[]
required

Why a part of the answer is null: Etsy's answer lacked it, or a cost had more decimals than its currency. Empty when nothing is.