Eto Developer Platform

Developer API

v1 routes 90 core endpoints 105 marketplace endpoints Get an API key

Build on Eto’s infrastructure: manage listings and orders across your connected Etsy shops, run product research, and generate content, all behind a single API key.

This page carries the whole platform in one document. The Eto API comes first, followed by the complete marketplace reference covering every listing, order, shop and finance route Eto proxies for you.

This reference is a preview

It is the next version of Eto’s documentation, not a second version of the API. There is no /api/v2/: every path here is a live /api/v1/ route, and the routes the marketplace exposes but Eto does not are labelled not currently exposed rather than given a URL that would not answer. The settled, supported document is the v1 reference; this one is still being checked, so trust v1 where the two disagree.

Base URL

Every endpoint on this page is served from https://eto.tools and authenticates with the X-Eto-API-Key header. Eto holds the marketplace credentials for your connected stores, so you never handle them yourself.

#Authentication

Every request carries an API key in the X-Eto-API-Key header. Generate, rotate and revoke keys in the API console in your Eto dashboard.

curl -H "X-Eto-API-Key: eto_your_key_here" \
     "https://eto.tools/api/v1/listings/search?keywords=wallet"

One key opens every endpoint on this page, scoped to your own account and the stores connected to it. Treat it like a password: if it leaks, rotate it in the console and the old key stops working immediately.

OAuth bearer tokens

MCP clients that sign in with Eto send Authorization: Bearer <token> instead of a key. Both forms are accepted on every endpoint and resolve to the same account. See Connect an AI client.

The API and the MCP are Enterprise features. A key on any other plan is rejected with INVALID_API_KEY, and access stops the moment a plan is downgraded.

#Rate limits

Two limits apply, both counted per account rather than per key — rotating a key does not reset them.

2 / secondSliding window. Bursts above it get 429 with Retry-After: 1.

5,000 / dayResets at midnight UTC. Retry-After counts the seconds to the reset.

Every response, successful or not, carries the current budget:

X-RateLimit-Limit-Second: 2
X-RateLimit-Remaining-Second: 1
X-RateLimit-Limit-Day: 5000
X-RateLimit-Remaining-Day: 4987

A refused request returns the standard error body, so you can tell the two limits apart:

{
  "error": {
    "code": "RATE_LIMIT_SECOND",
    "status": 429,
    "message": "Rate limit exceeded (2 requests/second).",
    "hint": "Wait 1s before retrying.",
    "docs": "https://eto.tools/dev/docs#rate-limits"
  }
}

Retry on 429 after the Retry-After header says to, and back off exponentially if it happens repeatedly.

#Pagination

List endpoints page with limit and offset query parameters. Both are optional; each endpoint documents its own default and ceiling, and asking for more than the ceiling is clamped rather than rejected.

Name	Type	Required	Description
limit	integer	optional	Rows to return. Marketplace endpoints default to 25 (max 100); Eto orders default to 20 (max 200).
offset	integer	optional	Rows to skip. Default 0.

Responses carry the total alongside the page, so you can stop when offset + len(results) >= count:

{
  "count": 1000,
  "results": [ /* … up to `limit` rows … */ ]
}

Eto’s own list endpoints (orders, webhook deliveries) name the array after the resource — orders, deliveries — and return total next to it. The per-endpoint response examples below show the exact field names.

#Store connection

Endpoints that read or write shop data need that Etsy shop connected to your Eto account. Connect one at eto.tools/dashboard/stores, then list the shop ids with GET /api/v1/stores.

Store connection uses OAuth and must be done through the Eto dashboard — there is no API endpoint for this. Once connected, Eto manages credential refresh automatically.

#Errors

Every error response carries a machine-readable code, a human-readable message and a hint describing the fix.

INVALID_API_KEY HTTP 401

Your API key is missing, invalid, or has been revoked.

FixGenerate a new key in the API console at eto.tools/dashboard/api.

STORE_NOT_CONNECTED HTTP 403

You don't have access to this store.

FixConnect the store at eto.tools/dashboard first.

STORE_TOKEN_EXPIRED HTTP 503

Store authorization has expired.

FixReconnect your store at eto.tools/dashboard.

ENDPOINT_NOT_FOUND HTTP 404

This endpoint doesn't exist.

FixCheck the path and method against the docs.

METHOD_NOT_ALLOWED HTTP 405

This HTTP method isn't supported on this endpoint.

FixAllowed methods: {allowed_methods}

RATE_LIMIT_SECOND HTTP 429

Rate limit exceeded (2 requests/second).

FixWait {retry_after}s before retrying.

RATE_LIMIT_DAILY HTTP 429

Daily request limit reached (5,000/day).

FixLimit resets at midnight UTC.

UPSTREAM_ERROR HTTP 502

The upstream service returned an error.

FixCheck the upstream field for the marketplace’s own response.

INVALID_REQUEST HTTP 400

Request validation failed.

Fix{detail}

AI_CREDENTIALS_MISSING HTTP 403

No AI credentials configured.

FixAdd your Gemini API key at eto.tools/settings.

AI_GENERATION_FAILED HTTP 502

Image/text generation failed.

Fix{detail}

SESSION_NOT_FOUND HTTP 404

Research session not found.

FixCheck the session ID.

AGENT_BUSY HTTP 409

An agent process is already running for this session.

FixWait for it to complete or cancel it.

VALIDATION_FAILED HTTP 400

Request validation failed.

FixCheck the fields object for specific issues.

JOB_NOT_FOUND HTTP 404

Listing creation job not found.

FixCheck the job_id. Jobs expire after 24 hours.

DELIVERY_NOT_FOUND HTTP 404

Webhook delivery not found.

FixCheck the delivery id. List recent deliveries with GET /api/v1/webhooks/deliveries.

TAXONOMY_INVALID HTTP 400

The provided taxonomy_id is not a valid Etsy category.

FixUse GET /api/v1/categories/{id}/listing-schema to find valid categories.

STORE_NOT_OWNED HTTP 403

One or more shop_ids are not connected to your ETO account.

FixUse GET /api/v1/stores to see your connected shops. Connect new stores at eto.tools/dashboard.

FINANCE_NO_DATA HTTP 404

No finance data available for this store in the requested range.

FixVisit the Eto Finance dashboard to sync your store data, or adjust your date range.

ACTIVATION_COST_WARNING HTTP 200

Listing activation costs $0.20 USD per listing per shop.

FixSet state="draft" (default) to avoid charges.

#Listing Builder

How It Works

The ETO Listing Builder lets you create Etsy listings with a single API call. ETO handles all the complexity — variation property ordering, Cartesian product completion, price/quantity/SKU auto-detection, image uploading, category attributes, and personalization.

Three modes:

example

  state="draft"   → Saves to ETO only. Zero Etsy calls. Instant. You can review and edit in the ETO dashboard before publishing.
  state="publish" → Saves to ETO + publishes to Etsy as a draft listing. Synchronous: the request blocks for roughly 5–15 seconds per shop and returns the final results (including Etsy image URLs) in the response body.
  state="active"  → Same as publish + activates on Etsy. Costs $0.20 USD per listing per shop.

You can only publish to Etsy shops connected to your ETO account. Use GET /api/v1/stores to see your connected shops.

Step 1: Get Your Store Data

Before creating a listing, you need IDs for shipping profiles, return policies, processing profiles, and shop sections. We give you four dedicated "live" endpoints — one per profile type. Each one is a single GET, makes ONE Etsy API call, returns the absolute latest data right now, never from cache.

Live profile endpoints (always fresh, no cache):

example

  GET /api/v1/stores/{shop_id}/shipping-profiles/live    → shipping_profile_id
  GET /api/v1/stores/{shop_id}/return-policies/live      → return_policy_id
  GET /api/v1/stores/{shop_id}/processing-profiles/live  → processing_profile_id (a.k.a. readiness_state_id)
  GET /api/v1/stores/{shop_id}/shop-sections/live        → shop_section_id

Each response is the same shape:

example

  {
    "shop_id": "12345678",
    "fetched_at": "2026-04-19T14:30:00Z",
    "count": 2,
    "<profile_type>": [ { "<id_field>": ..., "title": "...", ... } ]
  }

Example — fetch all four in parallel from your client:

example

  curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/shipping-profiles/live"
  curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/return-policies/live"
  curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/processing-profiles/live"
  curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/shop-sections/live"

IDs you will need when building the listing payload:

example

  - shipping_profile_id   (required for physical listings)
  - return_policy_id      (required for physical listings)
  - processing_profile_id (controls processing-time display)
  - shop_section_id       (optional — organizes listing into a shop section)

Why use these instead of /details or /sync?

example

  - /details serves cached data — can be stale, missing return_policies and processing_profiles.
  - /sync refreshes everything in one shot but is heavier (~5 Etsy calls). Use it only when you want to refresh the full snapshot.
  - The four /live endpoints are the simplest path: pick the one you need, get the latest data, done.

Step 2: Get the Category Schema

Each Etsy category has different attributes. Call the schema endpoint to discover them:

example

  GET /api/v1/categories/{category_id}/listing-schema

This returns:

example

  - required_fields: title, description, price, quantity, taxonomy_id, listing_type
  - optional_fields: tags, materials, styles, sku, who_made, when_made, dimensions, weight, etc.
  - category_attributes: dynamic attributes for this category (e.g. Primary color, Sleeve length, Neckline)
    Each attribute has: property_id, name, required, possible_values (with value_id and name), scales
  - variation_properties: which properties can be used for product variations (e.g. Color, Size)

Cache this response — categories rarely change.

Example: Category 482 (T-Shirts) has 11 attributes:

example

  Materials, Primary color, Secondary color, Size, Sustainability, Sleeve length,
  Neckline, Clothing style, Occasion, Holiday, Graphic

Step 3: Upload Images (Two Options)

Option A — Remote URLs:

example

  Pass publicly accessible URLs directly in images[].url. ETO downloads them server-side.
  Example: "url": "https://i.etsystatic.com/12345/image.jpg"

Option B — Local files:

example

  1. Upload your file:  POST /api/v1/uploads  (multipart/form-data with "file" field)
  2. Use the returned eto-upload:// URL in images[].url

example

  Example:
    curl -X POST -H "X-Eto-API-Key: eto_..." -F "file=@my_photo.jpg" -F "type=image" https://eto.tools/api/v1/uploads
    Response: {"url": "eto-upload:///path/to/file.jpg", ...}
    Then use: "images": [{"url": "eto-upload:///path/to/file.jpg", "rank": 1}]

Images:

example

  - Min 1, max 20 per listing
  - Formats: JPG, PNG, GIF (max 100MB each)
  - rank: 1-20 (rank 1 = primary photo shown to buyers)
  - For variation images: use the index (0-based) in variation_images.mapping

Step 4: Create the Listing

Send a single POST with everything:

example

  POST /api/v1/listings/create

The request body is a JSON object with these top-level keys:

example

  state, shops[], listing{}, images[], personalization{}, category_attributes{}, variations{}
  Optional: digital_files[], videos[]

For state="draft": Returns instantly with listing_pk and dashboard_url. For state="publish"/"active": Returns job_id. Poll with GET /api/v1/listings/create/{job_id}.

Variations — How They Work

Etsy allows up to 2 variation properties per listing (e.g. Color + Size). You provide the data — ETO automatically detects what varies and sets the correct Etsy toggles:

example

  - Prices vary: if offerings have different prices, ETO detects which property causes it
  - Quantities vary: same auto-detection
  - SKUs vary: if each offering has a unique sku, ETO sets sku_on_property
  - Processing profiles vary: if offerings have different processing_profile_id values
  - Photos vary: if you provide variation_images.mapping, ETO links images to property values

Structure:

example

  "variations": {
    "properties": [
      {"property_id": 200, "name": "Color", "values": ["Black", "White", "Navy"]},
      {"property_id": 62809790533, "name": "Size", "scale_id": 17, "values": ["S", "M", "L", "XL"]}
    ],
    "offerings": [
      {"color": "Black", "size": "S", "price": 29.99, "quantity": 20, "sku": "BLK-S", "processing_profile_id": 123},
      {"color": "Black", "size": "XL", "price": 34.99, "quantity": 15, "sku": "BLK-XL", "processing_profile_id": 456},
      ...
    ],
    "variation_images": {
      "property": "color",
      "mapping": {"Black": 0, "White": 1, "Navy": 2}
    }
  }

Key rules:

example

  - Offering keys use the lowercased property name (e.g. "color", "size")
  - Each offering value must match one of the property's values array
  - variation_images.mapping values are 0-based indices into the images[] array
  - Only ONE property can have variation images (Etsy constraint)
  - ETO fills in missing combinations with is_enabled=false automatically

Category Attributes

Each Etsy category has specific attributes (e.g. T-Shirts have Primary color, Sleeve length, Neckline). Use the listing-schema endpoint to discover them, then pass the values you want:

example

  "category_attributes": {
    "200": {"value_ids": [1], "values": ["Black"]},
    "325502675244": {"value_ids": [2668], "values": ["Short sleeve"]},
    "325502675262": {"value_ids": [2678], "values": ["Crew"]}
  }

The key is the property_id (from listing-schema category_attributes). The value_ids and values come from listing-schema possible_values. Some properties have scales (like Size) — include scale_id when applicable.

Personalization

Etsy's multi-question personalization system lets sellers collect up to 5 custom details from buyers. Pass a "questions" array inside the personalization object. ETO handles the Etsy API translation.

Limits:

example

  - Maximum 5 questions per listing
  - Maximum 1 file-upload question (unlabeled_upload or labeled_upload) per listing
  - Set "enabled": false (or omit personalization entirely) to disable

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ QUESTION TYPES ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. text_input — Free text field

example

   Buyers type freeform text (names, dates, quotes, etc.).

example

   Fields:
     question_text          string   REQUIRED  1-45 chars, must start with letter/number
     instructions           string   optional  max 120 chars, must start with letter/number
     required               boolean  optional  default false
     max_allowed_characters  integer  optional  1-1024, default 256

example

   Example:
     {
       "question_type": "text_input",
       "question_text": "Name for engraving",
       "instructions": "Enter first and last name exactly as you want it engraved",
       "required": true,
       "max_allowed_characters": 30
     }

2. dropdown — List of options

example

   Buyers select from a predefined list. No instructions field allowed.

example

   Fields:
     question_text  string   REQUIRED  1-45 chars, must start with letter/number
     required       boolean  optional  default false
     options        array    REQUIRED  1-30 items
       options[].label  string  REQUIRED  1-20 chars, must be unique (case-insensitive)

example

   DO NOT include "instructions" — Etsy rejects dropdowns with instructions.

example

   Example:
     {
       "question_type": "dropdown",
       "question_text": "Thread color",
       "required": true,
       "options": [
         {"label": "Gold"},
         {"label": "Silver"},
         {"label": "Rose Gold"},
         {"label": "Black"}
       ]
     }

3. unlabeled_upload — File upload

example

   Buyers upload files (images, PDFs, etc.) without per-file labels.
   Accepted formats: .jpg, .png, .svg, .pdf, .heic (up to 100MB each).

example

   Fields:
     question_text     string   REQUIRED  1-45 chars, must start with letter/number
     instructions      string   optional  max 120 chars, must start with letter/number
     required          boolean  optional  default false
     max_allowed_files  integer  optional  1-10, default 1

example

   Example:
     {
       "question_type": "unlabeled_upload",
       "question_text": "Upload your logo",
       "instructions": "High-resolution PNG or SVG preferred, minimum 300 DPI",
       "required": true,
       "max_allowed_files": 3
     }

4. labeled_upload — File upload with labels

example

   Like unlabeled_upload, but each file slot has a named label shown to the buyer.
   The options array MUST have exactly as many items as max_allowed_files.

example

   Fields:
     question_text     string   REQUIRED  1-45 chars, must start with letter/number
     instructions      string   optional  max 120 chars, must start with letter/number
     required          boolean  optional  default false
     max_allowed_files  integer  REQUIRED  2-10 (minimum 2 for labeled uploads)
     options           array    REQUIRED  exactly max_allowed_files items
       options[].label  string  REQUIRED  1-45 chars

example

   Example:
     {
       "question_type": "labeled_upload",
       "question_text": "Upload design files",
       "instructions": "Please upload high-res files only",
       "required": true,
       "max_allowed_files": 3,
       "options": [
         {"label": "Front design"},
         {"label": "Back design"},
         {"label": "Sleeve design"}
       ]
     }

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ FULL EXAMPLE — All 4 question types ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

example

  "personalization": {
    "enabled": true,
    "questions": [
      {
        "question_type": "text_input",
        "question_text": "Name for engraving",
        "instructions": "Enter first and last name",
        "required": true,
        "max_allowed_characters": 30
      },
      {
        "question_type": "text_input",
        "question_text": "Special date",
        "instructions": "Format: MM/DD/YYYY",
        "required": false,
        "max_allowed_characters": 10
      },
      {
        "question_type": "dropdown",
        "question_text": "Font style",
        "required": true,
        "options": [
          {"label": "Script"},
          {"label": "Block"},
          {"label": "Serif"},
          {"label": "Handwritten"}
        ]
      },
      {
        "question_type": "dropdown",
        "question_text": "Gift wrapping",
        "required": false,
        "options": [
          {"label": "None"},
          {"label": "Standard box"},
          {"label": "Premium box"}
        ]
      },
      {
        "question_type": "labeled_upload",
        "question_text": "Upload design files",
        "instructions": "High-res PNG or SVG, minimum 300 DPI",
        "required": true,
        "max_allowed_files": 2,
        "options": [
          {"label": "Front design"},
          {"label": "Back design"}
        ]
      }
    ]
  }

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ VALIDATION ERRORS ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If validation fails, ETO returns 400 with specific field-level errors:

example

  {"error": "VALIDATION_FAILED", "fields": {
    "personalization.questions": "Maximum 5 questions allowed.",
    "personalization.questions.upload": "Maximum 1 upload-type question.",
    "personalization.questions[0].question_text": "Required.",
    "personalization.questions[0].question_text": "Max 45 characters. Provided: 52.",
    "personalization.questions[0].question_text": "Must start with a letter or number.",
    "personalization.questions[0].instructions": "Dropdown questions cannot have instructions.",
    "personalization.questions[0].instructions": "Max 120 characters. Provided: 135.",
    "personalization.questions[0].max_allowed_characters": "Must be 1-1024. Provided: 2000.",
    "personalization.questions[0].max_allowed_files": "Must be 2-10. Provided: 1.",
    "personalization.questions[0].options": "At least 1 option required.",
    "personalization.questions[0].options[2].label": "Option label cannot be empty.",
    "personalization.questions[0].options[2].label": "Max 20 characters. Provided: 25.",
    "personalization.questions[0].options[2].label": "Duplicate option: \"Gold\".",
    "personalization.questions[0].options": "Labeled upload requires exactly 3 file labels (matching max_allowed_files). Provided: 2."
  }}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DISABLING PERSONALIZATION ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

To remove all personalization from a listing:

example

  "personalization": {"enabled": false}

Or simply omit the personalization object entirely. On existing listings, this calls DELETE on the Etsy personalization endpoint.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ LEGACY SHORTHAND (still supported) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

If you omit "questions" but set "enabled": true, ETO creates a single text_input question from the flat fields. This is for backward compatibility only — use "questions" for new code.

example

  "personalization": {
    "enabled": true,
    "is_required": false,
    "instructions": "Enter name or initials",
    "max_chars": 15
  }

Equivalent to:

example

  "personalization": {
    "enabled": true,
    "questions": [{
      "question_type": "text_input",
      "question_text": "Personalization",
      "instructions": "Enter name or initials",
      "required": false,
      "max_allowed_characters": 15
    }]
  }

Complete Example — Maxed Out Physical Listing

This example creates a physical listing with EVERY feature: 5 images, 12 variations (3 colors x 4 sizes), prices/quantities/SKUs/processing profiles all varying, photos linked to colors, 5 personalization questions (2 text + 2 dropdown + 1 labeled upload), all 11 category attributes, full store settings.

example

curl -X POST -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" \
  "https://eto.tools/api/v1/listings/create" \
  -d '{
  "state": "publish",
  "shops": [{
    "shop_id": 57124360,
    "shipping_profile_id": 291257702631,
    "return_policy_id": 1435074483195,
    "processing_profile_id": 1456101932490,
    "shop_section_id": 56909368
  }],
  "listing": {
    "title": "Vintage Band Tee - Custom Graphic Design",
    "description": "Premium cotton vintage-style t-shirt...",
    "listing_type": "physical",
    "taxonomy_id": 482,
    "price": 29.99,
    "quantity": 100,
    "who_made": "i_did",
    "when_made": "2020_2026",
    "sku": "VBT-MAIN",
    "tags": ["vintage tee", "band shirt", "graphic tee", ...],
    "materials": ["cotton", "polyester"],
    "styles": ["Casual", "Vintage"],
    "item_weight": 6.0,
    "item_weight_unit": "oz"
  },
  "images": [
    {"url": "https://example.com/black-tee.jpg", "rank": 1},
    {"url": "https://example.com/white-tee.jpg", "rank": 2},
    {"url": "https://example.com/navy-tee.jpg", "rank": 3},
    {"url": "https://example.com/detail-shot.jpg", "rank": 4},
    {"url": "https://example.com/size-chart.jpg", "rank": 5}
  ],
  "personalization": {
    "enabled": true,
    "questions": [
      {
        "question_type": "text_input",
        "question_text": "Name for print",
        "instructions": "First and last name as you want it printed",
        "required": true,
        "max_allowed_characters": 30
      },
      {
        "question_type": "text_input",
        "question_text": "Special date",
        "instructions": "Format: MM/DD/YYYY",
        "required": false,
        "max_allowed_characters": 10
      },
      {
        "question_type": "dropdown",
        "question_text": "Font style",
        "required": true,
        "options": [
          {"label": "Script"},
          {"label": "Block"},
          {"label": "Serif"},
          {"label": "Handwritten"}
        ]
      },
      {
        "question_type": "dropdown",
        "question_text": "Gift wrapping",
        "required": false,
        "options": [
          {"label": "None"},
          {"label": "Standard box"},
          {"label": "Premium box"}
        ]
      },
      {
        "question_type": "labeled_upload",
        "question_text": "Upload design files",
        "instructions": "High-res PNG or SVG, minimum 300 DPI",
        "required": true,
        "max_allowed_files": 2,
        "options": [
          {"label": "Front design"},
          {"label": "Back design"}
        ]
      }
    ]
  },
  "category_attributes": {
    "200": {"value_ids": [1], "values": ["Black"]},
    "52047899002": {"value_ids": [10], "values": ["White"]},
    "62809790533": {"value_ids": [2139], "values": ["M"], "scale_id": 17},
    "325502675244": {"value_ids": [2668], "values": ["Short sleeve"]},
    "325502675262": {"value_ids": [2678], "values": ["Crew"]},
    "325502673988": {"value_ids": [2556], "values": ["Streetwear"]},
    "46803063641": {"value_ids": [19], "values": ["Birthday"]},
    "46803063659": {"value_ids": [35], "values": ["Christmas"]},
    "332797777099": {"value_ids": [2558], "values": ["Animal"]}
  },
  "variations": {
    "properties": [
      {"property_id": 200, "name": "Color", "values": ["Black", "White", "Navy"]},
      {"property_id": 62809790533, "name": "Size", "scale_id": 17, "values": ["S", "M", "L", "XL"]}
    ],
    "offerings": [
      {"color": "Black", "size": "S", "price": 29.99, "quantity": 20, "sku": "BLK-S", "processing_profile_id": 1456101932490},
      {"color": "Black", "size": "XL", "price": 34.99, "quantity": 15, "sku": "BLK-XL", "processing_profile_id": 1458328250863},
      {"color": "White", "size": "S", "price": 29.99, "quantity": 20, "sku": "WHT-S", "processing_profile_id": 1456101932490},
      ...
    ],
    "variation_images": {
      "property": "color",
      "mapping": {"Black": 0, "White": 1, "Navy": 2}
    }
  }
}'

Response — Draft (state="draft")

example

{
  "listing_pk": 1135,
  "status": "draft",
  "message": "Listing saved as draft in ETO. Open it in the ETO dashboard to review and publish.",
  "dashboard_url": "/dashboard/single-research/1135/"
}

The listing is saved in ETO with all fields pre-filled. Open the dashboard URL to review, edit anything, and publish when ready. Zero Etsy API calls were made.

Response — Publish/Active (state="publish" or "active")

The request runs synchronously: it blocks for ~5–15 seconds per shop while ETO creates the draft on Etsy, uploads images/videos/files, sets inventory and variations, and fetches the final image URLs back. Set your HTTP client timeout to at least 60s (120s for multi-shop calls).

200 OK — successful publish:

example

{
  "job_id": "lcj_aDzKwnFW5sYHewZaPTduRw",
  "listing_pk": 1173,
  "status": "completed",
  "poll_url": "/api/v1/listings/create/lcj_aDzKwnFW5sYHewZaPTduRw",
  "dashboard_url": "/dashboard/single-research/1173/",
  "shops_count": 1,
  "results": [{
    "shop_id": "53081804",
    "status": "ok",
    "listing_id": 4489813117,
    "listing_url": "https://www.etsy.com/listing/4489813117",
    "currency_code": "GBP",
    "price": 24.99,
    "images": [
      {"listing_image_id": 5523110099001, "url_fullxfull": "https://i.etsystatic.com/...", "rank": 1}
    ],
    "videos": []
  }]
}

For state="active", successful shops also carry "activated": true and "activation_cost_usd": 0.20.

Per-shop failures are reported inside results[] with status="error" and an Etsy-side error payload. Other shops in the same request can still succeed.

Backwards compatibility: job_id and poll_url are still in the response so existing clients that call GET /api/v1/listings/create/{job_id} continue to work. The job will be in "completed" state on the first poll.

500 Internal Server Error — job-level failure (e.g. the entire publish flow threw):

example

{
  "job_id": "lcj_...",
  "listing_pk": 1174,
  "status": "failed",
  "error": "<human-readable reason>",
  "poll_url": "/api/v1/listings/create/lcj_...",
  "results": []
}

Validation & Preflight Errors (400)

The listing-create endpoint validates heavily before writing any state. If a preflight check fails, you get a 400 with a fields object pointing at the exact problem:

example

{
  "error": {
    "code": "VALIDATION_FAILED",
    "status": 400,
    "message": "Request validation failed.",
    "fields": {
      "images[1].url": "Uploaded file is no longer available on the server. Re-upload via POST /api/v1/uploads and use the new url.",
      "shops[0].shop_section_id": "Section 999999999 not found in shop 53081804."
    }
  }
}

Common preflight errors:

• images[N].url / digital_files[N].url / videos[N].url — the eto-upload:// URL you referenced no longer resolves to a file on the server. This can happen if the upload was done a long time ago or if the server was redeployed. Re-upload via POST /api/v1/uploads and use the fresh URL.

• shops[N].shop_section_id — the section ID does not belong to that shop. Call GET /api/v1/stores/{shop_id}/shop-sections/live to fetch the current sections.

• Standard field-shape errors (title too long, missing taxonomy_id, etc.) from the schema validator.

All preflight errors are fatal: if a 400 is returned, nothing was persisted on the ETO side and no Etsy draft was created. Retrying with a fixed payload is safe.

For AI Agents

1. Always call GET /api/v1/stores first to get valid shop_ids. 2. Get profile IDs from the four live endpoints (each returns the absolute latest, no cache):

example

     GET /api/v1/stores/{shop_id}/shipping-profiles/live    → shipping_profile_id
     GET /api/v1/stores/{shop_id}/return-policies/live      → return_policy_id
     GET /api/v1/stores/{shop_id}/processing-profiles/live  → processing_profile_id
     GET /api/v1/stores/{shop_id}/shop-sections/live        → shop_section_id
   Fetch them in parallel for speed.

3. Call GET /api/v1/categories/{id}/listing-schema for any new category to discover attributes and variation properties. 4. Use the "required" field on category_attributes to know which are mandatory. 5. Use "possible_values" from the schema to select valid value_ids for each attribute. 6. Default to state="draft" unless the user explicitly asks to publish or activate. 7. state="active" costs $0.20 USD per listing per shop — always warn the user. 8. For variations: just provide the data (prices, quantities, SKUs, processing_profile_id per offering). ETO auto-detects what varies. 9. For variation images: set variation_images.property to the property name (e.g. "color") and mapping to {value: image_index}. 10. Images can be URLs or local files uploaded via POST /api/v1/uploads.

#Get category listing schema

GEThttps://eto.tools/api/v1/categories/{category_id}/listing-schema

Returns the full schema for creating a listing in a specific Etsy category. Includes required fields, category-specific attributes with valid values, variation properties, and constraints. Cache this response — categories change rarely.

AuthorizationAPI keyoperation listing_schema

Path parameters

category_id integer required

Etsy taxonomy/category ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/categories/2078/listing-schema"

Example response

json

{"category_id": 2078, "required_fields": {...}, "category_attributes": [...], "variation_properties": [...]}

#Create a listing

POSThttps://eto.tools/api/v1/listings/create

Create a complete Etsy listing with a single JSON payload. Handles title, description, images (URLs or eto-upload:// tokens from POST /api/v1/uploads), variations, pricing, tags, materials, personalization, and multi-shop publishing. ETO handles all Etsy API complexity: variation property ordering, Cartesian product completion, price_on_property detection, SKU truncation, image ordering, and inventory updates.

state="draft" → saves to ETO only. No Etsy API calls. Returns immediately. state="publish" → saves to ETO and creates a draft listing on Etsy. Blocking: the request holds open until Etsy has accepted the listing and all images/videos/files are attached (typically 5–15s per shop). Returns the final results inline. state="active" → same as publish + activates each listing on Etsy. Costs $0.20 USD per listing per shop.

You can only publish to Etsy shops connected to your ETO account. Use GET /api/v1/stores to list them.

For backwards compatibility, the response still includes job_id and poll_url so existing clients that poll GET /api/v1/listings/create/{job_id} continue to work — the job will be in "completed" state on the first poll.

Validation errors (400 VALIDATION_FAILED): • images[N].url / digital_files[N].url / videos[N].url — "Uploaded file is no longer available on the server. Re-upload via POST /api/v1/uploads and use the new url." Fires when the eto-upload:// path no longer resolves on disk. Re-upload and retry. • shops[N].shop_section_id — "Section X not found in shop Y." Fires when the section ID does not belong to the shop. Call GET /api/v1/stores/{shop_id}/shop-sections/live to fetch the current sections.

All preflight validation runs before any ETO row or Etsy draft is created — a 400 means nothing was persisted and retrying with a fixed payload is safe.

AuthorizationAPI keyoperation listing_create

Body parameters

state string

"draft" saves to ETO only (instant, zero Etsy calls). "publish" saves to ETO and creates a draft listing on Etsy (blocking, 5–15s per shop). "active" same as publish + activates on Etsy (blocking, costs $0.20 USD per listing per shop).

Defaultdraft

Enumdraftpublishactive

shops[].shop_id integer required >= 1

The unique positive non-zero numeric ID for an Etsy Shop. Must be connected to your ETO account. Use GET /api/v1/stores to list connected shops.

shops[].price number nullable >= 0.20

Per-shop price override in the shop's native currency. If omitted, uses listing.price.

shops[].shipping_profile_id integer nullable >= 1

The numeric ID of the shipping profile associated with the listing. Required when listing_type is physical. Get the latest IDs from GET /api/v1/stores/{shop_id}/shipping-profiles/live.

shops[].return_policy_id integer nullable >= 1

The numeric ID of the return policy. Required for physical listings. Get the latest IDs from GET /api/v1/stores/{shop_id}/return-policies/live.

shops[].processing_profile_id integer nullable >= 1

The numeric ID of the processing/readiness state profile. Controls processing time display on the listing. Get the latest IDs from GET /api/v1/stores/{shop_id}/processing-profiles/live.

shops[].shop_section_id integer nullable >= 1

The numeric ID of the shop section to organize the listing under. Get the latest IDs from GET /api/v1/stores/{shop_id}/shop-sections/live.

shops[].production_partner_ids array nullable

An array of unique IDs of production partners for this listing. Get IDs from POST /api/v1/stores/{shop_id}/sync.

listing.title string required max 140 chars

The listing's title string. Valid title strings contain only letters, numbers, punctuation marks, mathematical symbols, whitespace characters, ™, ©, and ®. You can only use the %, :, & and + characters once each.

Pattern/[^\p{L}\p{Nd}\p{P}\p{Sm}\p{Zs}™©®]/u

listing.description string required

A description string of the product for sale in the listing. Newlines are rendered by Etsy. HTML tags are stripped.

listing.listing_type string required

An enumerated type string that indicates whether the listing is a physical product or a digital download.

Enumphysicaldigital

listing.taxonomy_id integer required >= 1

The numerical taxonomy ID of the listing. Use GET /api/v1/categories/{id}/listing-schema to find valid IDs and discover required category attributes and variation properties.

listing.price number >= 0.20

The positive non-zero price of the product. Required unless variations define per-variant prices. Note: The price is the minimum possible price. Variation offerings can set different prices per combination.

listing.quantity integer 1-999

The positive non-zero number of products available for purchase. Required unless variations define per-variant quantities. Note: For variation listings, this is overridden by per-offering quantities.

listing.who_made string

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Defaulti_did

Enumi_didsomeone_elsecollective

listing.when_made string

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Default2020_2026

Enummade_to_order2020_20262010_20192007_2009before_20072000_20061990s1980s1970s1960s1950s1940s1930s1920s1910s1900s

listing.tags array nullable max 13 items, each max 20 chars

A list of tag strings for the listing. Valid tag strings contain only letters, numbers, whitespace characters, -, ', ™, ©, and ®. Default value is null.

Pattern/[^\p{L}\p{Nd}\p{Zs}\-'™©®]/u

listing.materials array nullable max 13 items

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. Default value is null.

Pattern/[^\p{L}\p{Nd}\p{Zs}]/u

listing.styles array nullable max 2 items

An array of style strings for this listing, each of which is free-form text string such as "Formal", or "Steampunk". Valid style strings contain only letters, numbers, and whitespace characters. Default value is null.

Pattern/[^\p{L}\p{Nd}\p{Zs}]/u

listing.sku string max 512 chars (32 to Etsy)

Optional internal identifier. First 32 characters are sent to Etsy (Etsy's limit). The full SKU (up to 512 chars) is stored in ETO for order fulfillment and can be retrieved via the ETO API.

listing.is_supply boolean

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

Defaultfalse

listing.is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

listing.is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

listing.should_auto_renew boolean

When true, renews a listing for four months upon expiration.

listing.item_weight number nullable > 0

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

listing.item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enumozlbgkg

listing.item_length number nullable > 0

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

listing.item_width number nullable > 0

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

listing.item_height number nullable > 0

The numeric height of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

listing.item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enuminftmmcmmydinches

listing.processing_min integer nullable

The minimum number of days required to process this listing. Default value is null.

listing.processing_max integer nullable

The maximum number of days required to process this listing. Default value is null.

images[].url string required min 1, max 10 images

A publicly accessible URL to the image file. ETO downloads the image server-side and uploads it to Etsy. Supported formats: JPG, PNG, GIF. Max 100MB per image.

images[].rank integer 1-10

Position in the listing image gallery. Rank 1 is the primary/leftmost photo shown to buyers. If omitted, images are ordered by their position in the array.

digital_files[].url string min 1, max 5 files (for digital listings)

A publicly accessible URL to the digital file. Required for listing_type=digital. ETO downloads the file server-side and uploads it to Etsy. Max 100MB per file. Supported types: .bmp, .doc, .gif, .jpeg, .jpg, .mobi, .mov, .mp3, .mpeg, .pdf, .png, .psp, .rtf, .stl, .txt, .zip, .ePUB, .iBook.

digital_files[].name string 3-70 chars

The display name for the digital file shown to buyers after purchase. Letters, numbers, periods, hyphens, and underscores only. No spaces or parentheses.

Pattern/^[a-zA-Z0-9._-]+$/

videos[].url string nullable max 1 video per listing

A publicly accessible URL to the video file. ETO downloads the video server-side and uploads it to Etsy. MP4 or MOV format, max 15 seconds, no audio. Max 100MB.

personalization.enabled boolean

When true, enables personalization for this listing. ETO uses the modern Etsy personalization API to set this up after listing creation.

Defaultfalse

personalization.is_required boolean

When true, the buyer must enter personalization text before purchasing. Only applies when personalization.enabled is true.

Defaultfalse

personalization.instructions string max 256 chars

Instructions shown to the buyer at checkout describing what personalization to enter (e.g. 'Enter up to 10 characters for monogram'). Only applies when personalization.enabled is true.

personalization.max_chars integer 1-1024

The maximum character count for the buyer's personalization message. Only applies when personalization.enabled is true.

category_attributes object

Category-specific listing attributes. Keys are property_id strings. Values are objects with value_ids, values, and optional scale_id. Use GET /api/v1/categories/{id}/listing-schema to discover which attributes exist, which are required, and their valid values for a given category.

category_attributes.{property_id}.value_ids array

The Etsy value IDs for the selected attribute values. Get valid IDs from the listing-schema endpoint possible_values array.

category_attributes.{property_id}.values array

Human-readable attribute value strings corresponding to each value_id.

category_attributes.{property_id}.scale_id integer nullable

Scale ID for properties that use scales (e.g. alpha sizing). Get valid scale IDs from the listing-schema endpoint scales array.

variations.properties array max 2 items

Array of variation property definitions. Etsy allows at most 2 variation properties per listing. Use GET /api/v1/categories/{id}/listing-schema variation_properties to discover available properties for the chosen category.

variations.properties[].property_id integer required

The Etsy property ID from the listing-schema variation_properties (e.g. 200 for Primary color, 100 for Size, 513 for Style).

variations.properties[].name string required

Human-readable property name (e.g. 'Color', 'Size'). This name (lowercased) is used as the key in each offering to specify the value.

variations.properties[].scale_id integer nullable

Scale ID for sized properties (e.g. Alpha sizing: XS, S, M, L, XL). Get valid scale IDs from the listing-schema endpoint.

variations.properties[].values array required

All possible values for this property (e.g. ['Black', 'Brown', 'Tan'] for Color). Parentheses characters () are not allowed in values.

variations.offerings array

Array of offerings, one per variation combination. Each offering uses the lowercased property name as a key to specify which value it represents. ETO auto-detects which properties affect price/quantity and builds the Etsy inventory payload accordingly.

variations.offerings[].{property_name} string required

The value for this property in this offering. The key is the lowercased property name (e.g. 'color': 'Black', 'size': 'S'). Must match one of the values listed in variations.properties[].values.

variations.offerings[].price number >= 0.20

Price for this specific variation combination. If all offerings have the same price, ETO automatically tells Etsy that price does not vary by property. If prices differ, ETO detects which property causes the difference.

variations.offerings[].quantity integer 0-999

Stock quantity for this specific variation combination. Set to 0 along with enabled=false to create the combination but hide it from the listing.

variations.offerings[].sku string nullable max 512 chars (32 to Etsy)

Per-variant SKU identifier. First 32 characters are sent to Etsy, full SKU (up to 512 chars) is stored in ETO. Must be unique across all offerings if provided.

variations.offerings[].enabled boolean

When false, the offering is created but hidden from the listing. Etsy receives is_enabled=false and quantity=0. Useful for pre-creating combinations that are temporarily out of stock.

Defaulttrue

variations.offerings[].processing_profile_id integer nullable >= 1

Per-variant processing/readiness profile ID. If different values are set across offerings, ETO automatically sets readiness_state_on_property. If omitted, the shop-level processing_profile_id applies.

variations.variation_images.property string

The name of the variation property whose values should be linked to specific listing images (e.g. 'color'). Only one property can have variation images per listing (Etsy constraint). Case-insensitive match against variations.properties[].name.

variations.variation_images.mapping object

Maps property values to image indices. Keys are value names (e.g. 'Black'), values are 0-based indices into the images[] array. Example: {"Black": 0, "Brown": 1, "Tan": 2}. If a value references an out-of-bounds index, validation returns an error.

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" \
  "https://eto.tools/api/v1/listings/create" \
  -d '{
  "state": "draft",
  "shops": [{"shop_id": 12345678, "shipping_profile_id": 111222, "return_policy_id": 333444, "price": 24.99}],
  "listing": {
    "title": "Custom Leather Wallet - Personalized Gift for Him",
    "description": "Handmade genuine leather wallet with optional monogram...",
    "listing_type": "physical",
    "taxonomy_id": 2078,
    "price": 24.99,
    "quantity": 50,
    "who_made": "i_did",
    "when_made": "2020_2026",
    "tags": ["leather wallet", "personalized gift", "groomsmen gift"],
    "materials": ["leather", "thread"],
    "sku": "WALLET-CUSTOM-001",
    "item_weight": 4.5,
    "item_weight_unit": "oz"
  },
  "images": [
    {"url": "https://example.com/wallet-front.jpg", "rank": 1},
    {"url": "https://example.com/wallet-back.jpg", "rank": 2}
  ],
  "variations": {
    "properties": [
      {"property_id": 200, "name": "Color", "values": ["Black", "Brown", "Tan"]}
    ],
    "offerings": [
      {"color": "Black", "price": 24.99, "quantity": 50, "sku": "W-BLK"},
      {"color": "Brown", "price": 24.99, "quantity": 50, "sku": "W-BRN"},
      {"color": "Tan", "price": 27.99, "quantity": 30, "sku": "W-TAN"}
    ],
    "variation_images": {"property": "color", "mapping": {"Black": 0, "Brown": 1}}
  }
}'

Example response

json

# state="draft" — 201 Created
{
  "listing_pk": 1173,
  "status": "draft",
  "message": "Listing saved as draft in ETO. Open it in the ETO dashboard to review and publish.",
  "dashboard_url": "/dashboard/single-research/1173/"
}

# state="publish" or "active" — 200 OK, synchronous
{
  "job_id": "lcj_aDzKwnFW5sYHewZaPTduRw",
  "listing_pk": 1173,
  "status": "completed",
  "poll_url": "/api/v1/listings/create/lcj_aDzKwnFW5sYHewZaPTduRw",
  "dashboard_url": "/dashboard/single-research/1173/",
  "shops_count": 1,
  "results": [
    {
      "shop_id": "53081804",
      "status": "ok",
      "listing_id": 4489813117,
      "listing_url": "https://www.etsy.com/listing/4489813117",
      "currency_code": "GBP",
      "price": 24.99,
      "images": [
        {"listing_image_id": 5523110099001, "url_fullxfull": "https://i.etsystatic.com/...", "rank": 1},
        {"listing_image_id": 5523110099002, "url_fullxfull": "https://i.etsystatic.com/...", "rank": 2}
      ],
      "videos": []
    }
  ]
}

# For state="active", each succeeded shop also includes:
#   "activated": true, "activation_cost_usd": 0.20

# On per-shop failure (other shops may still succeed):
#   {"shop_id": "...", "status": "error", "error": "<reason>", "etsy_status": 400, "details": {...}}

#Poll listing creation job status

GEThttps://eto.tools/api/v1/listings/create/{job_id}

Returns the status and results of a listing-create job. Since publish/active now execute synchronously on the web, jobs are normally in "completed" state by the time any poll lands. This endpoint remains available for backwards compatibility and for clients that prefer the job-polling pattern. Returns per-shop results when the job completes, including listing IDs, Etsy URLs, and any per-shop warnings.

AuthorizationAPI keyoperation listing_create_status

Path parameters

job_id string required

The job_id returned by POST /api/v1/listings/create

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/create/lcj_abc123def456"

Example response

json

{
  "job_id": "lcj_aDzKwnFW5sYHewZaPTduRw",
  "status": "completed",
  "created_at": "2026-04-16T21:07:20.963219+00:00",
  "completed_at": "2026-04-16T21:07:28.245564+00:00",
  "results": [
    {
      "shop_id": "53081804",
      "status": "ok",
      "listing_id": 4489813117,
      "listing_url": "https://www.etsy.com/listing/4489813117",
      "currency_code": "GBP",
      "price": 24.99,
      "images": [
        {"listing_image_id": 5523110099001, "url_fullxfull": "https://i.etsystatic.com/...", "rank": 1}
      ],
      "videos": [],
      "warnings": [
        {"code": "recovery_update_failed", "fields": ["shop_section_id"], "reason": "Etsy rejected the section update"}
      ]
    }
  ]
}

# Terminal statuses: "completed" | "failed"
# On job-level failure: response also includes "error_message": "<reason>"

#Get cached store details (zero Etsy calls)

GEThttps://eto.tools/api/v1/stores/{shop_id}/details

Returns all cached data for a connected store: shop details, shipping profiles, shop sections. No Etsy API calls are made. Return policies, processing profiles, and production partners return null (not cached locally). Use POST /sync to fetch those.

AuthorizationAPI keyoperation store_details_cached

Path parameters

shop_id integer required

Your connected Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/details"

Example response

json

{
  "shop_id": "12345678",
  "shop_name": "MyShop",
  "currency_code": "USD",
  "shipping_from_country_iso": "US",
  "listing_active_count": 142,
  "review_average": 4.8,
  "review_count": 523,
  "is_vacation": false,
  "url": "https://www.etsy.com/shop/MyShop",
  "last_synced_at": "2026-04-10T14:30:00Z",
  "shipping_profiles": [
    {"shipping_profile_id": 111222, "title": "Standard Shipping", "min_processing_days": 1, "max_processing_days": 3, "primary_cost": "5.99", "currency_code": "USD"}
  ],
  "shop_sections": [
    {"shop_section_id": 44556, "title": "New Arrivals", "rank": 1, "active_listing_count": 15}
  ],
  "return_policies": null,
  "processing_profiles": null,
  "production_partners": null
}

#Sync store data from Etsy

POSThttps://eto.tools/api/v1/stores/{shop_id}/sync

Triggers a fresh pull from Etsy API for all store data (details, shipping profiles, sections, return policies, processing profiles, production partners). Caches what can be cached and returns the complete updated dataset. Costs ~5 Etsy API calls.

AuthorizationAPI keyoperation store_sync

Path parameters

shop_id integer required

Your connected Etsy shop ID

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/sync"

Example response

json

{
  "shop_id": "12345678",
  "shop_name": "MyShop",
  "currency_code": "USD",
  "last_synced_at": "2026-04-12T16:45:00Z",
  "shipping_profiles": [
    {"shipping_profile_id": 111222, "title": "Standard Shipping", "min_processing_days": 1, "max_processing_days": 3, "primary_cost": "5.99", "currency_code": "USD"}
  ],
  "shop_sections": [
    {"shop_section_id": 44556, "title": "New Arrivals", "rank": 1, "active_listing_count": 15}
  ],
  "return_policies": [
    {"return_policy_id": 333444, "accepts_returns": true, "accepts_exchanges": true, "return_deadline": 30}
  ],
  "processing_profiles": [
    {"readiness_state_id": 555666, "readiness_state": "ready_to_ship", "min_processing_days": 1, "max_processing_days": 3, "processing_days_display_label": "1-3 business days"}
  ],
  "production_partners": [
    {"production_partner_id": 999, "partner_name": "PrintCo", "location": "USA"}
  ]
}

#Upload a file (image, video, or digital file)

POSThttps://eto.tools/api/v1/uploads

Upload a local file to ETO for use in listing creation. Returns an eto-upload:// URL that you can use in images[].url, digital_files[].url, or videos[].url when calling POST /api/v1/listings/create. This is the way to use local files instead of remote URLs.

Send as multipart/form-data with a "file" field and optional "type" field.

AuthorizationAPI keyoperation file_upload

Body parameters

file file required max 100MB

The file to upload. Send as multipart/form-data.

type string

The type of file being uploaded.

Defaultimage

Enumimagevideodigital

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" \
  -F "file=@my_product_photo.jpg" \
  -F "type=image" \
  "https://eto.tools/api/v1/uploads"

Example response

json

{
  "url": "eto-upload:///path/to/uploaded/file.jpg",
  "filename": "my_product_photo.jpg",
  "size": 102400,
  "content_type": "image/jpeg",
  "type": "image",
  "note": "Use this url value in images[].url when calling POST /api/v1/listings/create."
}

#Search

#Search active Etsy listings

GEThttps://eto.tools/api/v1/listings/search

Search for active listings on Etsy by keyword. Returns paginated results with listing details.

AuthorizationAPI keyoperation listings_search

Query parameters

keywords string required

Search keywords

limit integer

Number of results (max 100)

Default25

offset integer

Pagination offset

Default0

sort_on string

Sort field: created, price, score

Defaultcreated

sort_order string

Sort order: asc, desc

Defaultdesc

min_price number

Minimum price filter

max_price number

Maximum price filter

category_id integer

Filter by product category ID (get IDs from /categories)

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/search?keywords=leather+wallet&limit=10"

Example response

json

{"count": 1000, "results": [{"listing_id": 123, "title": "...", "price": {"amount": 2999, "divisor": 100, "currency_code": "USD"}, ...}]}

#Listings

#Get listing details

GEThttps://eto.tools/api/v1/listings/{listing_id}

Retrieve detailed information about a specific listing including title, description, price, tags, materials, and more.

AuthorizationAPI keyoperation listing_detail

Path parameters

listing_id integer required

The Etsy listing ID

Query parameters

includes string

Comma-separated associations to include: Images, Shop, User, Translations, Inventory, Videos

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890?includes=Images,Shop"

#Delete a listing

DELETEhttps://eto.tools/api/v1/listings/{listing_id}

Permanently delete a listing you own. This action cannot be undone.

AuthorizationAPI key + connected storeoperation listing_delete

Path parameters

listing_id integer required

The Etsy listing ID to delete

Example request

shell

curl -X DELETE -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890"

#Get listing images

GEThttps://eto.tools/api/v1/listings/{listing_id}/images

Retrieve all images for a specific listing.

AuthorizationAPI keyoperation listing_images

Path parameters

listing_id integer required

The Etsy listing ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/images"

#Get listing reviews

GEThttps://eto.tools/api/v1/listings/{listing_id}/reviews

Retrieve reviews for a specific listing.

AuthorizationAPI keyoperation listing_reviews

Path parameters

listing_id integer required

The Etsy listing ID

Query parameters

limit integer

Number of reviews (max 100)

Default25

offset integer

Pagination offset

Default0

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/reviews?limit=5"

#Get listing inventory

GEThttps://eto.tools/api/v1/listings/{listing_id}/inventory

Retrieve inventory data (stock levels, variations, pricing) for a listing.

AuthorizationAPI keyoperation listing_inventory_get

Path parameters

listing_id integer required

The Etsy listing ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/inventory"

#Update listing inventory

PUThttps://eto.tools/api/v1/listings/{listing_id}/inventory

Update inventory, pricing, and variations for a listing you own.

AuthorizationAPI key + connected storeoperation listing_inventory_update

Path parameters

listing_id integer required

The Etsy listing ID

Example request

shell

curl -X PUT -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"products": [...]}' "https://eto.tools/api/v1/listings/1234567890/inventory"

#Get listing videos

GEThttps://eto.tools/api/v1/listings/{listing_id}/videos

Retrieve all videos for a specific listing.

AuthorizationAPI keyoperation listing_videos

Path parameters

listing_id integer required

The Etsy listing ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/videos"

#Manage listing personalization

GETPOSTDELETEhttps://eto.tools/api/v1/listings/{listing_id}/personalization

Get, create, or delete personalization questions for a listing. GET returns {personalization_questions: [...]} with up to 5 questions. POST replaces all questions. DELETE removes personalization entirely. Question types: text_input, dropdown, unlabeled_upload, labeled_upload. Max 1 file-upload question per listing. See the Listing Builder guide for full field constraints.

AuthorizationAPI key + connected storeoperation listing_personalization

Path parameters

listing_id integer required

The Etsy listing ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/personalization"

#Batch get listings

GEThttps://eto.tools/api/v1/listings/batch

Retrieve multiple listings in a single request.

AuthorizationAPI key + connected storeoperation listings_batch

Query parameters

listing_ids string required

Comma-separated listing IDs

includes string

Comma-separated associations: Images, Shop, User, Inventory

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/batch?listing_ids=123,456,789"

#Get a listing offering

GEThttps://eto.tools/api/v1/listings/{listing_id}/products/{product_id}/offerings/{offering_id}

Get pricing and availability for a specific product variation offering. Etsy docs: "Listing Offering".

AuthorizationAPI keyoperation listing_offering

Path parameters

listing_id integer required

The listing ID

product_id integer required

The product variant ID

offering_id integer required

The offering ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/products/555666777/offerings/888999000"

#Get a product variant

GEThttps://eto.tools/api/v1/listings/{listing_id}/inventory/products/{product_id}

Get a specific product variant (size/color combination) and its offerings. Etsy docs: "Listing Product".

AuthorizationAPI keyoperation listing_product

Path parameters

listing_id integer required

The listing ID

product_id integer required

The product variant ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/inventory/products/555666777"

#Shops

#Get shop details

GEThttps://eto.tools/api/v1/shops/{shop_id}

Retrieve detailed information about a shop including name, description, ratings, and listing counts.

AuthorizationAPI keyoperation shop_detail

Path parameters

shop_id integer required

The Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678"

#Get shop reviews

GEThttps://eto.tools/api/v1/shops/{shop_id}/reviews

Retrieve reviews for a specific shop.

AuthorizationAPI keyoperation shop_reviews

Path parameters

shop_id integer required

The Etsy shop ID

Query parameters

limit integer

Number of reviews (max 100)

Default25

offset integer

Pagination offset

Default0

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/reviews?limit=5"

#Get shop sections

GEThttps://eto.tools/api/v1/shops/{shop_id}/sections

Retrieve product sections for a shop.

AuthorizationAPI keyoperation shop_sections_get

Path parameters

shop_id integer required

The Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/sections"

#Create shop section

POSThttps://eto.tools/api/v1/shops/{shop_id}/sections

Create a new product section in your shop.

AuthorizationAPI key + connected storeoperation shop_sections_create

Path parameters

shop_id integer required

Your Etsy shop ID

Body parameters

title string required

Section title

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"title": "New Section"}' "https://eto.tools/api/v1/shops/12345678/sections"

#Update shop details

PUThttps://eto.tools/api/v1/shops/{shop_id}

Update your shop's title, announcement, or other settings. Etsy docs: "Update Shop".

AuthorizationAPI key + connected storeoperation shop_update

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -X PUT -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"title": "My Shop Name"}' "https://eto.tools/api/v1/shops/12345678"

#Search shops

GEThttps://eto.tools/api/v1/shops

Search for Etsy shops by name. Etsy docs: "Find Shops".

AuthorizationAPI keyoperation shop_search

Query parameters

shop_name string required

Shop name to search for

limit integer

Number of results (max 100)

Default25

offset integer

Pagination offset

Default0

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops?shop_name=handmade&limit=5"

#Get, update, or delete a section

GETPUTDELETEhttps://eto.tools/api/v1/shops/{shop_id}/sections/{section_id}

Manage a specific shop section. Etsy docs: "Shop Section".

AuthorizationAPI key + connected storeoperation shop_section_detail

Path parameters

shop_id integer required

Your Etsy shop ID

section_id integer required

The section ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/sections/12345"

#Get listings by section

GEThttps://eto.tools/api/v1/shops/{shop_id}/section-listings

Get all listings organized by shop section. Etsy docs: "Listings By Section".

AuthorizationAPI key + connected storeoperation section_listings

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/section-listings"

#Store Management

#List or create shop listings

GETPOSThttps://eto.tools/api/v1/shops/{shop_id}/listings

GET: Retrieve your shop listings. POST: Create a new draft listing.

AuthorizationAPI key + connected storeoperation shop_listings

Path parameters

shop_id integer required

Your Etsy shop ID

Query parameters

limit integer

Number of listings (max 100)

Default25

offset integer

Pagination offset

Default0

state string

Listing state: active, draft, inactive

Defaultactive

sort_on string

Sort field

Defaultcreated

sort_order string

Sort direction

Defaultdesc

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings?limit=10&state=active"

#Update a listing

PATCHhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}

Update properties of a listing you own.

AuthorizationAPI key + connected storeoperation shop_listing_update

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID to update

Example request

shell

curl -X PATCH -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"title": "Updated Title"}' "https://eto.tools/api/v1/shops/12345678/listings/1234567890"

#Get active listings only

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/active

Get only active (live) listings for your shop. Etsy docs: "Active Listings By Shop".

AuthorizationAPI key + connected storeoperation shop_active_listings

Path parameters

shop_id integer required

Your Etsy shop ID

Query parameters

limit integer

Number of results (max 100)

Default25

offset integer

Pagination offset

Default0

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/active?limit=10"

#Get featured listings

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/featured

Get listings featured on your shop's homepage. Etsy docs: "Featured Listings By Shop".

AuthorizationAPI key + connected storeoperation shop_featured_listings

Path parameters

shop_id integer required

Your Etsy shop ID

Query parameters

limit integer

Number of results (max 100)

Default25

offset integer

Pagination offset

Default0

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/featured?limit=5"

#Manage listing translations

GETPOSTPUThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/translations/{language}

Get, create, or update a listing translation for a specific language. Etsy docs: "Listing Translation".

AuthorizationAPI key + connected storeoperation listing_translation

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

language string required

Language code (e.g. "fr", "de", "es")

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/translations/fr"

#Finance

#Get all finance metrics

GEThttps://eto.tools/api/v1/finance/{shop_id}

Returns every financial metric for a store over a date range. Zero Etsy API calls — reads directly from the Eto database. Instant.

━━━ WHAT YOU GET BACK (always returned) ━━━

shop_id — the store shop_name — store display name currency — e.g. "GBP", "USD" start / end — the range you requested balance_cents — current store balance (latest ledger entry, not range-scoped) paid_out_cents — total deposited to bank in this range sales_count — number of sales gross_sales_cents — raw sale revenue before any deductions sales_cents — display sales value (gross - refunds - cancelled + remitted tax) fees_cents — total Etsy fees charged (negative number) ads_cents — total ad spend (negative number) refund_cents — total refunded to buyers cancelled_cents — total cancelled order amounts recoup_cents — Etsy recovering money from your balance remitted_tax_cents — sales tax / VAT remitted by Etsy (negative) gross_profit_cents — profit before COGS (gross + fees + ads + tax) cogs_cents — cost of goods sold (from your item costs in Eto) net_profit_cents — gross profit minus COGS

All amounts in cents. Divide by 100 for display. Negative = money out.

━━━ HOW TO PICK THE DATE WINDOW ━━━

EASIEST — pass period: today, yesterday, last_7_days, last_30_days, this_month, last_month. The server resolves it in the shop timezone (override with timezone). No timestamps, no math. Specific days — pass start_date / end_date as "YYYY-MM-DD" (inclusive). Advanced — pass raw start / end unix seconds (range is [start, end), max 366 days). The response echoes back a range object (exact start/end unix, start_local/end_local ISO, timezone, label) AND the current server time — so you never compute or guess dates, and never need a separate "what time is it" call. If the user means THEIR calendar day, pass their timezone. Any store — use any shop_id connected to your Eto account (GET /api/v1/stores to list them).

━━━ BREAKDOWNS (optional) ━━━

Add &breakdown= to get detailed sub-breakdowns. Combine with commas.

breakdown=fees — returns breakdown.fees with: listing, listing_credits, transaction, transaction_credits, processing, processing_credits, shipping, shipping_credits, vat_on_fees, vat_on_fees_credits, regulatory, regulatory_credits, other, total

breakdown=ads — returns breakdown.ads with: etsy_ads, offsite_ads, offsite_ads_credits, subscription, total

breakdown=sales — returns breakdown.sales with: gross_sales_cents, refund_cents, cancelled_cents, remitted_tax: { sales_tax, sales_tax_credits, vat_ep, vat_ep_credits, total }

breakdown=gross — same as sales (alias)

breakdown=profit — returns both breakdown.gross_profit and breakdown.net_profit: gross_profit: { gross_sales_cents, fees_cents, ads_cents, remitted_tax_cents, total } net_profit: { gross_profit_cents, cogs_cents, total }

Combine: &breakdown=fees,ads,profit returns all three at once. Omit entirely to get just the top-level numbers.

━━━ WHAT HAS BREAKDOWNS vs WHAT DOESN'T ━━━

HAS breakdown: fees, ads, sales/gross, profit NO breakdown: balance_cents, paid_out_cents, sales_count, refund_cents, cancelled_cents, recoup_cents, cogs_cents, remitted_tax_cents (some of these appear inside the sales or profit breakdown instead)

━━━ HOURLY BREAKDOWN (optional, single-day only) ━━━

Add &hourly=true to get a per-hour breakdown alongside the day summary. Only works when your range is 24 hours or less (single day). If your range is longer than 24h, hourly returns null with a note.

What you get: an "hourly" array with one object per hour, from hour 0 (midnight) up to the hour containing your end time.

Each hour object contains: hour — 0-23 (the hour index) hour_start — unix timestamp of this hour's start hour_end — unix timestamp of this hour's end entry_count — number of ledger entries in this hour sales_count — number of sales gross_sales_cents — raw revenue for this hour sales_cents — display sales (gross - refunds - cancelled + tax) fees_cents — Etsy fees charged this hour ads_cents — ad spend this hour remitted_tax_cents — tax remitted this hour refund_cents — refunds this hour cancelled_cents — cancellations this hour recoup_cents — Etsy recoupments this hour gross_profit_cents — profit before COGS cogs_cents — cost of goods sold this hour net_profit_cents — profit after COGS paid_out_cents — payouts this hour

Combine with breakdowns: &hourly=true&breakdown=fees,ads works fine. The hourly array gives per-hour summary metrics. The breakdown object gives sub-category detail for the FULL day.

Turn it off: just omit &hourly (default is off). No penalty for not using it. Multi-day range: hourly is ignored (returns null + hourly_note explaining why).

AuthorizationAPI keyoperation finance

Path parameters

shop_id integer required

Your Etsy shop ID (from GET /api/v1/stores)

Query parameters

period string

EASIEST — a named window the server resolves for you, no timestamps: today, yesterday, last_7_days, last_30_days, this_month, last_month.

start_date string

Calendar day "YYYY-MM-DD" (inclusive). Use with end_date for a custom range.

end_date string

Calendar day "YYYY-MM-DD" (inclusive). Defaults to start_date (single day).

timezone string

IANA timezone for resolving period/dates (e.g. "Europe/London", "America/New_York"). Defaults to the shop's local timezone. Pass the USER's timezone (e.g. Europe/Helsinki) if they mean their own calendar day.

start integer

Advanced: raw range start as unix seconds (inclusive). Prefer period/start_date.

end integer

Advanced: raw range end as unix seconds (exclusive, max 366 days). Prefer period/start_date.

breakdown string

Comma-separated breakdowns to include: fees, ads, sales, gross, profit. Omit for top-level numbers only.

hourly string

Set to "true" to get per-hour metrics. Only works for single-day queries (range ≤ 24h). Returns array of 24 hour objects. Default: off.

Example request

shell

# ── All metrics for a period (no breakdown) ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1717113600"

# ── All metrics for a single day ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1716595200"

# ── All metrics + fee breakdown ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1717113600&breakdown=fees"

# ── All metrics + ads breakdown ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1717113600&breakdown=ads"

# ── All metrics + profit breakdown (shows gross + net) ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1717113600&breakdown=profit"

# ── All metrics + sales/tax breakdown ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1717113600&breakdown=sales"

# ── All metrics + EVERY breakdown combined ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1717113600&breakdown=fees,ads,sales,profit"

# ── Single day + fee and ads breakdown ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1716595200&breakdown=fees,ads"

# ── Single day + hourly breakdown (per-hour metrics) ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1716595200&hourly=true"

# ── Single day + hourly + fee breakdown (combine both) ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678?start=1716508800&end=1716595200&hourly=true&breakdown=fees"

Example response

json

// ── Response WITHOUT breakdown ──
{
  "shop_id": "12345678",
  "shop_name": "My Etsy Shop",
  "currency": "GBP",
  "start": 1716508800,
  "end": 1717113600,
  "balance_cents": 125430,
  "paid_out_cents": 90000,
  "sales_count": 15,
  "gross_sales_cents": 125000,
  "sales_cents": 120000,
  "fees_cents": -15000,
  "ads_cents": -5000,
  "refund_cents": 8000,
  "cancelled_cents": 2000,
  "recoup_cents": 0,
  "remitted_tax_cents": -3000,
  "gross_profit_cents": 102000,
  "cogs_cents": 30000,
  "net_profit_cents": 72000
}

// ── Response WITH breakdown=fees,ads,sales,profit ──
{
  "shop_id": "12345678",
  "shop_name": "My Etsy Shop",
  "currency": "GBP",
  "start": 1716508800,
  "end": 1717113600,
  "balance_cents": 125430,
  "paid_out_cents": 90000,
  "sales_count": 15,
  "gross_sales_cents": 125000,
  "sales_cents": 120000,
  "fees_cents": -15000,
  "ads_cents": -5000,
  "refund_cents": 8000,
  "cancelled_cents": 2000,
  "recoup_cents": 0,
  "remitted_tax_cents": -3000,
  "gross_profit_cents": 102000,
  "cogs_cents": 30000,
  "net_profit_cents": 72000,
  "breakdown": {
    "fees": {
      "listing": -400,
      "listing_credits": 40,
      "transaction": -8125,
      "transaction_credits": 325,
      "processing": -4800,
      "processing_credits": 192,
      "shipping": -650,
      "shipping_credits": 0,
      "vat_on_fees": -1200,
      "vat_on_fees_credits": 0,
      "regulatory": -500,
      "regulatory_credits": 0,
      "other": 0,
      "total": -15118
    },
    "ads": {
      "etsy_ads": -3000,
      "offsite_ads": -1500,
      "offsite_ads_credits": 0,
      "subscription": -999,
      "total": -5499
    },
    "sales": {
      "gross_sales_cents": 125000,
      "refund_cents": 8000,
      "cancelled_cents": 2000,
      "remitted_tax": {
        "sales_tax": -2000,
        "sales_tax_credits": 200,
        "vat_ep": -1200,
        "vat_ep_credits": 0,
        "total": -3000
      }
    },
    "gross_profit": {
      "gross_sales_cents": 125000,
      "fees_cents": -15000,
      "ads_cents": -5000,
      "remitted_tax_cents": -3000,
      "total": 102000
    },
    "net_profit": {
      "gross_profit_cents": 102000,
      "cogs_cents": 30000,
      "total": 72000
    }
  }
}

// ── Response WITH hourly=true (single day) ──
{
  "shop_id": "12345678",
  "shop_name": "My Etsy Shop",
  "currency": "GBP",
  "start": 1716508800,
  "end": 1716595200,
  "balance_cents": 125430,
  "paid_out_cents": 12000,
  "sales_count": 5,
  "gross_sales_cents": 45000,
  "sales_cents": 43500,
  "fees_cents": -5400,
  "ads_cents": -1200,
  "refund_cents": 1500,
  "cancelled_cents": 0,
  "recoup_cents": 0,
  "remitted_tax_cents": 0,
  "gross_profit_cents": 38400,
  "cogs_cents": 10000,
  "net_profit_cents": 28400,
  "hourly": [
    {
      "hour": 0,
      "hour_start": 1716508800,
      "hour_end": 1716512400,
      "entry_count": 0,
      "sales_count": 0,
      "gross_sales_cents": 0,
      "sales_cents": 0,
      "fees_cents": 0,
      "ads_cents": 0,
      "remitted_tax_cents": 0,
      "refund_cents": 0,
      "cancelled_cents": 0,
      "recoup_cents": 0,
      "gross_profit_cents": 0,
      "cogs_cents": 0,
      "net_profit_cents": 0,
      "paid_out_cents": 0
    },
    { "hour": 1, "..." : "..." },
    { "hour": 2, "..." : "..." },
    "... (hours 3-8 omitted for brevity) ...",
    {
      "hour": 9,
      "hour_start": 1716541200,
      "hour_end": 1716544800,
      "entry_count": 4,
      "sales_count": 2,
      "gross_sales_cents": 18000,
      "sales_cents": 18000,
      "fees_cents": -2160,
      "ads_cents": -600,
      "remitted_tax_cents": 0,
      "refund_cents": 0,
      "cancelled_cents": 0,
      "recoup_cents": 0,
      "gross_profit_cents": 15240,
      "cogs_cents": 4000,
      "net_profit_cents": 11240,
      "paid_out_cents": 0
    },
    "... (hours 10-23) ..."
  ]
}

#Re-fetch finance data from Etsy

POSThttps://eto.tools/api/v1/finance/{shop_id}/sync

Re-fetches ledger data from the Etsy API and saves it to the Eto database. After syncing, GET /finance/{shop_id} returns the updated numbers.

━━━ MODES ━━━

EASIEST — send { "period": "today" } (or yesterday/last_7_days/last_30_days/this_month/last_month), or { "date": "2026-06-01" }, or { "start_date": "...", "end_date": "..." }. The server resolves the window (shop timezone, override with "timezone") and re-fetches it — no unix math. Single day → day mode, multi-day → range mode. The response echoes a range object with the exact window + server time.

1. Incremental — send empty body or {}. Fetches only new entries since last sync. Fast, safe to call often. Use for: keeping data fresh on a schedule (e.g. every 15 min). Returns: new_entries, total_fetched, affected_days.

2. Single day — send { "day_start": unix_ts }. Re-fetches ALL entries for that day. Replaces stale data. Optionally include day_end (defaults to day_start + 86399). Use for: a day that looks wrong or incomplete. Returns: day_start, day_end, new_entries, total_fetched.

3. Date range — send { "start": unix_ts, "end": unix_ts }. Deletes existing entries in the range, re-fetches from Etsy, recomputes summaries. Use for: full reconciliation of a period. Heaviest mode. Returns: start, end, deleted_stale, new_entries.

━━━ WHAT YOU GET BACK ━━━

success — true if sync completed mode — "incremental", "day", or "range" new_entries — number of new ledger entries saved total_fetched — total entries fetched from Etsy (incremental + day modes) affected_days — list of day timestamps that had changes (incremental mode only) deleted_stale — entries deleted before re-fetch (range mode only) day_start / day_end — the day that was synced (day mode only) start / end — the range that was synced (range mode only)

━━━ NOTES ━━━

This is the ONLY finance endpoint that makes Etsy API calls. Counts toward your Eto rate limit AND Etsy API cost billing. If the store's OAuth token expired, returns STORE_TOKEN_EXPIRED. If Etsy's API is down, returns UPSTREAM_ERROR with detail.

AuthorizationAPI keyoperation finance_sync

Path parameters

shop_id integer required

Your Etsy shop ID

Body parameters

period string

EASIEST — resolve a window server-side and re-fetch it: today, yesterday, last_7_days, last_30_days, this_month, last_month. No timestamps.

date string

Re-fetch one calendar day "YYYY-MM-DD" (resolved in the shop/timezone).

start_date string

Range mode — first day "YYYY-MM-DD" (inclusive).

end_date string

Range mode — last day "YYYY-MM-DD" (inclusive).

timezone string

IANA timezone for resolving period/date (default: shop timezone).

day_start integer

Advanced single-day mode — unix timestamp of the day start.

day_end integer

Advanced single-day mode — unix timestamp of the day end (default: day_start + 86399).

start integer

Advanced range mode — start of range to re-fetch (unix seconds).

end integer

Advanced range mode — end of range to re-fetch (unix seconds).

Example request

shell

# ── Incremental sync (get latest entries) ──
curl -X POST -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/12345678/sync"

# ── Re-fetch a single day ──
curl -X POST -H "X-Eto-API-Key: eto_your_key" \
  -H "Content-Type: application/json" \
  -d '{"day_start": 1716508800}' \
  "https://eto.tools/api/v1/finance/12345678/sync"

# ── Re-fetch a single day with explicit end ──
curl -X POST -H "X-Eto-API-Key: eto_your_key" \
  -H "Content-Type: application/json" \
  -d '{"day_start": 1716508800, "day_end": 1716595199}' \
  "https://eto.tools/api/v1/finance/12345678/sync"

# ── Re-fetch an entire date range ──
curl -X POST -H "X-Eto-API-Key: eto_your_key" \
  -H "Content-Type: application/json" \
  -d '{"start": 1716508800, "end": 1717113600}' \
  "https://eto.tools/api/v1/finance/12345678/sync"

Example response

json

// ── Incremental ──
{
  "success": true,
  "mode": "incremental",
  "new_entries": 12,
  "total_fetched": 15,
  "affected_days": [1716508800, 1716595200]
}

// ── Single day ──
{
  "success": true,
  "mode": "day",
  "day_start": 1716508800,
  "day_end": 1716595199,
  "new_entries": 22,
  "total_fetched": 22
}

// ── Date range ──
{
  "success": true,
  "mode": "range",
  "start": 1716508800,
  "end": 1717113600,
  "deleted_stale": 145,
  "new_entries": 152
}

#Get logged software expenses (subscriptions)

GEThttps://eto.tools/api/v1/finance/software-expenses

Returns the software expenses you logged on the Finance dashboard — the subscriptions under Finance → Settings → Subscriptions (Canva, Printify, Eto, …) — and exactly what they cost inside a date window. The same numbers as the dashboard's "Software Expense" card and its breakdown. Zero Etsy API calls — reads from the Eto database. Instant.

These are ACCOUNT-level, not per shop, so they are NOT included in GET /finance/{shop_id}. To get profit after software, subtract total_cents from the shop's net_profit_cents.

━━━ WHAT YOU GET BACK (always returned) ━━━

start / end — the resolved window (unix seconds) range — exact window: timezone, local-ISO bounds, label, server time currency — the currency total_cents is in: your common currency from Finance settings, else the single currency all subscriptions share, else null (mixed) common_currency — the common currency configured in Finance → Settings, or null total_cents — everything charged inside the window, converted to currency totals_by_currency — { "USD": 2598, "GBP": 999 } raw sums per native currency charge_count — number of individual charges inside the window subscription_count — number of subscriptions logged (all of them, not just active in window) subscriptions[] — one entry per logged subscription: id, name, amount_cents, currency, frequency (weekly | biweekly | monthly | onetime), start_date (YYYY-MM-DD), conversion_rate (native → common), amount_converted_cents, charges_in_range, total_in_range_cents (converted), next_charge_date (YYYY-MM-DD or null), issue (only present when the entry is broken and never bills — e.g. missing amount/date) scope — reminder that these are account-level costs, not per shop warnings[] — caveats, e.g. mixed currencies with no common currency set hint — only when nothing is logged yet, with where to add subscriptions

All amounts are COSTS (money out) returned as POSITIVE cents. Divide by 100 for display.

━━━ HOW CHARGES ARE COUNTED ━━━

Each subscription bills from its start_date on its schedule: weekly every 7 days, biweekly every 14, monthly on the same day each month (clamped to shorter months — the 31st bills on the 30th/28th), onetime exactly once on start_date. A charge is counted when its calendar date falls inside the window. So "this month" for a $12.99 monthly subscription started on the 15th is 1299 cents; "last_7_days" may be 0 if the billing day is not in that week. Identical to the dashboard.

━━━ HOW TO PICK THE DATE WINDOW ━━━

EASIEST — pass period=this_month (the default), today, yesterday, last_7_days, last_30_days or last_month. Or start_date=YYYY-MM-DD & end_date=YYYY-MM-DD (inclusive calendar days). Add timezone=Europe/London to resolve the window in a specific zone — the default is your primary connected shop's timezone, else UTC. Raw unix start/end are accepted too (max 366 days). The response echoes the resolved window in range, so you never have to guess which days were counted.

━━━ OPTIONAL ━━━

include=charges — also return charges[]: every individual charge inside the window (date, subscription_id, name, frequency, amount_cents, currency, converted_cents), sorted by date. charges_truncated is true if the list was cut at 2,000 entries (totals are always complete).

━━━ NOTES ━━━

Read-only. Subscriptions are added and edited on the Finance dashboard (eto.tools/dashboard/finances → Settings → Subscriptions). Only YOUR account's subscriptions are ever returned — there is no id to look up. An empty subscriptions[] with total_cents 0 is a valid answer: nothing is logged yet (the response carries a hint saying so).

AuthorizationAPI keyoperation finance_software_expenses

Query parameters

period string

EASIEST — today, yesterday, last_7_days, last_30_days, this_month, last_month. Resolved server-side. Default: this_month.

Defaultthis_month

start_date string

First calendar day "YYYY-MM-DD" (inclusive).

end_date string

Last calendar day "YYYY-MM-DD" (inclusive). Defaults to start_date.

timezone string

IANA timezone used to resolve period/dates into calendar days (default: your primary connected shop's timezone, else UTC).

include string

Set to "charges" to also list every individual charge in the window.

start integer

Advanced — unix timestamp, range start (inclusive). Prefer period/start_date.

end integer

Advanced — unix timestamp, range end (exclusive). Prefer period/end_date.

Example request

shell

# ── This month (default) ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/software-expenses"

# ── Last month ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/software-expenses?period=last_month"

# ── A specific window, in your own timezone ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/software-expenses?start_date=2026-07-01&end_date=2026-07-31&timezone=Europe/London"

# ── This month + every individual charge ──
curl -H "X-Eto-API-Key: eto_your_key" \
  "https://eto.tools/api/v1/finance/software-expenses?period=this_month&include=charges"

Example response

json

{
  "start": 1785542400,
  "end": 1788220800,
  "range": {
    "start": 1785542400,
    "end": 1788220800,
    "start_local": "2026-08-01T00:00:00+01:00",
    "end_local": "2026-09-01T00:00:00+01:00",
    "timezone": "Europe/London",
    "label": "this month (month-to-date)",
    "server_now_unix": 1787788800,
    "server_now_utc": "2026-08-23T00:00:00+00:00"
  },
  "currency": "GBP",
  "common_currency": "GBP",
  "total_cents": 2325,
  "totals_by_currency": { "USD": 1299, "GBP": 1299 },
  "charge_count": 2,
  "subscription_count": 3,
  "subscriptions": [
    {
      "id": "sub_1753000000000_ab12",
      "name": "Eto",
      "amount_cents": 1299,
      "currency": "GBP",
      "frequency": "monthly",
      "start_date": "2026-03-05",
      "conversion_rate": 1.0,
      "amount_converted_cents": 1299,
      "charges_in_range": 1,
      "total_in_range_cents": 1299,
      "next_charge_date": "2026-09-05"
    },
    {
      "id": "sub_1751000000000_cd34",
      "name": "Canva Pro",
      "amount_cents": 1299,
      "currency": "USD",
      "frequency": "monthly",
      "start_date": "2026-01-15",
      "conversion_rate": 0.79,
      "amount_converted_cents": 1026,
      "charges_in_range": 1,
      "total_in_range_cents": 1026,
      "next_charge_date": "2026-09-15"
    },
    {
      "id": "sub_1749000000000_ef56",
      "name": "Printify Premium",
      "amount_cents": 2499,
      "currency": "USD",
      "frequency": "monthly",
      "start_date": "2026-08-28",
      "conversion_rate": 0.79,
      "amount_converted_cents": 1974,
      "charges_in_range": 0,
      "total_in_range_cents": 0,
      "next_charge_date": "2026-08-28"
    }
  ],
  "scope": {
    "level": "account",
    "note": "Software expenses are logged per Eto account, not per shop, so they are NOT part of GET /api/v1/finance/{shop_id}. All amounts are costs (money out) returned as positive cents; subtract total_cents from a shop's net_profit_cents to get profit after software.",
    "manage_at": "https://eto.tools/dashboard/finances (Settings → Subscriptions)"
  },
  "warnings": []
}

// ── With include=charges (extra keys) ──
{
  "...": "...",
  "charges": [
    { "date": "2026-08-05", "subscription_id": "sub_1753000000000_ab12", "name": "Eto", "frequency": "monthly", "amount_cents": 1299, "currency": "GBP", "converted_cents": 1299 },
    { "date": "2026-08-15", "subscription_id": "sub_1751000000000_cd34", "name": "Canva Pro", "frequency": "monthly", "amount_cents": 1299, "currency": "USD", "converted_cents": 1026 }
  ],
  "charges_truncated": false
}

// ── Nothing logged yet ──
{
  "...": "...",
  "currency": null,
  "total_cents": 0,
  "subscription_count": 0,
  "subscriptions": [],
  "hint": "No software expenses are logged yet. Add them at eto.tools/dashboard/finances → Settings → Subscriptions and they will appear here."
}

#Images & Media

#Upload listing image

POSThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/images

Upload an image to a listing. Send as multipart/form-data with the image in the "image" field.

AuthorizationAPI key + connected storeoperation listing_image_upload

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

Body parameters

image file required

Image file (JPEG, PNG, GIF)

rank integer

Image display order (1-10)

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" -F "image=@photo.jpg" -F "rank=1" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/images"

#Delete listing image

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/images/{image_id}

Remove an image from a listing.

AuthorizationAPI key + connected storeoperation listing_image_delete

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

image_id integer required

The image ID to delete

Example request

shell

curl -X DELETE -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/images/987654321"

#Upload listing video

POSThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/videos

Upload a video to a listing.

AuthorizationAPI key + connected storeoperation listing_video_upload

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

Body parameters

video file required

Video file

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" -F "video=@clip.mp4" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/videos"

#Delete listing video

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/videos/{video_id}

Remove a video from a listing.

AuthorizationAPI key + connected storeoperation listing_video_delete

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

video_id integer required

The video ID to delete

Example request

shell

curl -X DELETE -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/videos/987654321"

#Manage variation images

GETPOSThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/variation-images

Get or upload images for listing variations.

AuthorizationAPI key + connected storeoperation listing_variation_images

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/variation-images"

#List or upload digital files

GETPOSThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/files

GET: List all digital files for a listing. POST: Upload a new digital file. Etsy docs: "Listing Files".

AuthorizationAPI key + connected storeoperation listing_file_upload

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

Body parameters

file file required

Digital file to upload

name string

Display name for the file

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" -F "file=@design.pdf" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/files"

#Get or delete a digital file

GETDELETEhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/files/{file_id}

Get details for or delete a specific digital file. Etsy docs: "Listing File".

AuthorizationAPI key + connected storeoperation listing_file_detail

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

file_id integer required

The file ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/files/987654321"

#Get a single image

GEThttps://eto.tools/api/v1/listings/{listing_id}/images/{image_id}

Get details for a specific listing image. Etsy docs: "Listing Image".

AuthorizationAPI keyoperation listing_image_detail

Path parameters

listing_id integer required

The listing ID

image_id integer required

The image ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/images/987654321"

#Get a single video

GEThttps://eto.tools/api/v1/listings/{listing_id}/videos/{video_id}

Get details for a specific listing video. Etsy docs: "Listing Video".

AuthorizationAPI keyoperation listing_video_detail

Path parameters

listing_id integer required

The listing ID

video_id integer required

The video ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/videos/987654321"

#Listing Properties

#Get or update listing property

GETPUThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/properties/{property_id}

Manage specific properties (like color, size) for a listing.

AuthorizationAPI key + connected storeoperation listing_property

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

property_id integer required

The property ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/properties/200"

#Get a listing property (public)

GEThttps://eto.tools/api/v1/listings/{listing_id}/properties/{property_id}

Get a specific property value for any listing. Etsy docs: "Listing Property".

AuthorizationAPI keyoperation listing_property_public

Path parameters

listing_id integer required

The listing ID

property_id integer required

The property ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/listings/1234567890/properties/200"

#Get all listing properties

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/properties

Get all properties for one of your listings. Etsy docs: "Listing Properties".

AuthorizationAPI key + connected storeoperation listing_properties_all

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/properties"

#Delete a listing property

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/properties/{property_id}

Remove a property value from your listing. Etsy docs: "Delete Listing Property".

AuthorizationAPI key + connected storeoperation listing_property_delete

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

property_id integer required

The property ID

Example request

shell

curl -X DELETE -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/properties/200"

#Shipping

#List or create shipping profiles

GETPOSThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles

GET: List all shipping profiles for your shop. POST: Create a new shipping profile.

AuthorizationAPI key + connected storeoperation shipping_profiles

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/shipping-profiles"

#Update or delete shipping profile

PUTDELETEhttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}

Update or delete a specific shipping profile.

AuthorizationAPI key + connected storeoperation shipping_profile_detail

Path parameters

shop_id integer required

Your Etsy shop ID

profile_id integer required

The shipping profile ID

Example request

shell

curl -X PUT -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"title": "Updated"}' "https://eto.tools/api/v1/shops/12345678/shipping-profiles/111222333"

#List or add shipping destinations

GETPOSThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/destinations

Get or add destination countries/regions for a shipping profile. Etsy docs: "Shipping Profile Destinations".

AuthorizationAPI key + connected storeoperation shipping_destinations

Path parameters

shop_id integer required

Your Etsy shop ID

profile_id integer required

The shipping profile ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/shipping-profiles/111222333/destinations"

#Update or delete a shipping destination

PUTDELETEhttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/destinations/{destination_id}

Manage a specific shipping destination. Etsy docs: "Shipping Profile Destination".

AuthorizationAPI key + connected storeoperation shipping_destination_detail

Path parameters

shop_id integer required

Your Etsy shop ID

profile_id integer required

The shipping profile ID

destination_id integer required

The destination ID

Example request

shell

curl -X PUT -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"primary_cost": 500}' "https://eto.tools/api/v1/shops/12345678/shipping-profiles/111222333/destinations/77777"

#List or add shipping upgrades

GETPOSThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/upgrades

Get or add shipping speed upgrades (e.g. express, priority). Etsy docs: "Shipping Profile Upgrades".

AuthorizationAPI key + connected storeoperation shipping_upgrades

Path parameters

shop_id integer required

Your Etsy shop ID

profile_id integer required

The shipping profile ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/shipping-profiles/111222333/upgrades"

#Get, update, or delete a shipping upgrade

GETPUTDELETEhttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/upgrades/{upgrade_id}

Manage a specific shipping speed upgrade. Etsy docs: "Shipping Profile Upgrade".

AuthorizationAPI key + connected storeoperation shipping_upgrade_detail

Path parameters

shop_id integer required

Your Etsy shop ID

profile_id integer required

The shipping profile ID

upgrade_id integer required

The upgrade ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/shipping-profiles/111222333/upgrades/88888"

#Get shipping carriers

GEThttps://eto.tools/api/v1/shipping-carriers

List all available shipping carriers (USPS, FedEx, DHL, etc.). Etsy docs: "Shipping Carriers".

AuthorizationAPI keyoperation shipping_carriers

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shipping-carriers"

#Categories

#Get product categories

GEThttps://eto.tools/api/v1/categories

Get the full product category tree (e.g. Jewelry, Clothing, Home Decor). Use category IDs when creating listings to place them in the right section. Etsy docs: "Seller Taxonomy Nodes".

AuthorizationAPI keyoperation categories

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/categories"

#Get category properties

GEThttps://eto.tools/api/v1/categories/{category_id}/properties

Get the required and optional fields for a category — like size, color, or material options that buyers can filter by. Etsy docs: "Taxonomy Node Properties".

AuthorizationAPI keyoperation category_properties

Path parameters

category_id integer required

The category ID (from /categories)

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/categories/1/properties"

#Get buyer categories

GEThttps://eto.tools/api/v1/buyer-categories

Get the category tree from a buyer's perspective — how shoppers browse Etsy. Etsy docs: "Buyer Taxonomy Nodes".

AuthorizationAPI keyoperation buyer_categories

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/buyer-categories"

#Get buyer category properties

GEThttps://eto.tools/api/v1/buyer-categories/{category_id}/properties

Get filterable properties for a buyer category. Etsy docs: "Buyer Taxonomy Properties".

AuthorizationAPI keyoperation buyer_category_properties

Path parameters

category_id integer required

The buyer category ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/buyer-categories/1/properties"

#User

#Get current user

GEThttps://eto.tools/api/v1/users/me

Retrieve the Etsy user profile for the authenticated store.

AuthorizationAPI key + connected storeoperation users_me

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/users/me"

#Get user shops

GEThttps://eto.tools/api/v1/users/{user_id}/shops

List shops owned by a specific user.

AuthorizationAPI key + connected storeoperation user_shops

Path parameters

user_id integer required

The Etsy user ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/users/123456789/shops"

#Get user profile

GEThttps://eto.tools/api/v1/users/{user_id}

Get a user's Etsy profile by ID. Etsy docs: "Get User".

AuthorizationAPI key + connected storeoperation user_profile

Path parameters

user_id integer required

The Etsy user ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/users/123456789"

#Shop Policies

#Get return policies

GEThttps://eto.tools/api/v1/shops/{shop_id}/return-policies

Retrieve return policy details for your shop.

AuthorizationAPI key + connected storeoperation shop_return_policies

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/return-policies"

#Get production partners

GEThttps://eto.tools/api/v1/shops/{shop_id}/production-partners

List production partners (e.g. print-on-demand services) for your shop.

AuthorizationAPI key + connected storeoperation shop_production_partners

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/production-partners"

#Listing requirements

GETPOSThttps://eto.tools/api/v1/shops/{shop_id}/listing-requirements

Get or create listing readiness requirements — the checklist items a listing must complete before going live. Etsy docs: "Readiness State Definitions".

AuthorizationAPI key + connected storeoperation shop_listing_requirements

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listing-requirements"

#Create return policy

POSThttps://eto.tools/api/v1/shops/{shop_id}/return-policies

Create a new return policy for your shop. Etsy docs: "Create Return Policy".

AuthorizationAPI key + connected storeoperation return_policy_create

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"accepts_returns": true, "return_deadline": 30}' "https://eto.tools/api/v1/shops/12345678/return-policies"

#Get, update, or delete a return policy

GETPUTDELETEhttps://eto.tools/api/v1/shops/{shop_id}/return-policies/{policy_id}

Manage a specific return policy. Etsy docs: "Shop Return Policy".

AuthorizationAPI key + connected storeoperation return_policy_detail

Path parameters

shop_id integer required

Your Etsy shop ID

policy_id integer required

The return policy ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/return-policies/54321"

#Consolidate return policies

POSThttps://eto.tools/api/v1/shops/{shop_id}/return-policies/consolidate

Merge multiple return policies into one. Etsy docs: "Consolidate Return Policies".

AuthorizationAPI key + connected storeoperation return_policy_consolidate

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/return-policies/consolidate"

#Get listings with a return policy

GEThttps://eto.tools/api/v1/shops/{shop_id}/return-policies/{policy_id}/listings

Get all listings that use a specific return policy. Etsy docs: "Listings By Return Policy".

AuthorizationAPI key + connected storeoperation return_policy_listings

Path parameters

shop_id integer required

Your Etsy shop ID

policy_id integer required

The return policy ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/return-policies/54321/listings"

#Get holiday preferences

GEThttps://eto.tools/api/v1/shops/{shop_id}/holiday-preferences

Get your shop's holiday settings (when you're on vacation). Etsy docs: "Holiday Preferences".

AuthorizationAPI key + connected storeoperation shop_holidays

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/holiday-preferences"

#Update a holiday preference

PUThttps://eto.tools/api/v1/shops/{shop_id}/holiday-preferences/{holiday_id}

Update vacation/holiday settings. Etsy docs: "Update Holiday Preferences".

AuthorizationAPI key + connected storeoperation shop_holiday_update

Path parameters

shop_id integer required

Your Etsy shop ID

holiday_id integer required

The holiday ID

Example request

shell

curl -X PUT -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"is_working": false}' "https://eto.tools/api/v1/shops/12345678/holiday-preferences/1"

#Get, update, or delete a listing requirement

GETPUTDELETEhttps://eto.tools/api/v1/shops/{shop_id}/listing-requirements/{requirement_id}

Manage a specific listing readiness requirement. Etsy docs: "Readiness State Definition".

AuthorizationAPI key + connected storeoperation listing_requirement_detail

Path parameters

shop_id integer required

Your Etsy shop ID

requirement_id integer required

The requirement ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listing-requirements/99999"

#Get current shipping profiles (live, no cache)

GEThttps://eto.tools/api/v1/stores/{shop_id}/shipping-profiles/live

Returns this shop's shipping profiles RIGHT NOW — fetched live from Etsy on every call, never from the local cache. Use this when you need the absolute latest IDs to put into shops[].shipping_profile_id when calling POST /api/v1/listings/create.

One Etsy API call per request. Response is a flat list — pick the shipping_profile_id you want.

AuthorizationAPI keyoperation shipping_profiles_live

Path parameters

shop_id integer required

Your connected Etsy shop ID. Get the list from GET /api/v1/stores.

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/shipping-profiles/live"

Example response

json

{
  "shop_id": "12345678",
  "fetched_at": "2026-04-19T14:30:00Z",
  "count": 2,
  "shipping_profiles": [
    {
      "shipping_profile_id": 291257702631,
      "title": "Standard Shipping",
      "min_processing_days": 1,
      "max_processing_days": 3,
      "processing_days_display_label": "1-3 business days",
      "origin_country_iso": "US",
      "origin_postal_code": "10001",
      "profile_type": "manual",
      "domestic_handling_fee": 0.00,
      "international_handling_fee": 0.00
    }
  ]
}

#Get current return policies (live, no cache)

GEThttps://eto.tools/api/v1/stores/{shop_id}/return-policies/live

Returns this shop's return policies RIGHT NOW — fetched live from Etsy on every call. No cache, no staleness. Use this to get the return_policy_id to plug into shops[].return_policy_id when calling POST /api/v1/listings/create.

One Etsy API call per request.

AuthorizationAPI keyoperation return_policies_live

Path parameters

shop_id integer required

Your connected Etsy shop ID.

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/return-policies/live"

Example response

json

{
  "shop_id": "12345678",
  "fetched_at": "2026-04-19T14:30:00Z",
  "count": 1,
  "return_policies": [
    {
      "return_policy_id": 1435074483195,
      "accepts_returns": true,
      "accepts_exchanges": true,
      "return_deadline": 30
    }
  ]
}

#Get current processing profiles (live, no cache)

GEThttps://eto.tools/api/v1/stores/{shop_id}/processing-profiles/live

Returns this shop's processing profiles (Etsy "readiness state definitions") RIGHT NOW — fetched live from Etsy on every call. No cache. Use this to get the processing_profile_id (a.k.a. readiness_state_id) for shops[].processing_profile_id when calling POST /api/v1/listings/create.

One Etsy API call per request.

AuthorizationAPI keyoperation processing_profiles_live

Path parameters

shop_id integer required

Your connected Etsy shop ID.

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/processing-profiles/live"

Example response

json

{
  "shop_id": "12345678",
  "fetched_at": "2026-04-19T14:30:00Z",
  "count": 1,
  "processing_profiles": [
    {
      "readiness_state_id": 1456101932490,
      "readiness_state": "ready_to_ship",
      "min_processing_days": 1,
      "max_processing_days": 3,
      "processing_days_display_label": "1-3 business days"
    }
  ]
}

#Get current shop sections (live, no cache)

GEThttps://eto.tools/api/v1/stores/{shop_id}/shop-sections/live

Returns this shop's sections RIGHT NOW — fetched live from Etsy on every call. No cache. Use this to get the shop_section_id to plug into shops[].shop_section_id when calling POST /api/v1/listings/create.

One Etsy API call per request.

AuthorizationAPI keyoperation shop_sections_live

Path parameters

shop_id integer required

Your connected Etsy shop ID.

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/stores/12345678/shop-sections/live"

Example response

json

{
  "shop_id": "12345678",
  "fetched_at": "2026-04-19T14:30:00Z",
  "count": 2,
  "shop_sections": [
    {
      "shop_section_id": 56909368,
      "title": "New Arrivals",
      "rank": 1,
      "user_id": 99887766,
      "active_listing_count": 15
    }
  ]
}

#Orders

#List shop orders

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders

Get all orders for your shop. Supports filtering by date and pagination. Etsy docs: "Shop Receipts".

AuthorizationAPI key + connected storeoperation shop_orders

Path parameters

shop_id integer required

Your Etsy shop ID

Query parameters

limit integer

Number of orders (max 100)

Default25

offset integer

Pagination offset

Default0

min_created integer

Earliest order date (unix seconds)

max_created integer

Latest order date (unix seconds)

sort_on string

Sort field

Defaultcreated

sort_order string

Sort direction

Defaultdesc

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/orders?limit=10"

#Get order details

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}

Get full details for a specific order including items, shipping, and payment info. Etsy docs: "Shop Receipt by ID".

AuthorizationAPI key + connected storeoperation shop_order_detail

Path parameters

shop_id integer required

Your Etsy shop ID

order_id integer required

The order ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/orders/3344556677"

#Update order tracking

POSThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}/tracking

Add or update tracking information for an order so the buyer can track their shipment. Etsy docs: "Receipt Tracking".

AuthorizationAPI key + connected storeoperation shop_order_tracking

Path parameters

shop_id integer required

Your Etsy shop ID

order_id integer required

The order ID

Body parameters

tracking_code string required

Tracking number

carrier_name string required

Shipping carrier name

Example request

shell

curl -X POST -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"tracking_code": "1Z999AA10123456784", "carrier_name": "ups"}' "https://eto.tools/api/v1/shops/12345678/orders/3344556677/tracking"

#Update an order

PUThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}/update

Update order details like notes or status. Etsy docs: "Update Shop Receipt".

AuthorizationAPI key + connected storeoperation order_update

Path parameters

shop_id integer required

Your Etsy shop ID

order_id integer required

The order ID

Example request

shell

curl -X PUT -H "X-Eto-API-Key: eto_your_key" -H "Content-Type: application/json" -d '{"was_shipped": true}' "https://eto.tools/api/v1/shops/12345678/orders/3344556677/update"

#Get listings in an order

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}/listings

Get the listings that were purchased in a specific order. Etsy docs: "Listings By Receipt".

AuthorizationAPI key + connected storeoperation order_listings

Path parameters

shop_id integer required

Your Etsy shop ID

order_id integer required

The order ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/orders/3344556677/listings"

#Get order payments

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}/payments

Get payment details for a specific order. Etsy docs: "Payment By Receipt ID".

AuthorizationAPI key + connected storeoperation order_payments

Path parameters

shop_id integer required

Your Etsy shop ID

order_id integer required

The order ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/orders/3344556677/payments"

#Finances

#Get financial transactions

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/transactions

Get all financial transactions — charges, fees, refunds, and deposits. This is your shop's payment ledger. Etsy docs: "Payment Account Ledger Entries".

AuthorizationAPI key + connected storeoperation shop_finance_transactions

Path parameters

shop_id integer required

Your Etsy shop ID

Query parameters

min_created integer

Earliest date (unix seconds)

max_created integer

Latest date (unix seconds)

limit integer

Number of results (max 100)

Default25

offset integer

Pagination offset

Default0

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/finance/transactions?limit=10"

#Get payment details

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/payments

Get detailed payment info for specific financial transactions. Etsy docs: "Ledger Entry Payments".

AuthorizationAPI key + connected storeoperation shop_finance_payments

Path parameters

shop_id integer required

Your Etsy shop ID

Query parameters

transaction_ids string required

Comma-separated transaction IDs

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/finance/payments?transaction_ids=123,456"

#Get sales history

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/sales

Get individual sale records — each item sold, its price, and the buyer. Etsy docs: "Shop Transactions".

AuthorizationAPI key + connected storeoperation shop_finance_sales

Path parameters

shop_id integer required

Your Etsy shop ID

Query parameters

limit integer

Number of sales (max 100)

Default25

offset integer

Pagination offset

Default0

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/finance/sales?limit=10"

#Get sales for a listing

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/sales

Get all sale transactions for a specific listing. Etsy docs: "Transactions By Listing".

AuthorizationAPI key + connected storeoperation listing_sales

Path parameters

shop_id integer required

Your Etsy shop ID

listing_id integer required

The listing ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/listings/1234567890/sales"

#Get transactions for an order

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}/transactions

Get individual sale items within a specific order. Etsy docs: "Transactions By Receipt".

AuthorizationAPI key + connected storeoperation order_transactions

Path parameters

shop_id integer required

Your Etsy shop ID

order_id integer required

The order ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/orders/3344556677/transactions"

#Get a single sale

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/sales/{transaction_id}

Get details for one specific sale transaction. Etsy docs: "Shop Receipt Transaction".

AuthorizationAPI key + connected storeoperation single_transaction

Path parameters

shop_id integer required

Your Etsy shop ID

transaction_id integer required

The transaction ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/finance/sales/4455667788"

#Get a single financial transaction

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/transactions/{entry_id}

Get details for one ledger entry. Etsy docs: "Ledger Entry".

AuthorizationAPI key + connected storeoperation single_ledger_entry

Path parameters

shop_id integer required

Your Etsy shop ID

entry_id integer required

The ledger entry ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/finance/transactions/9988776655"

#Get all payments

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/all-payments

Get all payment records for your shop. Etsy docs: "Shop Payments".

AuthorizationAPI key + connected storeoperation shop_all_payments

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/finance/all-payments"

#Analytics

#Shop views & favorites (lifetime)

GEThttps://eto.tools/api/v1/shops/{shop_id}/stats/traffic

Lifetime VIEWS and FAVORITES aggregated across your active listings, plus a top-listings-by-views leaderboard, total, and average. NOTE: Etsy's public API does not expose day-by-day traffic (Stats are dashboard-only), so these are cumulative figures, not per-day. No date range needed.

AuthorizationAPI key + connected storeoperation shop_traffic_stats

Path parameters

shop_id integer required

Your Etsy shop ID

Example request

shell

curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/shops/12345678/stats/traffic"

#Connected stores

Check store connection status. Stores must be connected via the Eto dashboard.

GET /api/v1/stores List connected stores

Returns all Etsy stores connected to your account.

Response

{
  "stores": [
    {
      "shop_id": "12345678",
      "shop_name": "My Etsy Shop",
      "is_connected": true,
      "token_valid": true,
      "connected_at": "2026-01-15T10:30:00Z"
    }
  ]
}

GET /api/v1/stores/{shop_id} Get store details

Get detailed status for a specific connected store.

Name	Type	Required	Description
shop_id	integer	REQUIRED	Your Etsy shop ID

#Eto orders

Access order data through Eto. Every call syncs latest orders from Etsy into Eto's database automatically.

GET /api/v1/orders/{shop_id} List orders (auto-sync)

Syncs latest orders from Etsy, then returns from Eto's database with enriched fields. Each order includes an inline profit object (with cogs_cents, fees_cents, net_profit_cents) read from Eto's materialized snapshot — so you get cost/profit for a whole page in one call instead of one extra call per order. profit is null when no snapshot exists yet (run /sync or finance_sync, then retry); call the detail endpoint for the full fees_breakdown.

Name	Type	Required	Description
shop_id	integer	REQUIRED	Your Etsy shop id, in the path.
period	string	optional	Named window, resolved in the shop’s timezone: `today`, `yesterday`, `last_7_days`, `last_30_days`, `this_month`, `last_month`.
start_date / end_date	string	optional	Calendar dates (`YYYY-MM-DD`), inclusive at both ends.
timezone	string	optional	IANA name (e.g. `Europe/London`) used to resolve the window. Defaults to the shop’s own timezone.
min_created / max_created	integer	optional	Raw Unix seconds, if you would rather compute the window yourself.
sort_on	string	optional	`created`, `updated` or `receipt_id` default: created
sort_order	string	optional	`asc` or `desc` default: desc
limit	integer	optional	Rows per page, clamped to 1–100 default: 25
offset	integer	optional	Rows to skip default: 0

With no date arguments at all you get the most recent orders. An unknown period or timezone is refused with INVALID_REQUEST and a hint naming the accepted values.

Example

curl -H "X-Eto-API-Key: eto_your_key" \
     "https://eto.tools/api/v1/orders/12345678?period=last_7_days&limit=25"

Response

{
  "count": 128,
  "results": [
    {
      "receipt_id": 987654321,
      "created_timestamp": 1717150000,
      "created_iso": "2026-05-31T10:26:40+00:00",
      "created_local": "2026-05-31T11:26:40+01:00",
      "profit": {
        "currency": "USD",
        "gross_sales_cents": 2599,
        "fees_cents": 412,
        "gross_profit_cents": 2187,
        "cogs_cents": 800,
        "net_profit_cents": 1387,
        "has_refund": false
      }
    }
  ],
  "timezone": "Europe/London",
  "profit_note": "Each order's `profit` is its own gross sale minus its own fees and COGS…",
  "server_now_unix": 1788720109,
  "server_now_utc": "2026-09-06T18:41:49+00:00",
  "range": { "start": 1788134400, "end": 1788739200, "label": "last 7 days" }
}

Every field Etsy returns on a receipt is passed through untouched; the fields above are the ones Eto adds. range appears only when you asked for a window.

GET/api/v1/orders/{shop_id}/{receipt_id}Order detail

Full order detail for one Etsy receipt: line items, shipments, refunds and the fees_breakdown behind the profit figure. receipt_id is Etsy’s receipt id, the same value the list endpoint returns.

POST/api/v1/orders/{shop_id}/syncForce sync

Manually trigger an Etsy → Eto order sync.

#Product hunt

Take your list of Etsy listings and let Eto add the one signal you can't get from the raw Etsy API: demand_24h — how many units were bought in the last 24 hours. You bring the listings, we add the demand.

Stateless — nothing is saved. Synchronous — waits and returns all results in one response (~30-90 seconds).

POST /api/v1/product-hunt Add demand signal to your listings

Three input modes — choose based on what you have:

Mode S — You give us a search term, we fetch & rank easiest

Send just a keyword (no listing IDs needed) and a few settings. Eto will:

Search Etsy for that term and collect up to amount products (optionally age-filtered)
Extract demand_24h for each — the popularity signal
Rank them: by demand, or — with optimized — AI-scored by opportunity (adds ai_score + ai_reason)
Return the ranked array

Use when: you only know a search term and want the same thing the Product Hunt page gives you.

Mode A — You give us IDs, we do everything

Send just a list of Etsy listing IDs. Eto will:

Fetch full details for every listing (title, price, shop info, tags, etc.)
Extract demand_24h (units bought in last 24h)
Return a fully enriched array

Use when: You only have listing IDs (e.g. from our Etsy search endpoint) and want the complete picture.

Mode B — You give us full data, we just add demand

Send your existing listing objects (whatever fields you already have). Eto will:

Extract demand_24h for each listing
Return your original objects with demand_24h added

Use when: You already have full listing data (from Etsy's API or our proxy) and just need the demand signal Etsy doesn't publicly expose.

Parameters

Name	Type	Required	Description
keyword	string	REQUIRED	Search term (max 200 chars). In Modes A/B it's context for popular detection; in Mode S it's the actual search query.
amount	integer	Mode S	Search: how many products to fetch & rank. 1–100, default 50.
max_listing_age	integer	Mode S	Search: only listings created within the last N months. 0 or omit = no limit (max 60).
optimized	boolean	Mode S	Search: AI-powered filtering & ranking. Results carry `ai_score` + `ai_reason` and are sorted by score. When true, `full_details` is ignored.
full_details	boolean	Mode S	Search (only when `optimized` is false): `true` returns full per-listing details; `false` returns `listing_id` + `demand_24h` only (lightest & cheapest).
listing_ids	array<int>	either/or	Mode A: Array of listing IDs (max 500). Eto will fetch everything.
listings	array<object>	either/or	Mode B: Array of listing objects with at minimum `listing_id`. Your fields are preserved and signals are added.

Omit both listing_ids and listings to run a Mode S search. Otherwise provide either listing_ids or listings — not both. Max 500 listings (Modes A/B) / 100 products (Mode S) per request.

Mode S Example — "I have a search term, find & rank for me"

curl -X POST -H "X-Eto-API-Key: eto_your_key" \
     -H "Content-Type: application/json" \
     -d '{
       "keyword": "shirt",
       "amount": 100,
       "max_listing_age": 6,
       "optimized": true
     }' \
     "https://eto.tools/api/v1/product-hunt"

Mode S Response

{
  "keyword": "shirt",
  "mode": "search",
  "params": {"amount": 100, "max_listing_age": 6, "optimized": true, "full_details": false},
  "total_results": 100,
  "results": [
    {
      "listing_id": 4472965081,
      "title": "Rad Dad Society Shirt, Cool Dad Club Tee",
      "price": {"amount": 1665, "divisor": 100, "currency_code": "USD"},
      "views": 5511,
      "favorites": 436,
      "demand_24h": 21,
      "listing_age_days": 77,
      "shop_name": "CozyPrintsClothing",
      "shop_sales": 72995,
      "shop_age_days": 1421,
      "ai_score": 88,
      "ai_reason": "Exceptional demand on a proven shop; strong fav rate."
    }
    // ...ranked by ai_score (optimized) or demand_24h
  ]
}

Mode A Example — "I have IDs, give me everything"

curl -X POST -H "X-Eto-API-Key: eto_your_key" \
     -H "Content-Type: application/json" \
     -d '{
       "keyword": "leather wallet",
       "listing_ids": [1234567890, 9876543210, 1122334455]
     }' \
     "https://eto.tools/api/v1/product-hunt"

Mode A Response

{
  "keyword": "leather wallet",
  "mode": "ids_to_full",
  "total_input": 3,
  "total_results": 3,
  "results": [
    {
      "listing_id": 1234567890,
      "title": "Handmade Leather Bifold Wallet",
      "description": "Beautiful handmade leather...",
      "price": {"amount": 2499, "divisor": 100, "currency_code": "USD"},
      "quantity": 50,
      "views": 3240,
      "favorites": 145,
      "demand_24h": 5,
      "is_digital": false,
      "listing_type": "physical",
      "has_variations": true,
      "tags": ["wallet", "leather", "gift"],
      "materials": ["leather", "thread"],
      "created_timestamp": 1500000000,
      "listing_age_days": 850,
      "shop_name": "LeatherCraftCo",
      "shop_sales": 2340,
      "shop_age_days": 1200,
      "shipping_origin_country": "US"
    }
  ]
}

Mode B Example — "I have full data, just add signals"

curl -X POST -H "X-Eto-API-Key: eto_your_key" \
     -H "Content-Type: application/json" \
     -d '{
       "keyword": "leather wallet",
       "listings": [
         {
           "listing_id": 1234567890,
           "title": "My Wallet",
           "price": 24.99,
           "my_custom_field": "whatever"
         },
         {
           "listing_id": 9876543210,
           "title": "Another Wallet"
         }
       ]
     }' \
     "https://eto.tools/api/v1/product-hunt"

Mode B Response

Your original listing objects are returned with only demand_24h added. Any custom fields you sent are preserved:

{
  "keyword": "leather wallet",
  "mode": "data_to_signals",
  "total_input": 2,
  "total_results": 2,
  "results": [
    {
      "listing_id": 1234567890,
      "title": "My Wallet",
      "price": 24.99,
      "my_custom_field": "whatever",
      "demand_24h": 5
    },
    {
      "listing_id": 9876543210,
      "title": "Another Wallet",
      "demand_24h": null
    }
  ]
}

Field Definitions

Field	Type	Description
demand_24h	integer\|null	Units bought in the last 24 hours. `null` if demand couldn't be extracted (e.g. listing unavailable). Added by Eto in both modes.
listing_id	integer	Etsy listing ID
title	string	Listing title (Mode A only, from Etsy API)
description	string	First 500 chars of description (Mode A)
price	object	Price as `{amount, divisor, currency_code}` (Mode A)
views	integer	Total listing views (Mode A)
favorites	integer	Users who favorited this (Mode A)
listing_age_days	integer	Days since first created (Mode A)
shop_name	string	Shop name (Mode A)
shop_sales	integer	Total sales by this shop (Mode A)
shop_age_days	integer	Days since shop created (Mode A)
tags	array	Listing keywords (Mode A)
materials	array	Materials used (Mode A)

Edge Cases

Scenario	Behavior
Both listing_ids and listings sent	Error — pick one.
Neither listing_ids nor listings	Error — must provide one.
More than 500 items	Error — max 500 per request.
Listing in Mode A has no details on Etsy (deleted)	Returns `{"listing_id": X, "error": "enrichment_failed", "demand_24h": null}`
Demand extraction fails for a listing	`demand_24h: null` for that specific listing.
Empty keyword	Error returned.
Mode B listing missing `listing_id`	Error returned.

#AI studio

Generate titles, descriptions and product copy with your own AI credentials. Every AI request must name a provider in the JSON body, and the credentials for it come from your account, not from the request. Add them at eto.tools/settings.

Provider Options

Provider	Value	Setup Required
Gemini API Key	`"gemini"`	Add your Google AI Studio API key in settings
Vertex AI	`"vertex"`	Add your GCP project ID + service account JSON in settings
Eto Credits	`"eto_credits"`	No setup — runs on Eto’s own Vertex AI. Enterprise plans only.

Every AI request must include "provider": "gemini" or "provider": "vertex" in the JSON body.

POST/api/v1/ai/chatAI chat

Text chat with Gemini. Send a message and get a response.

Example

curl -X POST -H "X-Eto-API-Key: eto_your_key" \
     -H "Content-Type: application/json" \
     -d '{"message": "Make this title premium", "provider": "gemini", "context": {"draft_title": "Cotton Pillow"}}' \
     "https://eto.tools/api/v1/ai/chat"

Response

{"status": "ok", "reply": "Premium Cotton Pillow Cover, Hand-Finished Linen Blend"}

POST/api/v1/ai/generate-titleGenerate title

Name	Type	Required	Description
keyword	string	REQUIRED	Main keyword
product_description	string	optional	Brief product description
style	string	optional	professional, premium, casual default: professional
max_length	integer	optional	Max chars default: 140

Response

{"status": "ok", "title": "Premium Handmade Leather Bifold Wallet RFID Blocking", "length": 52}

POST/api/v1/ai/generate-descriptionGenerate description

Generate a compelling, SEO-friendly listing description.

POST/api/v1/ai/generate-imageGenerate image — not available yet

This endpoint is not available yet. It validates your key and provider, then answers 501 with {"status": "error", "message": "Image generation via API is coming soon. Use eto.tools/dashboard for now."}. Generate images in the dashboard until it ships.

The parameters below are the contract it will answer to once it is live.

Name	Type	Required	Description
prompt	string	REQUIRED	Image generation prompt
provider	string	REQUIRED	gemini, vertex or eto_credits
product_image	string	optional	Base64-encoded product image
type	string	optional	thumbnail, info, showcase

GET/api/v1/ai/generate-image/statusPoll image status

Poll with ?job_id=xxx. Returns 202 and {"status": "pending"} while the job runs, 200 when it finishes, and 502 with an error string if it failed. An unknown or foreign job id returns SESSION_NOT_FOUND.

{"status": "ok", "image_url": "/media/api/generated/123/img.png", "elapsed_s": 12.5}

POST/api/v1/ai/analyze-imageAnalyze image

Analyze a product image — get descriptions, features, and keywords.

#Webhooks

Instead of polling for orders, let Eto push order events to your own server in real time. When an order on your connected Etsy shop is paid, shipped, canceled, or delivered, Eto enriches the event with the full order detail and sends an HTTP POST to a URL you choose.

Webhooks are an Enterprise feature. Set your destination URL, pick the events and stores, and read the signing secret in the API console under Webhooks. You only ever receive events for your own connected stores.

Events

Event	Meaning
order.paid	The buyer completed payment for the order.
order.shipped	Shipping information was created / the order was marked shipped.
order.canceled	The seller canceled the order.
order.delivered	The order was marked delivered.

Choose which events and which stores forward to your URL in settings. A store only forwards while its order notifications are enabled.

Request headers

Header	Description
X-Eto-Event	The event type, e.g. `order.paid`.
X-Eto-Webhook-Id	Unique id for this delivery (e.g. `evt_8842`). Use it to de-duplicate retries.
X-Eto-Timestamp	Unix seconds when the delivery was sent.
X-Eto-Signature	`v1,<base64 HMAC-SHA256>` — optional integrity signature (see below).

Payload

The body is JSON. The order object contains every detail Eto has for the receipt — buyer, full shipping address, all monetary amounts (with a computed decimal value), line items, and shipments.

Example — order.paid

{
  "event": "order.paid",
  "event_description": "The buyer completed payment for this order.",
  "event_id": "evt_8842",
  "source_webhook_id": "msg_2a1b...",
  "sent_at": "2026-05-31T10:26:00+00:00",
  "shop": { "shop_id": "12345678", "shop_name": "MyShop" },
  "order": {
    "receipt_id": 987654321,
    "status": "paid",
    "is_paid": true,
    "is_shipped": false,
    "is_gift": false,
    "gift_message": "",
    "buyer": { "name": "Jane Doe", "email": "jane@example.com", "phone": "", "buyer_user_id": 55512345 },
    "shipping_address": {
      "name": "Jane Doe", "first_line": "1 Main St", "second_line": "",
      "city": "Austin", "state": "TX", "zip": "78701", "country_iso": "US",
      "formatted_address": "1 Main St\nAustin, TX 78701"
    },
    "amounts": {
      "grandtotal":          { "amount": 2599, "divisor": 100, "currency_code": "USD", "value": 25.99 },
      "subtotal":            { "amount": 1999, "divisor": 100, "currency_code": "USD", "value": 19.99 },
      "total_price":         { "amount": 1999, "divisor": 100, "currency_code": "USD", "value": 19.99 },
      "total_shipping_cost": { "amount": 400,  "divisor": 100, "currency_code": "USD", "value": 4.00 },
      "total_tax_cost":      { "amount": 200,  "divisor": 100, "currency_code": "USD", "value": 2.00 },
      "total_vat_cost":      null,
      "discount":            null,
      "gift_wrap_price":     null
    },
    "payment_method": "cc",
    "message_from_buyer": "Please gift wrap.",
    "items": [
      {
        "transaction_id": 333111,
        "title": "Custom Ceramic Mug",
        "description": "...",
        "quantity": 1,
        "sku": "MUG-RED-11OZ",
        "listing_id": 1100110011,
        "product_id": 2200220022,
        "listing_image_id": 3300330033,
        "is_digital": false,
        "transaction_type": "listing",
        "price":         { "amount": 1999, "divisor": 100, "currency_code": "USD", "value": 19.99 },
        "shipping_cost": { "amount": 400,  "divisor": 100, "currency_code": "USD", "value": 4.00 },
        "variations": [ { "property_id": 200, "formatted_name": "Color", "formatted_value": "Red" } ],
        "shipping_profile_id": 9090,
        "shipping_method": null,
        "expected_ship_date": 1717500000,
        "paid_timestamp": 1717150000,
        "shipped_timestamp": null,
        "created_timestamp": 1717150000
      }
    ],
    "shipments": [
      { "receipt_shipping_id": 7777, "carrier_name": "usps", "tracking_code": "94001...", "shipment_notification_timestamp": 1717300000 }
    ],
    "created_timestamp": 1717150000,
    "updated_timestamp": 1717150500
  }
}

Money is given in Etsy's minor-unit form (amount ÷ divisor) plus a pre-computed decimal value for convenience. Fields with no value are null. For order.shipped / order.delivered / order.canceled the same shape is sent for the specific receipt that changed.

Verifying the signature (optional)

You don't have to verify anything — Eto only sends events for your own account. But if you want to be certain a request genuinely came from Eto (and wasn't spoofed by someone who discovered your URL), verify the X-Eto-Signature header. Your signing secret is shown in settings (whsec_…).

How it's computed

signed_content = X-Eto-Webhook-Id + "." + X-Eto-Timestamp + "." + raw_request_body
secret_bytes   = base64_decode(your_secret without the "whsec_" prefix)
expected       = base64( HMAC_SHA256(secret_bytes, signed_content) )
# valid if  expected == X-Eto-Signature.split(",")[1]

Python

import base64, hashlib, hmac

def verify(headers, raw_body, secret):
    secret_bytes = base64.b64decode(secret.split("_", 1)[1])
    signed = f"{headers['X-Eto-Webhook-Id']}.{headers['X-Eto-Timestamp']}.{raw_body}"
    expected = base64.b64encode(
        hmac.new(secret_bytes, signed.encode(), hashlib.sha256).digest()
    ).decode()
    got = headers["X-Eto-Signature"].split(",", 1)[1]
    return hmac.compare_digest(got, expected)

Reject requests whose X-Eto-Timestamp is more than a few minutes old to guard against replays.

Fetch & retry from your own server

Every delivery is stored, so your backend can pull recent events or re-request a missed one programmatically — authenticated with your X-Eto-API-Key (same key as the rest of the API).

GET /api/v1/webhooks/deliveries List recent deliveries

Returns your deliveries newest-first, each with its status and HTTP result.

Name	Type	Required	Description
status	string	optional	Filter: `success`, `failed`, `pending`
event	string	optional	Filter by event type, e.g. `order.paid`
include_payload	boolean	optional	Include each full JSON payload default: false
limit	integer	optional	default: 25, max: 100
offset	integer	optional	Pagination offset

curl -H "X-Eto-API-Key: eto_your_key" \
     "https://eto.tools/api/v1/webhooks/deliveries?status=failed&limit=50"

Example response

{
  "success": true,
  "total": 128,
  "limit": 50,
  "offset": 0,
  "deliveries": [
    {
      "id": 8842,
      "event_id": "evt_8842",
      "event_type": "order.paid",
      "status": "success",
      "response_status_code": 200,
      "attempts": 1,
      "error": "",
      "is_test": false,
      "receipt_id": 987654321,
      "target_url": "https://your-server.com/webhooks/eto",
      "created_at": "2026-05-31T10:26:00.123456+00:00",
      "last_attempt_at": "2026-05-31T10:26:00.456789+00:00"
    },
    {
      "id": 8841,
      "event_id": "evt_8841",
      "event_type": "order.shipped",
      "status": "failed",
      "response_status_code": 404,
      "attempts": 2,
      "error": "HTTP 404 from your endpoint",
      "is_test": false,
      "receipt_id": 987654000,
      "target_url": "https://your-server.com/webhooks/eto",
      "created_at": "2026-05-31T09:10:00.000000+00:00",
      "last_attempt_at": "2026-05-31T09:12:00.000000+00:00"
    }
  ]
}

Add include_payload=true to embed each delivery's full payload (same shape as the single-delivery response below).

GET/api/v1/webhooks/deliveries?id={id}Fetch one delivery (full payload)

Returns a single delivery including the exact payload we sent and the response we received — the "ask again and get it" path for a missed event.

Example response (the fullest you'll get)

{
  "success": true,
  "delivery": {
    "id": 8842,
    "event_id": "evt_8842",
    "event_type": "order.paid",
    "status": "success",
    "response_status_code": 200,
    "attempts": 1,
    "error": "",
    "is_test": false,
    "receipt_id": 987654321,
    "target_url": "https://your-server.com/webhooks/eto",
    "created_at": "2026-05-31T10:26:00.123456+00:00",
    "last_attempt_at": "2026-05-31T10:26:00.456789+00:00",
    "response_body": "{\"received\": true}",
    "payload": {
      "event": "order.paid",
      "event_description": "The buyer completed payment for this order.",
      "event_id": "evt_8842",
      "source_webhook_id": "msg_2a1b3c...",
      "sent_at": "2026-05-31T10:26:00+00:00",
      "shop": { "shop_id": "12345678", "shop_name": "MyShop" },
      "order": {
        "receipt_id": 987654321,
        "status": "paid",
        "is_paid": true,
        "is_shipped": false,
        "is_gift": false,
        "gift_message": "",
        "buyer": { "name": "Jane Doe", "email": "jane@example.com", "phone": "", "buyer_user_id": 55512345 },
        "shipping_address": {
          "name": "Jane Doe", "first_line": "1 Main St", "second_line": "",
          "city": "Austin", "state": "TX", "zip": "78701", "country_iso": "US",
          "formatted_address": "1 Main St\nAustin, TX 78701"
        },
        "amounts": {
          "grandtotal":          { "amount": 2599, "divisor": 100, "currency_code": "USD", "value": 25.99 },
          "subtotal":            { "amount": 1999, "divisor": 100, "currency_code": "USD", "value": 19.99 },
          "total_price":         { "amount": 1999, "divisor": 100, "currency_code": "USD", "value": 19.99 },
          "total_shipping_cost": { "amount": 400,  "divisor": 100, "currency_code": "USD", "value": 4.00 },
          "total_tax_cost":      { "amount": 200,  "divisor": 100, "currency_code": "USD", "value": 2.00 },
          "total_vat_cost":      null,
          "discount":            null,
          "gift_wrap_price":     null
        },
        "payment_method": "cc",
        "message_from_buyer": "Please gift wrap.",
        "items": [
          {
            "transaction_id": 333111,
            "title": "Custom Ceramic Mug",
            "description": "11oz glossy ceramic mug",
            "quantity": 1,
            "sku": "MUG-RED-11OZ",
            "listing_id": 1100110011,
            "product_id": 2200220022,
            "listing_image_id": 3300330033,
            "is_digital": false,
            "transaction_type": "listing",
            "price":         { "amount": 1999, "divisor": 100, "currency_code": "USD", "value": 19.99 },
            "shipping_cost": { "amount": 400,  "divisor": 100, "currency_code": "USD", "value": 4.00 },
            "variations": [ { "property_id": 200, "formatted_name": "Color", "formatted_value": "Red" } ],
            "shipping_profile_id": 9090,
            "shipping_method": null,
            "expected_ship_date": 1717500000,
            "paid_timestamp": 1717150000,
            "shipped_timestamp": null,
            "created_timestamp": 1717150000
          }
        ],
        "shipments": [
          { "receipt_shipping_id": 7777, "carrier_name": "usps", "tracking_code": "94001...", "shipment_notification_timestamp": 1717300000 }
        ],
        "created_timestamp": 1717150000,
        "updated_timestamp": 1717150500
      }
    }
  }
}

POST/api/v1/webhooks/deliveries/{id}/retryRe-send one delivery

Re-delivers exactly one delivery — the single id you pass — to your current URL, and returns the new outcome (success, response_status_code, error). It never re-sends anything else.

There's no "retry all" — that's deliberate, so you never accidentally re-fire your whole history. To backfill several, list the ones you want (e.g. ?status=failed) and POST a retry per id.

curl -X POST -H "X-Eto-API-Key: eto_your_key" \
     "https://eto.tools/api/v1/webhooks/deliveries/8842/retry"

Example response

{
  "success": true,
  "response_status_code": 200,
  "error": "",
  "delivery": {
    "id": 8842,
    "event_id": "evt_8842",
    "event_type": "order.paid",
    "status": "success",
    "response_status_code": 200,
    "attempts": 2,
    "error": "",
    "is_test": false,
    "receipt_id": 987654321,
    "target_url": "https://your-server.com/webhooks/eto",
    "created_at": "2026-05-31T10:26:00.123456+00:00",
    "last_attempt_at": "2026-05-31T11:02:14.000000+00:00"
  }
}

Responding, delivery & retries

Respond 2xxReturn any 2xx status within ~10 seconds to mark the delivery successful.

Every event is savedEto stores each delivery with its full payload — nothing is lost if your server is down.

Manual retryRe-send any past delivery from the dashboard, or via the API above.

There is no automatic retry today — if your endpoint is unavailable, the delivery is marked failed and kept so you can re-send it (or pull the data) whenever you're ready.

#Connect an AI client

The same account is reachable over MCP, the protocol Claude, ChatGPT and Perplexity use to call tools. The MCP server is a thin layer over the endpoints on this page: same key, same account, same limits.

Server URL

https://mcp.eto.tools/mcp

Claude Code, or any client that sends headers

One command, with your key from the API console:

claude mcp add --transport http eto https://mcp.eto.tools/mcp \
  --header "X-Eto-API-Key: eto_your_key"

Claude, ChatGPT and Perplexity apps

Add https://mcp.eto.tools/mcp as a custom connector and sign in with your Eto account — no key to paste. The client runs an OAuth 2.1 flow (dynamic client registration and PKCE) against Eto, you approve it on a consent screen, and it then calls the API with a bearer token. Step-by-step instructions per client are on the MCP setup page.

The connector can only reach the stores connected to your account, and you can revoke it from the API console at any time. Like the API, it is an Enterprise feature.

#Bulk CSV / Excel import

Create hundreds of Etsy drafts at once from a spreadsheet. Open it from Single Research → New listing → Upload via CSV / Excel. Eto auto-detects your columns (even renamed or reordered), shows an organized preview where every listing is validated, then publishes the selected ones to draft.

Download CSV template

.csv & .xlsxUpload a CSV or Excel file — Etsy's bulk-edit export layout works as-is.

Images via URLPhotos & videos are links in the sheet; Eto fetches them at publish time. No file uploads.

Preview & flagListings missing required details are flagged before anything is published.

Up to 2,000Listings per import, published in the background with live progress.

How images & videos work

Put image and video links as URLs in the Photo 1…10 and optional Video 1… columns. Eto downloads each URL and uploads it to Etsy automatically when publishing — you don't upload files here. Any public https:// URL works (your cloud storage, a CDN, or existing Etsy image URLs). Photo 1 becomes the listing thumbnail.

Variations span multiple rows

A row with a Title starts a new listing. The rows directly below it with a blank Title are extra variation combinations of that same listing. Set the axis names once on the first row in Variation 1 / Variation 2 (e.g. Size, Color); each row then carries its own V1 Option, V2 Option, Var Price, Var Quantity, Var SKU and Var Visibility (On/Off).

Title                         | V1 Option | V2 Option   | Var Price | Var Visibility
Extra Large Abstract Wall Art | 16×32in   | Unframed    | 140.00    | On
                              | 16×32in   | Black Frame | 400.00    | On
                              | 20×40in   | Unframed    | 198.00    | On

Minimum required per listing

Applies to	Required fields
ALL	Title, Description, Category, Who made it?, When was it made?, Product type, Price, Quantity, and at least one Photo URL
Physical	Also a Shipping profile, a Return policy, and a Processing profile. Add a `Processing profile` column (matched by its days label, e.g. `5-7 days`) — or pick defaults in the importer that apply to any row that leaves them blank.
Digital	Also at least one digital file (digital import is lower priority and may be flagged).

Character & count limits

Field	Limit
Title	Up to 140 characters
Tags	Up to 13 tags, each ≤ 20 characters (comma-separated). Over-long tags are trimmed and flagged.
Materials	Up to 13 (comma-separated)

How names are matched to your shop

Column	Matched by
Category	Etsy's category tree — full path (e.g. `Art & Collectibles > Painting > Oil`), then the final category name.
Shipping profile / Section	Name match against the selected store. Blank or unmatched → the default you pick in the importer.
Processing profile	Matched by the processing-days label on your shop (e.g. `5-7 days`). Blank or unmatched → the default you pick in the importer.
Return policy	Number of days in the label; otherwise the default.
Store	Optional column — sends specific rows to a different connected shop (matched by shop name).

Friendly values we understand

Field	Accepted values
Who made it?	`I did`, `A member of my shop`, `Another company or person`
When was it made?	`Made To Order`, `2020-2026`, decade ranges like `1990s`, or `Before 2007`
Product type	`Physical` or `Digital`

Column reference

Headers are matched case-insensitively and tolerate punctuation/spacing differences. The importer accepts Etsy's full bulk-edit export, including: Listing ID, Title, Description, Category, Who made it?, What is it?, When was it made?, Renewal options, Product type, Tags, Materials, Production partners, Section, Price, Quantity, SKU, Variation 1, V1 Option, Variation 2, V2 Option, Var Price, Var Quantity, Var SKU, Var Visibility, Var Photo, Shipping profile, Processing profile, Weight, Length, Width, Height, Return policy, Photo 1…10. An optional Store column and Video 1… columns are also supported.

Tip: grab the Download CSV template above (also available in the importer), fill it in, and upload.

#Changelog

2 Aug 2026

API keys move to their own console

Key generation, rotation and usage moved out of Settings into the API console in the dashboard. The API and the MCP are Enterprise features.

29 Jun 2026

Product Hunt adds demand_24h

POST /api/v1/product-hunt returns units bought in the last 24 hours for listings you supply, or searches and ranks a keyword for you.

2 Jun 2026

Friendlier dates on finance and orders

Finance and order endpoints resolve period and date arguments server side, so callers no longer have to compute Unix timestamps.

1 Jun 2026

MCP clients can authorise with an OAuth 2.1 login instead of an API key. Bearer tokens work on every endpoint on this page.

31 May 2026

Outbound order webhooks

Order events are pushed to your server, signed with HMAC-SHA256, and every delivery can be listed or retried through the API.

25 May 2026

Finance endpoints

Revenue, fees, refunds and profit for a connected shop, plus a sync endpoint that re-fetches a day or a range from Etsy.

14 May 2026

Personalisation in the listing builder

POST /api/v1/listings/create accepts personalisation settings and passes them through to Etsy.

#Marketplace reference

Eto proxies the marketplace, so these routes hand you its full surface behind your own Eto API key: 96 endpoints across 27 resources, each documented with every parameter, request field and response property it accepts or returns.

They authenticate exactly like the rest of the Eto API — the X-Eto-API-Key header, plus a connected store for anything reading or writing shop-owned data. See Authentication.

#User

#getUser

GEThttps://eto.tools/api/v1/users/{user_id}

General Release

This endpoint is ready for production use.

Retrieves a user profile based on a unique user ID. Access is limited to profiles of the authenticated user or linked buyers. For the primary_email field, specific app-based permissions are required and granted case-by-case.

AuthorizationAPI keyconnected storeoperation user_profile

Path parameters

user_id integer <int64> required ≥ 1

Responses

200

A single User

Response schemaapplication/jsonUser

Represents a single user of the site

user_id integer <int64> ≥ 1

The numeric ID of a user. This number is also a valid shop ID for the user's shop.

primary_email string <email> nullable

An email address string for the user's primary email address. Access to this field is granted on a case by case basis for third-party integrations that require full access

first_name string nullable

The user's first name.

last_name string nullable

The user's last name.

image_url_75x75 string nullable

The user's avatar URL.

Example response

200 · application/json

{
  "user_id": 1,
  "primary_email": "string",
  "first_name": "string",
  "last_name": "string",
  "image_url_75x75": "string"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getMe

GEThttps://eto.tools/api/v1/users/me

General Release

This endpoint is ready for production use.

Returns basic info for the user making the request.

AuthorizationAPI keyconnected storeoperation users_me

Responses

200

Fetches basic info about the requesting user

Response schemaapplication/jsonSelf

Represents a single user of the site

user_id integer <int64> ≥ 1

The numeric ID of a user. This number is also a valid shop ID for the user's shop.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Example response

200 · application/json

{
  "user_id": 1,
  "shop_id": 1
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#UserAddress

#getUserAddress

GET/v3/application/user/addresses/{user_address_id}

Not currently exposed through the Eto API. Documented here for the data model it returns.

General Release

This endpoint is ready for production use.

Open API V3 endpoint to retrieve a UserAddress for a User.

AuthorizationAPI keyconnected store

Path parameters

user_address_id integer <int64> required ≥ 1

The numeric ID of the user's address.

Responses

200

A single UserAddress

Response schemaapplication/jsonUserAddress

Represents a user's address.

user_address_id integer <int64> ≥ 1

The numeric ID of the user's address.

user_id integer <int64> ≥ 1

The user's numeric ID.

name string

The user's name for this address.

first_line string

The first line of the user's address.

second_line string nullable

The second line of the user's address.

city string

The city field of the user's address.

state string nullable

The state field of the user's address.

zip string nullable

The zip code field of the user's address.

iso_country_code string nullable

The ISO code of the country in this address.

country_name string nullable

The name of the user's country.

is_default_shipping_address boolean

Is this the user's default shipping address.

Example response

200 · application/json

{
  "user_address_id": 1,
  "user_id": 1,
  "name": "string",
  "first_line": "string",
  "second_line": "string",
  "city": "string",
  "state": "string",
  "zip": "string",
  "iso_country_code": "string",
  "country_name": "string",
  "is_default_shipping_address": true
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#deleteUserAddress

DELETE/v3/application/user/addresses/{user_address_id}

Not currently exposed through the Eto API. Documented here for the data model it returns.

General Release

This endpoint is ready for production use.

Open API V3 endpoint to delete a UserAddress for a User.

AuthorizationAPI keyconnected store

Path parameters

user_address_id integer <int64> required ≥ 1

The numeric ID of the user's address.

Responses

204

The User Address resource was correctly deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getUserAddresses

GET/v3/application/user/addresses

Not currently exposed through the Eto API. Documented here for the data model it returns.

General Release

This endpoint is ready for production use.

Open API V3 endpoint to retrieve UserAddresses for a User.

AuthorizationAPI keyconnected store

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

Responses

200

A list of UserAddress records

Response schemaapplication/jsonUserAddresses

Represents several UserAddress records.

count integer <int64> ≥ 0

The number of UserAddress records being returned.

results array of UserAddress

An array of UserAddress resources.

UserAddress

Represents a user's address.

user_address_id integer <int64> ≥ 1

The numeric ID of the user's address.

user_id integer <int64> ≥ 1

The user's numeric ID.

name string

The user's name for this address.

first_line string

The first line of the user's address.

second_line string nullable

The second line of the user's address.

city string

The city field of the user's address.

state string nullable

The state field of the user's address.

zip string nullable

The zip code field of the user's address.

iso_country_code string nullable

The ISO code of the country in this address.

country_name string nullable

The name of the user's country.

is_default_shipping_address boolean

Is this the user's default shipping address.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "user_address_id": 1,
      "user_id": 1,
      "name": "string",
      "first_line": "string",
      "second_line": "string",
      "city": "string",
      "state": "string",
      "zip": "string",
      "iso_country_code": "string",
      "country_name": "string",
      "is_default_shipping_address": true
    }
  ]
}

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Shop Receipt Transactions

#getShopReceiptTransactionsByListing

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/sales

General Release

This endpoint is ready for production use.

Retrieves the list of transactions associated with a listing.

AuthorizationAPI keyconnected storeoperation listing_sales

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

legacy boolean

This parameter needed to enable new parameters and response values related to processing profiles.

Responses

200

A list of transactions

Response schemaapplication/jsonShopReceiptTransactions

A set of ShopReceiptTransaction resources

count integer <int64>

The number of ShopReceiptTransaction resources found.

results array of ShopReceiptTransaction

The ShopReceiptTransaction resources found.

ShopReceiptTransaction

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

transaction_id integer <int64> ≥ 1

The unique numeric ID for a transaction.

title string nullable

The title string of the listing purchased in this transaction.

description string nullable

The description string of the listing purchased in this transaction.

seller_user_id integer <int64> ≥ 1

The numeric user ID for the seller in this transaction.

buyer_user_id integer <int64> ≥ 1

The numeric user ID for the buyer in this transaction.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

paid_timestamp integer <int64> nullable≥ 946684800

The transaction's paid date and time, in epoch seconds.

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

quantity integer <int64> ≥ 0

The numeric quantity of products purchased in this transaction.

listing_image_id integer <int64> nullable≥ 1

The numeric ID of the primary listing image for this transaction.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

is_digital boolean

When true, the transaction recorded the purchase of a digital listing.

file_data string

A string describing the files purchased in this transaction.

listing_id integer <int64> nullable≥ 0

The numeric ID for the listing associated to this transaction.

transaction_type string

The type string for the transaction, usually "listing".

product_id integer <int64> nullable≥ 1

The numeric ID for a specific product purchased from a listing.

sku string nullable

The SKU string for the product

price object

A money object representing the price recorded the transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object

A money object representing the shipping cost for this transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

variations array of TransactionVariations

Array of variations and personalizations the buyer chose.

TransactionVariations

A list of variations chosen by the buyer during checkout.

property_id integer <int64>

The variation property ID.

value_id integer <int64> nullable

The ID of the variation value selected.

formatted_name string

Formatted name of the variation.

formatted_value string

Value of the variation entered by the buyer.

question_id integer <int64> nullable

[Personalization only] The ID of the original personalization question.

product_data array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

shipping_profile_id integer <int64> nullable≥ 1

The ID of the shipping profile selected for this listing.

min_processing_days integer <int64> nullable≥ 0

The minimum number of days for processing the listing.

max_processing_days integer <int64> nullable≥ 0

The maximum number of days for processing the listing.

shipping_method string nullable

Name of the selected shipping method.

shipping_upgrade string nullable

The name of the shipping upgrade selected for this listing. Default value is null.

expected_ship_date integer <int64> nullable≥ 946684800

The date & time of the expected ship date, in epoch seconds.

buyer_coupon number <float>

The amount of the buyer coupon that was discounted in the shop's currency.

Default0

shop_coupon number <float>

The amount of the shop coupon that was discounted in the shop's currency.

Default0

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "transaction_id": 1,
      "title": "string",
      "description": "string",
      "seller_user_id": 1,
      "buyer_user_id": 1,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "paid_timestamp": 946684800,
      "shipped_timestamp": 946684800,
      "quantity": 0,
      "listing_image_id": 1,
      "receipt_id": 1,
      "is_digital": true,
      "file_data": "string",
      "listing_id": 0,
      "transaction_type": "string",
      "product_id": 1,
      "sku": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "variations": [
        {
          "property_id": 0,
          "value_id": 0,
          "formatted_name": "string",
          "formatted_value": "string",
          "question_id": 0
        }
      ],
      "product_data": [
        {
          "property_id": 1,
          "property_name": "string",
          "scale_id": 1,
          "scale_name": "string",
          "value_ids": [
            1
          ],
          "values": [
            "string"
          ]
        }
      ],
      "shipping_profile_id": 1,
      "min_processing_days": 0,
      "max_processing_days": 0,
      "shipping_method": "string",
      "shipping_upgrade": "string",
      "expected_ship_date": 946684800,
      "buyer_coupon": 0,
      "shop_coupon": 0
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopReceiptTransactionsByReceipt

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}/transactions

General Release

This endpoint is ready for production use.

Retrieves the list of transactions associated with a specific receipt.

AuthorizationAPI keyconnected storeoperation order_transactions

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

receipt_id integer <int64> required ≥ 1

The numeric ID for the receipt associated to this transaction.

Query parameters

legacy boolean

This parameter needed to enable new parameters and response values related to processing profiles.

Responses

200

A list of transactions

Response schemaapplication/jsonShopReceiptTransactions

A set of ShopReceiptTransaction resources

count integer <int64>

The number of ShopReceiptTransaction resources found.

results array of ShopReceiptTransaction

The ShopReceiptTransaction resources found.

ShopReceiptTransaction

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

transaction_id integer <int64> ≥ 1

The unique numeric ID for a transaction.

title string nullable

The title string of the listing purchased in this transaction.

description string nullable

The description string of the listing purchased in this transaction.

seller_user_id integer <int64> ≥ 1

The numeric user ID for the seller in this transaction.

buyer_user_id integer <int64> ≥ 1

The numeric user ID for the buyer in this transaction.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

paid_timestamp integer <int64> nullable≥ 946684800

The transaction's paid date and time, in epoch seconds.

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

quantity integer <int64> ≥ 0

The numeric quantity of products purchased in this transaction.

listing_image_id integer <int64> nullable≥ 1

The numeric ID of the primary listing image for this transaction.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

is_digital boolean

When true, the transaction recorded the purchase of a digital listing.

file_data string

A string describing the files purchased in this transaction.

listing_id integer <int64> nullable≥ 0

The numeric ID for the listing associated to this transaction.

transaction_type string

The type string for the transaction, usually "listing".

product_id integer <int64> nullable≥ 1

The numeric ID for a specific product purchased from a listing.

sku string nullable

The SKU string for the product

price object

A money object representing the price recorded the transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object

A money object representing the shipping cost for this transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

variations array of TransactionVariations

Array of variations and personalizations the buyer chose.

TransactionVariations

A list of variations chosen by the buyer during checkout.

property_id integer <int64>

The variation property ID.

value_id integer <int64> nullable

The ID of the variation value selected.

formatted_name string

Formatted name of the variation.

formatted_value string

Value of the variation entered by the buyer.

question_id integer <int64> nullable

[Personalization only] The ID of the original personalization question.

product_data array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

shipping_profile_id integer <int64> nullable≥ 1

The ID of the shipping profile selected for this listing.

min_processing_days integer <int64> nullable≥ 0

The minimum number of days for processing the listing.

max_processing_days integer <int64> nullable≥ 0

The maximum number of days for processing the listing.

shipping_method string nullable

Name of the selected shipping method.

shipping_upgrade string nullable

The name of the shipping upgrade selected for this listing. Default value is null.

expected_ship_date integer <int64> nullable≥ 946684800

The date & time of the expected ship date, in epoch seconds.

buyer_coupon number <float>

The amount of the buyer coupon that was discounted in the shop's currency.

Default0

shop_coupon number <float>

The amount of the shop coupon that was discounted in the shop's currency.

Default0

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "transaction_id": 1,
      "title": "string",
      "description": "string",
      "seller_user_id": 1,
      "buyer_user_id": 1,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "paid_timestamp": 946684800,
      "shipped_timestamp": 946684800,
      "quantity": 0,
      "listing_image_id": 1,
      "receipt_id": 1,
      "is_digital": true,
      "file_data": "string",
      "listing_id": 0,
      "transaction_type": "string",
      "product_id": 1,
      "sku": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "variations": [
        {
          "property_id": 0,
          "value_id": 0,
          "formatted_name": "string",
          "formatted_value": "string",
          "question_id": 0
        }
      ],
      "product_data": [
        {
          "property_id": 1,
          "property_name": "string",
          "scale_id": 1,
          "scale_name": "string",
          "value_ids": [
            1
          ],
          "values": [
            "string"
          ]
        }
      ],
      "shipping_profile_id": 1,
      "min_processing_days": 0,
      "max_processing_days": 0,
      "shipping_method": "string",
      "shipping_upgrade": "string",
      "expected_ship_date": 946684800,
      "buyer_coupon": 0,
      "shop_coupon": 0
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopReceiptTransaction

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/sales/{transaction_id}

General Release

This endpoint is ready for production use.

Retrieves a transaction by transaction ID.

AuthorizationAPI keyconnected storeoperation single_transaction

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

transaction_id integer <int64> required ≥ 1

The unique numeric ID for a transaction.

Responses

200

A single transaction

Response schemaapplication/jsonShopReceiptTransaction

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

transaction_id integer <int64> ≥ 1

The unique numeric ID for a transaction.

title string nullable

The title string of the listing purchased in this transaction.

description string nullable

The description string of the listing purchased in this transaction.

seller_user_id integer <int64> ≥ 1

The numeric user ID for the seller in this transaction.

buyer_user_id integer <int64> ≥ 1

The numeric user ID for the buyer in this transaction.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

paid_timestamp integer <int64> nullable≥ 946684800

The transaction's paid date and time, in epoch seconds.

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

quantity integer <int64> ≥ 0

The numeric quantity of products purchased in this transaction.

listing_image_id integer <int64> nullable≥ 1

The numeric ID of the primary listing image for this transaction.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

is_digital boolean

When true, the transaction recorded the purchase of a digital listing.

file_data string

A string describing the files purchased in this transaction.

listing_id integer <int64> nullable≥ 0

The numeric ID for the listing associated to this transaction.

transaction_type string

The type string for the transaction, usually "listing".

product_id integer <int64> nullable≥ 1

The numeric ID for a specific product purchased from a listing.

sku string nullable

The SKU string for the product

price object

A money object representing the price recorded the transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object

A money object representing the shipping cost for this transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

variations array of TransactionVariations

Array of variations and personalizations the buyer chose.

TransactionVariations

A list of variations chosen by the buyer during checkout.

property_id integer <int64>

The variation property ID.

value_id integer <int64> nullable

The ID of the variation value selected.

formatted_name string

Formatted name of the variation.

formatted_value string

Value of the variation entered by the buyer.

question_id integer <int64> nullable

[Personalization only] The ID of the original personalization question.

product_data array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

shipping_profile_id integer <int64> nullable≥ 1

The ID of the shipping profile selected for this listing.

min_processing_days integer <int64> nullable≥ 0

The minimum number of days for processing the listing.

max_processing_days integer <int64> nullable≥ 0

The maximum number of days for processing the listing.

shipping_method string nullable

Name of the selected shipping method.

shipping_upgrade string nullable

The name of the shipping upgrade selected for this listing. Default value is null.

expected_ship_date integer <int64> nullable≥ 946684800

The date & time of the expected ship date, in epoch seconds.

buyer_coupon number <float>

The amount of the buyer coupon that was discounted in the shop's currency.

Default0

shop_coupon number <float>

The amount of the shop coupon that was discounted in the shop's currency.

Default0

Example response

200 · application/json

{
  "transaction_id": 1,
  "title": "string",
  "description": "string",
  "seller_user_id": 1,
  "buyer_user_id": 1,
  "create_timestamp": 946684800,
  "created_timestamp": 946684800,
  "paid_timestamp": 946684800,
  "shipped_timestamp": 946684800,
  "quantity": 0,
  "listing_image_id": 1,
  "receipt_id": 1,
  "is_digital": true,
  "file_data": "string",
  "listing_id": 0,
  "transaction_type": "string",
  "product_id": 1,
  "sku": "string",
  "price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "shipping_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "variations": [
    {
      "property_id": 0,
      "value_id": 0,
      "formatted_name": "string",
      "formatted_value": "string",
      "question_id": 0
    }
  ],
  "product_data": [
    {
      "property_id": 1,
      "property_name": "string",
      "scale_id": 1,
      "scale_name": "string",
      "value_ids": [
        1
      ],
      "values": [
        "string"
      ]
    }
  ],
  "shipping_profile_id": 1,
  "min_processing_days": 0,
  "max_processing_days": 0,
  "shipping_method": "string",
  "shipping_upgrade": "string",
  "expected_ship_date": 946684800,
  "buyer_coupon": 0,
  "shop_coupon": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopReceiptTransactionsByShop

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/sales

General Release

This endpoint is ready for production use.

Retrieves the list of transactions associated with a shop.

AuthorizationAPI keyconnected storeoperation shop_finance_sales

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

legacy boolean

This parameter needed to enable new parameters and response values related to processing profiles.

Responses

200

A list of transactions

Response schemaapplication/jsonShopReceiptTransactions

A set of ShopReceiptTransaction resources

count integer <int64>

The number of ShopReceiptTransaction resources found.

results array of ShopReceiptTransaction

The ShopReceiptTransaction resources found.

ShopReceiptTransaction

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

transaction_id integer <int64> ≥ 1

The unique numeric ID for a transaction.

title string nullable

The title string of the listing purchased in this transaction.

description string nullable

The description string of the listing purchased in this transaction.

seller_user_id integer <int64> ≥ 1

The numeric user ID for the seller in this transaction.

buyer_user_id integer <int64> ≥ 1

The numeric user ID for the buyer in this transaction.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

paid_timestamp integer <int64> nullable≥ 946684800

The transaction's paid date and time, in epoch seconds.

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

quantity integer <int64> ≥ 0

The numeric quantity of products purchased in this transaction.

listing_image_id integer <int64> nullable≥ 1

The numeric ID of the primary listing image for this transaction.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

is_digital boolean

When true, the transaction recorded the purchase of a digital listing.

file_data string

A string describing the files purchased in this transaction.

listing_id integer <int64> nullable≥ 0

The numeric ID for the listing associated to this transaction.

transaction_type string

The type string for the transaction, usually "listing".

product_id integer <int64> nullable≥ 1

The numeric ID for a specific product purchased from a listing.

sku string nullable

The SKU string for the product

price object

A money object representing the price recorded the transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object

A money object representing the shipping cost for this transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

variations array of TransactionVariations

Array of variations and personalizations the buyer chose.

TransactionVariations

A list of variations chosen by the buyer during checkout.

property_id integer <int64>

The variation property ID.

value_id integer <int64> nullable

The ID of the variation value selected.

formatted_name string

Formatted name of the variation.

formatted_value string

Value of the variation entered by the buyer.

question_id integer <int64> nullable

[Personalization only] The ID of the original personalization question.

product_data array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

shipping_profile_id integer <int64> nullable≥ 1

The ID of the shipping profile selected for this listing.

min_processing_days integer <int64> nullable≥ 0

The minimum number of days for processing the listing.

max_processing_days integer <int64> nullable≥ 0

The maximum number of days for processing the listing.

shipping_method string nullable

Name of the selected shipping method.

shipping_upgrade string nullable

The name of the shipping upgrade selected for this listing. Default value is null.

expected_ship_date integer <int64> nullable≥ 946684800

The date & time of the expected ship date, in epoch seconds.

buyer_coupon number <float>

The amount of the buyer coupon that was discounted in the shop's currency.

Default0

shop_coupon number <float>

The amount of the shop coupon that was discounted in the shop's currency.

Default0

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "transaction_id": 1,
      "title": "string",
      "description": "string",
      "seller_user_id": 1,
      "buyer_user_id": 1,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "paid_timestamp": 946684800,
      "shipped_timestamp": 946684800,
      "quantity": 0,
      "listing_image_id": 1,
      "receipt_id": 1,
      "is_digital": true,
      "file_data": "string",
      "listing_id": 0,
      "transaction_type": "string",
      "product_id": 1,
      "sku": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "variations": [
        {
          "property_id": 0,
          "value_id": 0,
          "formatted_name": "string",
          "formatted_value": "string",
          "question_id": 0
        }
      ],
      "product_data": [
        {
          "property_id": 1,
          "property_name": "string",
          "scale_id": 1,
          "scale_name": "string",
          "value_ids": [
            1
          ],
          "values": [
            "string"
          ]
        }
      ],
      "shipping_profile_id": 1,
      "min_processing_days": 0,
      "max_processing_days": 0,
      "shipping_method": "string",
      "shipping_upgrade": "string",
      "expected_ship_date": 946684800,
      "buyer_coupon": 0,
      "shop_coupon": 0
    }
  ]
}

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Other

#ping

GET/v3/application/openapi-ping

Not currently exposed through the Eto API. Documented here for the data model it returns.

General Release

This endpoint is ready for production use.

Check to confirm connectivity to the Etsy API with an application

AuthorizationAPI key

Responses

200

A confirmation that the current application has access to the Open API

Response schemaapplication/jsonPong

A confirmation that the current application has access to the Open API

application_id integer <int64> ≥ 1

The authenticated application's ID

Example response

200 · application/json

{
  "application_id": 1
}

401

Missing or invalid API key.

Response schemaapplication/jsonErrorSchema

error string required

404

App does not have the proper permissions to access this resource.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#tokenScopes

POST/v3/application/scopes

Not currently exposed through the Eto API. Documented here for the data model it returns.

General Release

This endpoint is ready for production use.

Check the scopes of the provided token

AuthorizationAPI key

Request bodyapplication/x-www-form-urlencoded

token string required

Responses

200

A confirmation that the current application has access to the Open API

Response schemaapplication/jsonScopes

A list of scopes allowed for the token.

Example response

200 · application/json

{}

401

Missing or invalid API key.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Shop

#getShop

GEThttps://eto.tools/api/v1/shops/{shop_id}

General Release

This endpoint is ready for production use.

Retrieves the shop identified by a specific shop ID.

AuthorizationAPI keyoperation shop_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Responses

200

A single Shop

Response schemaapplication/jsonShop

A shop created by an Etsy user.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

user_id integer <int64> ≥ 1

The numeric user ID of the user who owns this shop.

shop_name string

The shop's name string.

create_date integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

title string nullable

A brief heading string for the shop's main page.

announcement string nullable

An announcement string to buyers that displays on the shop's homepage.

currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

is_vacation boolean

When true, this shop is not accepting purchases.

vacation_message string nullable

The shop's message string displayed when is_vacation is true.

sale_message string nullable

A message string sent to users who complete a purchase from this shop.

digital_sale_message string nullable

A message string sent to users who purchase a digital item from this shop.

update_date integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

updated_timestamp integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

listing_active_count integer <int64> ≥ 0

The number of active listings in the shop.

digital_listing_count integer <int64> ≥ 0

The number of digital listings in the shop.

login_name string

The shop owner's login name string.

accepts_custom_requests boolean

When true, the shop accepts customization requests.

policy_welcome string nullable

The shop's policy welcome string (may be blank).

policy_payment string nullable

The shop's payment policy string (may be blank).

policy_shipping string nullable

The shop's shipping policy string (may be blank).

policy_refunds string nullable

The shop's refund policy string (may be blank).

policy_additional string nullable

The shop's additional policies string (may be blank).

policy_seller_info string nullable

The shop's seller information string (may be blank).

policy_update_date integer <int64> ≥ 0

The date and time of the last update to the shop's policies, in epoch seconds.

policy_has_private_receipt_info boolean

When true, EU receipts display private info.

has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

policy_privacy string nullable

The shop's privacy policy string (may be blank).

vacation_autoreply string nullable

The shop's automatic reply string displayed in new conversations when is_vacation is true.

url string

The URL string for this shop.

image_url_760x100 string nullable

The URL string for this shop's banner image.

num_favorers integer <int64> ≥ 0

The number of users who marked this shop a favorite.

languages array of string

A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.

icon_url_fullxfull string nullable

The URL string for this shop's icon image.

is_using_structured_policies boolean

When true, the shop accepted using structured policies.

has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

is_direct_checkout_onboarded boolean

(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.

is_etsy_payments_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

is_calculated_eligible boolean

When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)

is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

is_shop_us_based boolean

When true, the shop is based in the US.

transaction_sold_count integer <int64> ≥ 0

The total number of sales (transactions) for this shop.

shipping_from_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO the shop is shipping from.

shop_location_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO where the shop is located.

review_count integer <int64> nullable

Number of reviews of shop listings in the past year.

review_average number <float> nullable

Average rating based on reviews of shop listings in the past year.

Example response

200 · application/json

{
  "shop_id": 1,
  "user_id": 1,
  "shop_name": "string",
  "create_date": 0,
  "created_timestamp": 0,
  "title": "string",
  "announcement": "string",
  "currency_code": "string",
  "is_vacation": true,
  "vacation_message": "string",
  "sale_message": "string",
  "digital_sale_message": "string",
  "update_date": 0,
  "updated_timestamp": 0,
  "listing_active_count": 0,
  "digital_listing_count": 0,
  "login_name": "string",
  "accepts_custom_requests": true,
  "policy_welcome": "string",
  "policy_payment": "string",
  "policy_shipping": "string",
  "policy_refunds": "string",
  "policy_additional": "string",
  "policy_seller_info": "string",
  "policy_update_date": 0,
  "policy_has_private_receipt_info": true,
  "has_unstructured_policies": true,
  "policy_privacy": "string",
  "vacation_autoreply": "string",
  "url": "string",
  "image_url_760x100": "string",
  "num_favorers": 0,
  "languages": [
    "string"
  ],
  "icon_url_fullxfull": "string",
  "is_using_structured_policies": true,
  "has_onboarded_structured_policies": true,
  "include_dispute_form_link": true,
  "is_direct_checkout_onboarded": true,
  "is_etsy_payments_onboarded": true,
  "is_calculated_eligible": true,
  "is_opted_in_to_buyer_promise": true,
  "is_shop_us_based": true,
  "transaction_sold_count": 0,
  "shipping_from_country_iso": "string",
  "shop_location_country_iso": "string",
  "review_count": 0,
  "review_average": 0.0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateShop

PUThttps://eto.tools/api/v1/shops/{shop_id}

General Release

This endpoint is ready for production use.

Updates a shop. Assumes that all string parameters are provided in the shop's primary language. Please note that the policy_additional field should only be set for shops located in the EU. Passing a value for this field for shops outside of the EU, will result in an error.

AuthorizationAPI keyconnected storeoperation shop_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Request bodyapplication/x-www-form-urlencoded

title string

A brief heading string for the shop's main page.

announcement string

An announcement string to buyers that displays on the shop's homepage.

sale_message string

A message string sent to users who complete a purchase from this shop.

digital_sale_message string

A message string sent to users who purchase a digital item from this shop.

policy_additional string

The shop's additional policies string (may be blank).

Responses

200

A single Shop.

Response schemaapplication/jsonShop

A shop created by an Etsy user.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

user_id integer <int64> ≥ 1

The numeric user ID of the user who owns this shop.

shop_name string

The shop's name string.

create_date integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

title string nullable

A brief heading string for the shop's main page.

announcement string nullable

An announcement string to buyers that displays on the shop's homepage.

currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

is_vacation boolean

When true, this shop is not accepting purchases.

vacation_message string nullable

The shop's message string displayed when is_vacation is true.

sale_message string nullable

A message string sent to users who complete a purchase from this shop.

digital_sale_message string nullable

A message string sent to users who purchase a digital item from this shop.

update_date integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

updated_timestamp integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

listing_active_count integer <int64> ≥ 0

The number of active listings in the shop.

digital_listing_count integer <int64> ≥ 0

The number of digital listings in the shop.

login_name string

The shop owner's login name string.

accepts_custom_requests boolean

When true, the shop accepts customization requests.

policy_welcome string nullable

The shop's policy welcome string (may be blank).

policy_payment string nullable

The shop's payment policy string (may be blank).

policy_shipping string nullable

The shop's shipping policy string (may be blank).

policy_refunds string nullable

The shop's refund policy string (may be blank).

policy_additional string nullable

The shop's additional policies string (may be blank).

policy_seller_info string nullable

The shop's seller information string (may be blank).

policy_update_date integer <int64> ≥ 0

The date and time of the last update to the shop's policies, in epoch seconds.

policy_has_private_receipt_info boolean

When true, EU receipts display private info.

has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

policy_privacy string nullable

The shop's privacy policy string (may be blank).

vacation_autoreply string nullable

The shop's automatic reply string displayed in new conversations when is_vacation is true.

url string

The URL string for this shop.

image_url_760x100 string nullable

The URL string for this shop's banner image.

num_favorers integer <int64> ≥ 0

The number of users who marked this shop a favorite.

languages array of string

A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.

icon_url_fullxfull string nullable

The URL string for this shop's icon image.

is_using_structured_policies boolean

When true, the shop accepted using structured policies.

has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

is_direct_checkout_onboarded boolean

(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.

is_etsy_payments_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

is_calculated_eligible boolean

When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)

is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

is_shop_us_based boolean

When true, the shop is based in the US.

transaction_sold_count integer <int64> ≥ 0

The total number of sales (transactions) for this shop.

shipping_from_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO the shop is shipping from.

shop_location_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO where the shop is located.

review_count integer <int64> nullable

Number of reviews of shop listings in the past year.

review_average number <float> nullable

Average rating based on reviews of shop listings in the past year.

Example response

200 · application/json

{
  "shop_id": 1,
  "user_id": 1,
  "shop_name": "string",
  "create_date": 0,
  "created_timestamp": 0,
  "title": "string",
  "announcement": "string",
  "currency_code": "string",
  "is_vacation": true,
  "vacation_message": "string",
  "sale_message": "string",
  "digital_sale_message": "string",
  "update_date": 0,
  "updated_timestamp": 0,
  "listing_active_count": 0,
  "digital_listing_count": 0,
  "login_name": "string",
  "accepts_custom_requests": true,
  "policy_welcome": "string",
  "policy_payment": "string",
  "policy_shipping": "string",
  "policy_refunds": "string",
  "policy_additional": "string",
  "policy_seller_info": "string",
  "policy_update_date": 0,
  "policy_has_private_receipt_info": true,
  "has_unstructured_policies": true,
  "policy_privacy": "string",
  "vacation_autoreply": "string",
  "url": "string",
  "image_url_760x100": "string",
  "num_favorers": 0,
  "languages": [
    "string"
  ],
  "icon_url_fullxfull": "string",
  "is_using_structured_policies": true,
  "has_onboarded_structured_policies": true,
  "include_dispute_form_link": true,
  "is_direct_checkout_onboarded": true,
  "is_etsy_payments_onboarded": true,
  "is_calculated_eligible": true,
  "is_opted_in_to_buyer_promise": true,
  "is_shop_us_based": true,
  "transaction_sold_count": 0,
  "shipping_from_country_iso": "string",
  "shop_location_country_iso": "string",
  "review_count": 0,
  "review_average": 0.0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopByOwnerUserId

GEThttps://eto.tools/api/v1/users/{user_id}/shops

General Release

This endpoint is ready for production use.

Retrieves the shop identified by the shop owner's user ID.

AuthorizationAPI keyoperation user_shops

Path parameters

user_id integer <int64> required ≥ 1

The numeric user ID of the user who owns this shop.

Responses

200

A single Shop

Response schemaapplication/jsonShop

A shop created by an Etsy user.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

user_id integer <int64> ≥ 1

The numeric user ID of the user who owns this shop.

shop_name string

The shop's name string.

create_date integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

title string nullable

A brief heading string for the shop's main page.

announcement string nullable

An announcement string to buyers that displays on the shop's homepage.

currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

is_vacation boolean

When true, this shop is not accepting purchases.

vacation_message string nullable

The shop's message string displayed when is_vacation is true.

sale_message string nullable

A message string sent to users who complete a purchase from this shop.

digital_sale_message string nullable

A message string sent to users who purchase a digital item from this shop.

update_date integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

updated_timestamp integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

listing_active_count integer <int64> ≥ 0

The number of active listings in the shop.

digital_listing_count integer <int64> ≥ 0

The number of digital listings in the shop.

login_name string

The shop owner's login name string.

accepts_custom_requests boolean

When true, the shop accepts customization requests.

policy_welcome string nullable

The shop's policy welcome string (may be blank).

policy_payment string nullable

The shop's payment policy string (may be blank).

policy_shipping string nullable

The shop's shipping policy string (may be blank).

policy_refunds string nullable

The shop's refund policy string (may be blank).

policy_additional string nullable

The shop's additional policies string (may be blank).

policy_seller_info string nullable

The shop's seller information string (may be blank).

policy_update_date integer <int64> ≥ 0

The date and time of the last update to the shop's policies, in epoch seconds.

policy_has_private_receipt_info boolean

When true, EU receipts display private info.

has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

policy_privacy string nullable

The shop's privacy policy string (may be blank).

vacation_autoreply string nullable

The shop's automatic reply string displayed in new conversations when is_vacation is true.

url string

The URL string for this shop.

image_url_760x100 string nullable

The URL string for this shop's banner image.

num_favorers integer <int64> ≥ 0

The number of users who marked this shop a favorite.

languages array of string

A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.

icon_url_fullxfull string nullable

The URL string for this shop's icon image.

is_using_structured_policies boolean

When true, the shop accepted using structured policies.

has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

is_direct_checkout_onboarded boolean

(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.

is_etsy_payments_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

is_calculated_eligible boolean

When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)

is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

is_shop_us_based boolean

When true, the shop is based in the US.

transaction_sold_count integer <int64> ≥ 0

The total number of sales (transactions) for this shop.

shipping_from_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO the shop is shipping from.

shop_location_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO where the shop is located.

review_count integer <int64> nullable

Number of reviews of shop listings in the past year.

review_average number <float> nullable

Average rating based on reviews of shop listings in the past year.

Example response

200 · application/json

{
  "shop_id": 1,
  "user_id": 1,
  "shop_name": "string",
  "create_date": 0,
  "created_timestamp": 0,
  "title": "string",
  "announcement": "string",
  "currency_code": "string",
  "is_vacation": true,
  "vacation_message": "string",
  "sale_message": "string",
  "digital_sale_message": "string",
  "update_date": 0,
  "updated_timestamp": 0,
  "listing_active_count": 0,
  "digital_listing_count": 0,
  "login_name": "string",
  "accepts_custom_requests": true,
  "policy_welcome": "string",
  "policy_payment": "string",
  "policy_shipping": "string",
  "policy_refunds": "string",
  "policy_additional": "string",
  "policy_seller_info": "string",
  "policy_update_date": 0,
  "policy_has_private_receipt_info": true,
  "has_unstructured_policies": true,
  "policy_privacy": "string",
  "vacation_autoreply": "string",
  "url": "string",
  "image_url_760x100": "string",
  "num_favorers": 0,
  "languages": [
    "string"
  ],
  "icon_url_fullxfull": "string",
  "is_using_structured_policies": true,
  "has_onboarded_structured_policies": true,
  "include_dispute_form_link": true,
  "is_direct_checkout_onboarded": true,
  "is_etsy_payments_onboarded": true,
  "is_calculated_eligible": true,
  "is_opted_in_to_buyer_promise": true,
  "is_shop_us_based": true,
  "transaction_sold_count": 0,
  "shipping_from_country_iso": "string",
  "shop_location_country_iso": "string",
  "review_count": 0,
  "review_average": 0.0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#findShops

GEThttps://eto.tools/api/v1/shops

General Release

This endpoint is ready for production use.

Open API V3 endpoint for searching shops by name. Note: We make every effort to ensure that frozen or removed shops are not included in the search results. However, rarely, due to timing issues, they may appear.

AuthorizationAPI keyoperation shop_search

Query parameters

shop_name string required

The shop's name string.

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

Responses

200

A list of Shops

Response schemaapplication/jsonShops

A set of Shop records.

count integer <int64> ≥ 0

The total number of Shops

results array of Shop

The Shop resources.

Shop

A shop created by an Etsy user.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

user_id integer <int64> ≥ 1

The numeric user ID of the user who owns this shop.

shop_name string

The shop's name string.

create_date integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

title string nullable

A brief heading string for the shop's main page.

announcement string nullable

An announcement string to buyers that displays on the shop's homepage.

currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

is_vacation boolean

When true, this shop is not accepting purchases.

vacation_message string nullable

The shop's message string displayed when is_vacation is true.

sale_message string nullable

A message string sent to users who complete a purchase from this shop.

digital_sale_message string nullable

A message string sent to users who purchase a digital item from this shop.

update_date integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

updated_timestamp integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

listing_active_count integer <int64> ≥ 0

The number of active listings in the shop.

digital_listing_count integer <int64> ≥ 0

The number of digital listings in the shop.

login_name string

The shop owner's login name string.

accepts_custom_requests boolean

When true, the shop accepts customization requests.

policy_welcome string nullable

The shop's policy welcome string (may be blank).

policy_payment string nullable

The shop's payment policy string (may be blank).

policy_shipping string nullable

The shop's shipping policy string (may be blank).

policy_refunds string nullable

The shop's refund policy string (may be blank).

policy_additional string nullable

The shop's additional policies string (may be blank).

policy_seller_info string nullable

The shop's seller information string (may be blank).

policy_update_date integer <int64> ≥ 0

The date and time of the last update to the shop's policies, in epoch seconds.

policy_has_private_receipt_info boolean

When true, EU receipts display private info.

has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

policy_privacy string nullable

The shop's privacy policy string (may be blank).

vacation_autoreply string nullable

The shop's automatic reply string displayed in new conversations when is_vacation is true.

url string

The URL string for this shop.

image_url_760x100 string nullable

The URL string for this shop's banner image.

num_favorers integer <int64> ≥ 0

The number of users who marked this shop a favorite.

languages array of string

A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.

icon_url_fullxfull string nullable

The URL string for this shop's icon image.

is_using_structured_policies boolean

When true, the shop accepted using structured policies.

has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

is_direct_checkout_onboarded boolean

(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.

is_etsy_payments_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

is_calculated_eligible boolean

When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)

is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

is_shop_us_based boolean

When true, the shop is based in the US.

transaction_sold_count integer <int64> ≥ 0

The total number of sales (transactions) for this shop.

shipping_from_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO the shop is shipping from.

shop_location_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO where the shop is located.

review_count integer <int64> nullable

Number of reviews of shop listings in the past year.

review_average number <float> nullable

Average rating based on reviews of shop listings in the past year.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "shop_id": 1,
      "user_id": 1,
      "shop_name": "string",
      "create_date": 0,
      "created_timestamp": 0,
      "title": "string",
      "announcement": "string",
      "currency_code": "string",
      "is_vacation": true,
      "vacation_message": "string",
      "sale_message": "string",
      "digital_sale_message": "string",
      "update_date": 0,
      "updated_timestamp": 0,
      "listing_active_count": 0,
      "digital_listing_count": 0,
      "login_name": "string",
      "accepts_custom_requests": true,
      "policy_welcome": "string",
      "policy_payment": "string",
      "policy_shipping": "string",
      "policy_refunds": "string",
      "policy_additional": "string",
      "policy_seller_info": "string",
      "policy_update_date": 0,
      "policy_has_private_receipt_info": true,
      "has_unstructured_policies": true,
      "policy_privacy": "string",
      "vacation_autoreply": "string",
      "url": "string",
      "image_url_760x100": "string",
      "num_favorers": 0,
      "languages": [
        "string"
      ],
      "icon_url_fullxfull": "string",
      "is_using_structured_policies": true,
      "has_onboarded_structured_policies": true,
      "include_dispute_form_link": true,
      "is_direct_checkout_onboarded": true,
      "is_etsy_payments_onboarded": true,
      "is_calculated_eligible": true,
      "is_opted_in_to_buyer_promise": true,
      "is_shop_us_based": true,
      "transaction_sold_count": 0,
      "shipping_from_country_iso": "string",
      "shop_location_country_iso": "string",
      "review_count": 0,
      "review_average": 0.0
    }
  ]
}

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Shop ShippingProfile

#getShippingCarriers

GEThttps://eto.tools/api/v1/shipping-carriers

General Release

This endpoint is ready for production use.

Retrieves a list of available shipping carriers and the mail classes associated with them for a given country

AuthorizationAPI keyoperation shipping_carriers

Query parameters

origin_country_iso string <ISO 3166-1 alpha-2> required

The ISO code of the country from which the listing ships.

Responses

200

A set of ShippingCarriers

Response schemaapplication/jsonShippingCarriers

Represents several ShippingCarriers.

count integer <int64> ≥ 0

results array of ShippingCarrier

ShippingCarrier

A supported shipping carrier, which is used to calculate an Estimated Delivery Date.

shipping_carrier_id integer <int64> ≥ 1

The numeric ID of this shipping carrier.

name string

The name of this shipping carrier.

domestic_classes array of ShippingCarrierMailClass

Set of domestic mail classes of this shipping carrier.

ShippingCarrierMailClass

A shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.

mail_class_key string

The unique identifier of this mail class.

name string

The name of this mail class.

international_classes array of ShippingCarrierMailClass

Set of international mail classes of this shipping carrier.

ShippingCarrierMailClass

A shipping carrier's mail class, which is used to calculate an Estimated Delivery Date.

mail_class_key string

The unique identifier of this mail class.

name string

The name of this mail class.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "shipping_carrier_id": 1,
      "name": "string",
      "domestic_classes": [
        {
          "mail_class_key": "string",
          "name": "string"
        }
      ],
      "international_classes": [
        {
          "mail_class_key": "string",
          "name": "string"
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopShippingProfiles

GEThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles

General Release

This endpoint is ready for production use.

Retrieves a list of shipping profiles available in the specific Etsy shop identified by its shop ID.

AuthorizationAPI keyconnected storeoperation shipping_profiles

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Responses

200

A list of shipping profiles

Response schemaapplication/jsonShopShippingProfiles

Represents several ShopShippingProfiles.

count integer <int64> ≥ 0

results array of ShopShippingProfile

ShopShippingProfile

Represents a profile used to set a listing's shipping information. Please note that it's not possible to create calculated shipping templates via the API. However, you can associate calculated shipping profiles created from Shop Manager with listings using the API.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

title string nullable

The name string of this shipping profile.

user_id integer <int64> ≥ 1

The numeric ID for the user who owns the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

is_deleted boolean

When true, someone deleted this shipping profile.

shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

The code of the region to which the listing ships. A region represents a set of countries. Supported regions are Europe Union and Non-Europe Union (countries in Europe not in EU). If none, request sets destination to destination_country_iso. Required if destination_country_iso is null or not provided.

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

The unique ID string of a shipping carrier's mail class, which is used to calculate an estimated delivery date. **Required with shipping_carrier_id** if min_delivery_days and max_delivery_days are null.

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

origin_postal_code string nullable

The postal code string (not necessarily a number) for the location from which the listing ships. Required if the origin_country_iso supports postal codes. See the Fulfillment Tutorial docs for more info

profile_type string

Default"manual"

Enum"manual""calculated"

domestic_handling_fee number <float> ≥ 0

The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

international_handling_fee number <float> ≥ 0

The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "shipping_profile_id": 1,
      "title": "string",
      "user_id": 1,
      "origin_country_iso": "string",
      "is_deleted": true,
      "shipping_profile_destinations": [
        {
          "shipping_profile_destination_id": 1,
          "shipping_profile_id": 1,
          "origin_country_iso": "string",
          "destination_country_iso": "string",
          "destination_region": "eu",
          "primary_cost": {
            "amount": 0,
            "divisor": 0,
            "currency_code": "string"
          },
          "secondary_cost": {
            "amount": 0,
            "divisor": 0,
            "currency_code": "string"
          },
          "shipping_carrier_id": 0,
          "mail_class": "string",
          "min_delivery_days": 1,
          "max_delivery_days": 1
        }
      ],
      "shipping_profile_upgrades": [
        {
          "shipping_profile_id": 1,
          "upgrade_id": 1,
          "upgrade_name": "string",
          "type": 0,
          "rank": 0,
          "language": "string",
          "price": {
            "amount": 0,
            "divisor": 0,
            "currency_code": "string"
          },
          "secondary_price": {
            "amount": 0,
            "divisor": 0,
            "currency_code": "string"
          },
          "shipping_carrier_id": 0,
          "mail_class": "string",
          "min_delivery_days": 1,
          "max_delivery_days": 1
        }
      ],
      "origin_postal_code": "string",
      "profile_type": "manual",
      "domestic_handling_fee": 0,
      "international_handling_fee": 0
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#createShopShippingProfile

POSThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles

General Release

This endpoint is ready for production use.

Creates a new ShippingProfile. You can pass a country iso code or a region when creating a ShippingProfile, but not both. Only one is required. You must pass either a shipping_carrier_id AND mail_class, or both min and max_delivery_days.

AuthorizationAPI keyconnected storeoperation shipping_profiles

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Request bodyapplication/x-www-form-urlencoded

title string required

The name string of this shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2> required

The ISO code of the country from which the listing ships.

primary_cost number <float> required ≥ 0

The cost of shipping to this country/region alone, measured in the store's default currency.

secondary_cost number <float> required ≥ 0

The cost of shipping to this country/region with another item, measured in the store's default currency.

min_processing_time integer <int64> ≥ 1≤ 10

The minimum time required to process to ship listings with this shipping profile.

max_processing_time integer <int64> ≥ 1≤ 10

The maximum processing time the listing needs to ship.

processing_time_unit string

The unit used to represent how long a processing time is. A week is equivalent to the set processing schedule (default to 5 business days). If none is provided, the unit is set to "business_days".

Default"business_days"

Enum"business_days""weeks"

destination_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

Defaultnull

destination_region string

Default"none"

Enum"eu""non_eu""none"

origin_postal_code string

Default""

shipping_carrier_id integer <int64> ≥ 0

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

Default0

mail_class string

Defaultnull

min_delivery_days integer <int64> ≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

Defaultnull

max_delivery_days integer <int64> ≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Defaultnull

Responses

200

A single ShippingProfile

Response schemaapplication/jsonShopShippingProfile

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

title string nullable

The name string of this shipping profile.

user_id integer <int64> ≥ 1

The numeric ID for the user who owns the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

is_deleted boolean

When true, someone deleted this shipping profile.

shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

origin_postal_code string nullable

profile_type string

Default"manual"

Enum"manual""calculated"

domestic_handling_fee number <float> ≥ 0

The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

international_handling_fee number <float> ≥ 0

The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

Example response

200 · application/json

{
  "shipping_profile_id": 1,
  "title": "string",
  "user_id": 1,
  "origin_country_iso": "string",
  "is_deleted": true,
  "shipping_profile_destinations": [
    {
      "shipping_profile_destination_id": 1,
      "shipping_profile_id": 1,
      "origin_country_iso": "string",
      "destination_country_iso": "string",
      "destination_region": "eu",
      "primary_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "secondary_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_carrier_id": 0,
      "mail_class": "string",
      "min_delivery_days": 1,
      "max_delivery_days": 1
    }
  ],
  "shipping_profile_upgrades": [
    {
      "shipping_profile_id": 1,
      "upgrade_id": 1,
      "upgrade_name": "string",
      "type": 0,
      "rank": 0,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "secondary_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_carrier_id": 0,
      "mail_class": "string",
      "min_delivery_days": 1,
      "max_delivery_days": 1
    }
  ],
  "origin_postal_code": "string",
  "profile_type": "manual",
  "domestic_handling_fee": 0,
  "international_handling_fee": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopShippingProfile

GEThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}

General Release

This endpoint is ready for production use.

Retrieves a Shipping Profile referenced by shipping profile ID.

AuthorizationAPI keyconnected storeoperation shipping_profile_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

Responses

200

A single ShippingProfile

Response schemaapplication/jsonShopShippingProfile

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

title string nullable

The name string of this shipping profile.

user_id integer <int64> ≥ 1

The numeric ID for the user who owns the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

is_deleted boolean

When true, someone deleted this shipping profile.

shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

origin_postal_code string nullable

profile_type string

Default"manual"

Enum"manual""calculated"

domestic_handling_fee number <float> ≥ 0

The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

international_handling_fee number <float> ≥ 0

The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

Example response

200 · application/json

{
  "shipping_profile_id": 1,
  "title": "string",
  "user_id": 1,
  "origin_country_iso": "string",
  "is_deleted": true,
  "shipping_profile_destinations": [
    {
      "shipping_profile_destination_id": 1,
      "shipping_profile_id": 1,
      "origin_country_iso": "string",
      "destination_country_iso": "string",
      "destination_region": "eu",
      "primary_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "secondary_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_carrier_id": 0,
      "mail_class": "string",
      "min_delivery_days": 1,
      "max_delivery_days": 1
    }
  ],
  "shipping_profile_upgrades": [
    {
      "shipping_profile_id": 1,
      "upgrade_id": 1,
      "upgrade_name": "string",
      "type": 0,
      "rank": 0,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "secondary_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_carrier_id": 0,
      "mail_class": "string",
      "min_delivery_days": 1,
      "max_delivery_days": 1
    }
  ],
  "origin_postal_code": "string",
  "profile_type": "manual",
  "domestic_handling_fee": 0,
  "international_handling_fee": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateShopShippingProfile

PUThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}

General Release

This endpoint is ready for production use.

Changes the settings in a shipping profile. You can pass a country iso code or a region when updating a ShippingProfile, but not both. Only one is required. You must pass either a shipping_carrier_id AND mail_class, or both min and max_delivery_days.

AuthorizationAPI keyconnected storeoperation shipping_profile_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

Request bodyapplication/x-www-form-urlencoded

title string

The name string of this shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

min_processing_time integer <int64> ≥ 1≤ 10

The minimum time required to process to ship listings with this shipping profile.

max_processing_time integer <int64> ≥ 1≤ 10

The maximum processing time the listing needs to ship.

processing_time_unit string

The unit used to represent how long a processing time is. A week is equivalent to the set processing schedule (default to 5 business days). If none is provided, the unit is set to "business_days".

Default"business_days"

Enum"business_days""weeks"

origin_postal_code string

Defaultnull

Responses

200

The updated shipping profile.

Response schemaapplication/jsonShopShippingProfile

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

title string nullable

The name string of this shipping profile.

user_id integer <int64> ≥ 1

The numeric ID for the user who owns the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

is_deleted boolean

When true, someone deleted this shipping profile.

shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

origin_postal_code string nullable

profile_type string

Default"manual"

Enum"manual""calculated"

domestic_handling_fee number <float> ≥ 0

The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

international_handling_fee number <float> ≥ 0

The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

Example response

200 · application/json

{
  "shipping_profile_id": 1,
  "title": "string",
  "user_id": 1,
  "origin_country_iso": "string",
  "is_deleted": true,
  "shipping_profile_destinations": [
    {
      "shipping_profile_destination_id": 1,
      "shipping_profile_id": 1,
      "origin_country_iso": "string",
      "destination_country_iso": "string",
      "destination_region": "eu",
      "primary_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "secondary_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_carrier_id": 0,
      "mail_class": "string",
      "min_delivery_days": 1,
      "max_delivery_days": 1
    }
  ],
  "shipping_profile_upgrades": [
    {
      "shipping_profile_id": 1,
      "upgrade_id": 1,
      "upgrade_name": "string",
      "type": 0,
      "rank": 0,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "secondary_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_carrier_id": 0,
      "mail_class": "string",
      "min_delivery_days": 1,
      "max_delivery_days": 1
    }
  ],
  "origin_postal_code": "string",
  "profile_type": "manual",
  "domestic_handling_fee": 0,
  "international_handling_fee": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

503

This function is temporarily unavailable. Please try again later.

Response schemaapplication/jsonErrorSchema

error string required

#deleteShopShippingProfile

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}

General Release

This endpoint is ready for production use.

Deletes a ShippingProfile by given id.

AuthorizationAPI keyconnected storeoperation shipping_profile_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

Responses

204

The ShopShippingProfile resource was correctly deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopShippingProfileDestinationsByShippingProfile

GEThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/destinations

General Release

This endpoint is ready for production use.

Retrieves a list of shipping destination objects associated with a shipping profile.

AuthorizationAPI keyconnected storeoperation shipping_destinations

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

Responses

200

A list of shipping destination objects.

Response schemaapplication/jsonShopShippingProfileDestinations

Represents a list of shipping destination objects.

count integer <int64> ≥ 0

The number of results.

results array of ShopShippingProfileDestination

The list of requested resources.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "shipping_profile_destination_id": 1,
      "shipping_profile_id": 1,
      "origin_country_iso": "string",
      "destination_country_iso": "string",
      "destination_region": "eu",
      "primary_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "secondary_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_carrier_id": 0,
      "mail_class": "string",
      "min_delivery_days": 1,
      "max_delivery_days": 1
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#createShopShippingProfileDestination

POSThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/destinations

General Release

This endpoint is ready for production use.

Creates a new shipping destination, which sets the shipping cost, carrier, and class for a destination in a shipping profile. createShopShippingProfileDestination assigns costs using the currency of the associated shop. Set the destination using either destination_country_iso or destination_region; destination_country_iso and destination_region are mutually exclusive — set one or the other. Setting both triggers error 400. If the request sets neither destination_country_iso nor destination_region, the default destination is "everywhere". You must also either assign both a shipping_carrier_id AND mail_class or both min_delivery_days AND max_delivery_days.

AuthorizationAPI keyconnected storeoperation shipping_destinations

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

Request bodyapplication/x-www-form-urlencoded

primary_cost number <float> required ≥ 0

The cost of shipping to this country/region alone, measured in the store's default currency.

secondary_cost number <float> required ≥ 0

The cost of shipping to this country/region with another item, measured in the store's default currency.

destination_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

Defaultnull

destination_region string

Default"none"

Enum"eu""non_eu""none"

shipping_carrier_id integer <int64> ≥ 0

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

Default0

mail_class string

Defaultnull

min_delivery_days integer <int64> ≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

Defaultnull

max_delivery_days integer <int64> ≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Defaultnull

Responses

201

A single shipping destination.

Response schemaapplication/jsonShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Example response

201 · application/json

{
  "shipping_profile_destination_id": 1,
  "shipping_profile_id": 1,
  "origin_country_iso": "string",
  "destination_country_iso": "string",
  "destination_region": "eu",
  "primary_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "secondary_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "shipping_carrier_id": 0,
  "mail_class": "string",
  "min_delivery_days": 1,
  "max_delivery_days": 1
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateShopShippingProfileDestination

PUThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/destinations/{destination_id}

General Release

This endpoint is ready for production use.

Updates an existing shipping destination, which can set or reassign the shipping cost, carrier, and class for a destination.

AuthorizationAPI keyconnected storeoperation shipping_destination_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

shipping_profile_destination_id integer <int64> required ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

Request bodyapplication/x-www-form-urlencoded

primary_cost number <float> ≥ 0

The cost of shipping to this country/region alone, measured in the store's default currency.

Defaultnull

secondary_cost number <float> ≥ 0

The cost of shipping to this country/region with another item, measured in the store's default currency.

Defaultnull

destination_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

Defaultnull

destination_region string

Default"none"

Enum"eu""non_eu""none"

shipping_carrier_id integer <int64> ≥ 0

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

Defaultnull

mail_class string

Defaultnull

min_delivery_days integer <int64> ≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

Defaultnull

max_delivery_days integer <int64> ≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Defaultnull

Responses

200

A single shipping destination.

Response schemaapplication/jsonShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Example response

200 · application/json

{
  "shipping_profile_destination_id": 1,
  "shipping_profile_id": 1,
  "origin_country_iso": "string",
  "destination_country_iso": "string",
  "destination_region": "eu",
  "primary_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "secondary_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "shipping_carrier_id": 0,
  "mail_class": "string",
  "min_delivery_days": 1,
  "max_delivery_days": 1
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

503

This function is temporarily unavailable. Please try again later.

Response schemaapplication/jsonErrorSchema

error string required

#deleteShopShippingProfileDestination

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/destinations/{destination_id}

General Release

This endpoint is ready for production use.

Deletes a shipping destination and removes the destination option from every listing that uses the associated shipping profile. A shipping profile requires at least one shipping destination, so this endpoint cannot delete the final shipping destination for any shipping profile. To delete the final shipping destination from a shipping profile, you must delete the entire shipping profile.

AuthorizationAPI keyconnected storeoperation shipping_destination_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

shipping_profile_destination_id integer <int64> required ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

Responses

204

Etsy deleted the shipping profile destination.

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopShippingProfileUpgrades

GEThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/upgrades

General Release

This endpoint is ready for production use.

Retrieves the list of shipping profile upgrades assigned to a specific shipping profile.

AuthorizationAPI keyconnected storeoperation shipping_upgrades

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

Responses

200

A list of shipping profile upgrades.

Response schemaapplication/jsonShopShippingProfileUpgrades

A list of shipping upgrade options.

count integer <int64> ≥ 0

The number of results.

results array of ShopShippingProfileUpgrade

The list of requested resources.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "shipping_profile_id": 1,
      "upgrade_id": 1,
      "upgrade_name": "string",
      "type": 0,
      "rank": 0,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "secondary_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_carrier_id": 0,
      "mail_class": "string",
      "min_delivery_days": 1,
      "max_delivery_days": 1
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#createShopShippingProfileUpgrade

POSThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/upgrades

General Release

This endpoint is ready for production use.

Creates a new shipping profile upgrade, which can establish a price for a shipping option, such as an alternate carrier or faster delivery.

AuthorizationAPI keyconnected storeoperation shipping_upgrades

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

Request bodyapplication/x-www-form-urlencoded

type integer <int64> required

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

upgrade_name string required

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

price number <float> required ≥ 0

Additional cost of adding the shipping upgrade.

secondary_price number <float> required ≥ 0

Additional cost of adding the shipping upgrade for each additional item.

shipping_carrier_id integer <int64> ≥ 0

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

Default0

mail_class string

Defaultnull

min_delivery_days integer <int64> ≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

Defaultnull

max_delivery_days integer <int64> ≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Defaultnull

Responses

200

A single shipping profile upgrade.

Response schemaapplication/jsonShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Example response

200 · application/json

{
  "shipping_profile_id": 1,
  "upgrade_id": 1,
  "upgrade_name": "string",
  "type": 0,
  "rank": 0,
  "language": "string",
  "price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "secondary_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "shipping_carrier_id": 0,
  "mail_class": "string",
  "min_delivery_days": 1,
  "max_delivery_days": 1
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateShopShippingProfileUpgrade

PUThttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/upgrades/{upgrade_id}

General Release

This endpoint is ready for production use.

Updates a shipping profile upgrade and updates any listings that use the shipping profile.

AuthorizationAPI keyconnected storeoperation shipping_upgrade_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

upgrade_id integer <int64> required ≥ 1

The numeric ID that is associated with a shipping upgrade

Request bodyapplication/x-www-form-urlencoded

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

Defaultnull

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

price number <float> ≥ 0

Additional cost of adding the shipping upgrade.

Defaultnull

secondary_price number <float> ≥ 0

Additional cost of adding the shipping upgrade for each additional item.

Defaultnull

shipping_carrier_id integer <int64> ≥ 0

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

Defaultnull

mail_class string

Defaultnull

min_delivery_days integer <int64> ≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

Defaultnull

max_delivery_days integer <int64> ≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Defaultnull

Responses

200

A single shipping profile upgrade.

Response schemaapplication/jsonShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

Example response

200 · application/json

{
  "shipping_profile_id": 1,
  "upgrade_id": 1,
  "upgrade_name": "string",
  "type": 0,
  "rank": 0,
  "language": "string",
  "price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "secondary_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "shipping_carrier_id": 0,
  "mail_class": "string",
  "min_delivery_days": 1,
  "max_delivery_days": 1
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

503

This function is temporarily unavailable. Please try again later.

Response schemaapplication/jsonErrorSchema

error string required

#deleteShopShippingProfileUpgrade

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/shipping-profiles/{profile_id}/upgrades/{upgrade_id}

General Release

This endpoint is ready for production use.

Deletes a shipping profile upgrade and removes the upgrade option from every listing that uses the associated shipping profile.

AuthorizationAPI keyconnected storeoperation shipping_upgrade_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shipping_profile_id integer <int64> required ≥ 1

The numeric ID of the shipping profile.

upgrade_id integer <int64> required ≥ 1

The numeric ID that is associated with a shipping upgrade

Responses

204

Etsy deleted the shipping profile upgrade.

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Shop Section

#getShopSections

GEThttps://eto.tools/api/v1/shops/{shop_id}/sections

General Release

This endpoint is ready for production use.

Retrieves the list of shop sections in a specific shop identified by shop ID.

AuthorizationAPI keyoperation shop_sections_get

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Responses

200

A list of shop sections.

Response schemaapplication/jsonShopSections

All the sections in a specific Shop.

count integer <int64> ≥ 0

The number of results.

results array of ShopSection

The list of requested resources.

ShopSection

A section within a shop, into which a user can sort listings.

shop_section_id integer <int64> ≥ 1

The numeric ID of a section in a specific Etsy shop.

title string

The title string for a shop section.

rank integer <int64> ≥ 0

The positive non-zero numeric position of this section in the section display order for a shop, with rank 1 sections appearing first.

user_id integer <int64> ≥ 1

The numeric ID of the user who owns this shop section.

active_listing_count integer <int64> ≥ 0

The number of active listings in one section of a specific Etsy shop.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "shop_section_id": 1,
      "title": "string",
      "rank": 0,
      "user_id": 1,
      "active_listing_count": 0
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#createShopSection

POSThttps://eto.tools/api/v1/shops/{shop_id}/sections

General Release

This endpoint is ready for production use.

Creates a new section in a specific shop.

AuthorizationAPI keyconnected storeoperation shop_sections_get

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Request bodyapplication/x-www-form-urlencoded

title string required

The title string for a shop section.

Responses

200

A Shop Section resource

Response schemaapplication/jsonShopSection

A section within a shop, into which a user can sort listings.

shop_section_id integer <int64> ≥ 1

The numeric ID of a section in a specific Etsy shop.

title string

The title string for a shop section.

rank integer <int64> ≥ 0

The positive non-zero numeric position of this section in the section display order for a shop, with rank 1 sections appearing first.

user_id integer <int64> ≥ 1

The numeric ID of the user who owns this shop section.

active_listing_count integer <int64> ≥ 0

The number of active listings in one section of a specific Etsy shop.

Example response

200 · application/json

{
  "shop_section_id": 1,
  "title": "string",
  "rank": 0,
  "user_id": 1,
  "active_listing_count": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

503

This function is temporarily unavailable. Please try again later.

Response schemaapplication/jsonErrorSchema

error string required

#getShopSection

GEThttps://eto.tools/api/v1/shops/{shop_id}/sections/{section_id}

General Release

This endpoint is ready for production use.

Retrieves a shop section, referenced by section ID and shop ID.

AuthorizationAPI keyoperation shop_section_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shop_section_id integer <int64> required ≥ 1

The numeric ID of a section in a specific Etsy shop.

Responses

200

A shop section resource

Response schemaapplication/jsonShopSection

A section within a shop, into which a user can sort listings.

shop_section_id integer <int64> ≥ 1

The numeric ID of a section in a specific Etsy shop.

title string

The title string for a shop section.

rank integer <int64> ≥ 0

The positive non-zero numeric position of this section in the section display order for a shop, with rank 1 sections appearing first.

user_id integer <int64> ≥ 1

The numeric ID of the user who owns this shop section.

active_listing_count integer <int64> ≥ 0

The number of active listings in one section of a specific Etsy shop.

Example response

200 · application/json

{
  "shop_section_id": 1,
  "title": "string",
  "rank": 0,
  "user_id": 1,
  "active_listing_count": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateShopSection

PUThttps://eto.tools/api/v1/shops/{shop_id}/sections/{section_id}

General Release

This endpoint is ready for production use.

Updates a section in a specific shop given a valid shop_section_id.

AuthorizationAPI keyconnected storeoperation shop_section_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shop_section_id integer <int64> required ≥ 1

The numeric ID of a section in a specific Etsy shop.

Request bodyapplication/x-www-form-urlencoded

title string required

The title string for a shop section.

Responses

200

A Shop Section resource

Response schemaapplication/jsonShopSection

A section within a shop, into which a user can sort listings.

shop_section_id integer <int64> ≥ 1

The numeric ID of a section in a specific Etsy shop.

title string

The title string for a shop section.

rank integer <int64> ≥ 0

The positive non-zero numeric position of this section in the section display order for a shop, with rank 1 sections appearing first.

user_id integer <int64> ≥ 1

The numeric ID of the user who owns this shop section.

active_listing_count integer <int64> ≥ 0

The number of active listings in one section of a specific Etsy shop.

Example response

200 · application/json

{
  "shop_section_id": 1,
  "title": "string",
  "rank": 0,
  "user_id": 1,
  "active_listing_count": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

503

This function is temporarily unavailable. Please try again later.

Response schemaapplication/jsonErrorSchema

error string required

#deleteShopSection

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/sections/{section_id}

General Release

This endpoint is ready for production use.

Deletes a section in a specific shop given a valid shop_section_id.

AuthorizationAPI keyconnected storeoperation shop_section_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

shop_section_id integer <int64> required ≥ 1

The numeric ID of a section in a specific Etsy shop.

Responses

204

The shop section resource was correctly deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

503

This function is temporarily unavailable. Please try again later.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing

#getListingsByShop

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings

General Release

This endpoint is ready for production use.

Endpoint to list Listings that belong to a Shop. Listings can be filtered using the 'state' param.

AuthorizationAPI keyconnected storeoperation shop_listings

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

state string

When _updating_ a listing, this value can be either active or inactive. Note: Setting a draft listing to active will also publish the listing on etsy.com and requires that the listing have an image set. Setting a sold_out listing to active will update the quantity to 1 and renew the listing on etsy.com.

Default"active"

Enum"active""inactive""sold_out""draft""expired"

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

sort_on string

The value to sort a search result of listings on. NOTES: a) sort_on only works when combined with one of the search options (keywords, region, etc.). b) when using score the returned results will always be in _descending_ order, regardless of the sort_order parameter.

Default"created"

Enum"created""price""updated""score"

sort_order string

The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).

Default"desc"

Enum"asc""ascending""desc""descending""up""down"

includes array of string

An enumerated string that attaches a valid association. Acceptable inputs are 'Shipping', 'Shop', 'Images', 'User', 'Translations', 'Videos', 'Inventory' and 'Personalization'.

Defaultnull

Enum"Shipping""Images""Shop""User""Translations""Inventory""Videos""Personalization""BuyerPrice"

Responses

200

A list of Listings

Response schemaapplication/jsonShopListingsWithAssociations

A set of ShopListing resources with associations.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListingWithAssociations

The ShopListing resources found.

ShopListingWithAssociations

A listing from a shop, which contains a product quantity, title, description, price, etc. and additional fields which represent associations.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

The listing's title string. When creating or updating a listing, valid title strings contain only letters, numbers, punctuation marks, mathematical symbols, whitespace characters, ™, ©, and ®. (regex: /[^\p{L}\p{Nd}\p{P}\p{Sm}\p{Zs}™©®]/u) You can only use the %, :, & and + characters once each.

description string

A description string of the product for sale in the listing.

rich_description string nullable

The seller-authored HTML rich-text description of the product when the listing uses rich text; null for plain-text listings. The plain-text description field is always populated. This value is HTML and consumers MUST sanitize it before rendering it in any HTML context.

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

The positive non-zero number of products available for purchase in the listing. Note: The listing quantity is the sum of available offering quantities. You can request the quantities for individual offerings from the ListingInventory resource using the getListingInventory endpoint.

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

A comma-separated list of tag strings for the listing. When creating or updating a listing, valid tag strings contain only letters, numbers, whitespace characters, -, ', ™, ©, and ®. (regex: /[^\p{L}\p{Nd}\p{Zs}\-'™©®]/u) Default value is null.

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

An array of style strings for this listing, each of which is free-form text string such as "Formal", or "Steampunk". When creating or updating a listing, the listing may have up to two styles. Valid style strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Each style string is limited to 45 characters. Default value is null.

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

The positive non-zero price of the product. (Sold product listings are private) Note: The price is the minimum possible price. The getListingInventory method requests exact prices for available offerings.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

The numeric ID of the processing profile associated with the listing. Returned only when the listing is active and of type physical, and the endpoint is either shop-scoped (path contains shop_id) or a single-listing request such as getListing. For every other case this field can be null.

suggested_title string nullable

A title string suggested by Etsy. Only available for a user's own listings, when allow_suggested_title param is present, and when a shop's language setting is English. Not all listings will have suggestions.

shipping_profile object nullable

An array of data representing the shipping profile resource.

ShopShippingProfile

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

title string nullable

The name string of this shipping profile.

user_id integer <int64> ≥ 1

The numeric ID for the user who owns the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

is_deleted boolean

When true, someone deleted this shipping profile.

shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

origin_postal_code string nullable

profile_type string

Default"manual"

Enum"manual""calculated"

domestic_handling_fee number <float> ≥ 0

The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

international_handling_fee number <float> ≥ 0

The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

user object nullable

Represents a single user of the site

User

user_id integer <int64> ≥ 1

The numeric ID of a user. This number is also a valid shop ID for the user's shop.

primary_email string <email> nullable

An email address string for the user's primary email address. Access to this field is granted on a case by case basis for third-party integrations that require full access

first_name string nullable

The user's first name.

last_name string nullable

The user's last name.

image_url_75x75 string nullable

The user's avatar URL.

shop object nullable

A shop created by an Etsy user.

Shop

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

user_id integer <int64> ≥ 1

The numeric user ID of the user who owns this shop.

shop_name string

The shop's name string.

create_date integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

title string nullable

A brief heading string for the shop's main page.

announcement string nullable

An announcement string to buyers that displays on the shop's homepage.

currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

is_vacation boolean

When true, this shop is not accepting purchases.

vacation_message string nullable

The shop's message string displayed when is_vacation is true.

sale_message string nullable

A message string sent to users who complete a purchase from this shop.

digital_sale_message string nullable

A message string sent to users who purchase a digital item from this shop.

update_date integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

updated_timestamp integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

listing_active_count integer <int64> ≥ 0

The number of active listings in the shop.

digital_listing_count integer <int64> ≥ 0

The number of digital listings in the shop.

login_name string

The shop owner's login name string.

accepts_custom_requests boolean

When true, the shop accepts customization requests.

policy_welcome string nullable

The shop's policy welcome string (may be blank).

policy_payment string nullable

The shop's payment policy string (may be blank).

policy_shipping string nullable

The shop's shipping policy string (may be blank).

policy_refunds string nullable

The shop's refund policy string (may be blank).

policy_additional string nullable

The shop's additional policies string (may be blank).

policy_seller_info string nullable

The shop's seller information string (may be blank).

policy_update_date integer <int64> ≥ 0

The date and time of the last update to the shop's policies, in epoch seconds.

policy_has_private_receipt_info boolean

When true, EU receipts display private info.

has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

policy_privacy string nullable

The shop's privacy policy string (may be blank).

vacation_autoreply string nullable

The shop's automatic reply string displayed in new conversations when is_vacation is true.

url string

The URL string for this shop.

image_url_760x100 string nullable

The URL string for this shop's banner image.

num_favorers integer <int64> ≥ 0

The number of users who marked this shop a favorite.

languages array of string

A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.

icon_url_fullxfull string nullable

The URL string for this shop's icon image.

is_using_structured_policies boolean

When true, the shop accepted using structured policies.

has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

is_direct_checkout_onboarded boolean

(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.

is_etsy_payments_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

is_calculated_eligible boolean

When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)

is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

is_shop_us_based boolean

When true, the shop is based in the US.

transaction_sold_count integer <int64> ≥ 0

The total number of sales (transactions) for this shop.

shipping_from_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO the shop is shipping from.

shop_location_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO where the shop is located.

review_count integer <int64> nullable

Number of reviews of shop listings in the past year.

review_average number <float> nullable

Average rating based on reviews of shop listings in the past year.

images array of ListingImage

Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image

ListingImage

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> ≥ 1

The numeric ID of the primary listing image for this transaction.

hex_code string nullable

The webhex string for the image's average color, in webhex notation.

red integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

green integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

blue integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

hue integer <int64> nullable≥ 0

The numeric hue equal to the image's average hue, from 0-360 (HSV color).

saturation integer <int64> nullable≥ 0

The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).

brightness integer <int64> nullable≥ 0

The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).

is_black_and_white boolean nullable

When true, the image is in black & white.

creation_tsz integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

url_75x75 string

The url string for a 75x75 pixel thumbnail of the image.

url_170x135 string

The url string for a 170x135 pixel thumbnail of the image.

url_570xN string

The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.

url_fullxfull string

The url string for the full-size image, up to 3000 pixels in each dimension.

full_height integer <int64> nullable≥ 0

The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.

full_width integer <int64> nullable≥ 0

The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.

alt_text string nullable

Alt text for the listing image. Max length 500 characters.

videos array of ListingVideo

The single video associated with a listing.

ListingVideo

Reference urls and metadata for a video associated with a specific listing.

video_id integer <int64> ≥ 1

The unique ID of a video associated with a listing.

height integer <int64>

The video height dimension in pixels.

width integer <int64>

The video width dimension in pixels.

thumbnail_url string

The url of the video thumbnail.

video_url string

The url of the video file.

video_state string

The current state of a given video. Value is one of active, inactive, deleted or flagged.

Default"active"

Enum"active""inactive""deleted""flagged"

inventory object nullable

An enumerated string that attaches a valid association. Default value is null.

ListingInventory

A representation of a single listing's inventory record.

products array of ListingInventoryProduct

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

ListingInventoryProduct

A representation of a product for a listing.

product_id integer <int64> ≥ 1

The numeric ID for a specific product purchased from a listing.

sku string

The SKU string for the product

is_deleted boolean

When true, someone deleted this product.

offerings array of ListingInventoryProductOffering

A list of product offering entries for this product.

ListingInventoryProductOffering

A representation of an offering for a listing.

offering_id integer <int64> ≥ 1

The ID for the ProductOffering

quantity integer <int64> ≥ 0

The quantity the ProductOffering

is_enabled boolean

Whether or not the offering can be shown to buyers.

is_deleted boolean

Whether or not the offering has been deleted.

price object

Price data for this ProductOffering

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

readiness_state_id integer <int64> nullable≥ 1

Processing Profile for this ProductOffering

property_values array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

price_on_property array of integer <int64>

An array of unique listing property ID integers for the properties that change product prices, if any. For example, if you charge specific prices for different sized products in the same listing, then this array contains the property ID for size.

quantity_on_property array of integer <int64>

An array of unique listing property ID integers for the properties that change the quantity of the products, if any. For example, if you stock specific quantities of different colored products in the same listing, then this array contains the property ID for color.

sku_on_property array of integer <int64>

An array of unique listing property ID integers for the properties that change the product SKU, if any. For example, if you use specific skus for different colored products in the same listing, then this array contains the property ID for color.

readiness_state_on_property array of integer <int64>

An array of unique listing property ID integers for the properties that change processing profile, if any. For example, if you need specific processing profiles for different colored products in the same listing, then this array contains the property ID for color.

production_partners array of ShopProductionPartner

Represents a list of production partners for a shop.

ShopProductionPartner

Represents a description of a shop production partner.

production_partner_id integer <int64> ≥ 1

The numeric ID of a production partner.

partner_name string

The name or title of the production partner.

location string

A string representing the production partner location.

skus array of string

A list of SKU strings for the listing. SKUs will only appear if the requesting user owns the shop and a valid matching OAuth 2 token is provided. When requested without the token it will be an empty array.

translations object nullable

A map of translations for the listing. Default value is a map of all supported languages keyed to null.

ListingTranslations

Container for all current supported translations of a listing. Note that Etsy periodically adds/removes languages, so this list may change in the future.

de object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-GB object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-IN object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-US object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

es object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

fr object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

it object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ja object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

nl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pt object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ru object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

sv object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

views integer <int64>

The number of times the listing has been viewed. This value is tabulated once per day and **only for active listings**, so the value is not real-time. If 0, the listing has either not been viewed, not yet tabulated, was not active during the last tabulation or there was an error fetching the value. If a value is expected, call getListing to confirm the value.

personalization object nullable

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization

personalization_questions array of Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

question_id integer <int64> nullable≥ 1

question_text string

instructions string nullable

question_type string

required boolean

max_allowed_characters integer <int64> nullable

max_allowed_files integer <int64> nullable

add_on_price object nullable

A representation of an amount of money.

Money

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

options array of object nullable

item

option_id integer <int64> required nullable≥ 1

label string required

buyer_price object nullable

The buyer-facing price for a listing, including VAT, inclusive shipping (UK), and active promotions. Requires buyer_country parameter. Shows base_price, shipping_cost, original_price (display price), and discounted_price if a promotion is active. Currently only supported on the /listings/batch endpoint.

ListingBuyerPrice

The buyer-facing price for a listing, including VAT, inclusive shipping (UK), and active promotions.

base_price object

The pre-discount listing price with VAT applied, excluding shipping. When a promotion is active, this is the price before the discount is applied.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object nullable

The shipping cost to the buyer's country. Includes VAT where applicable. Null when shipping is free or unavailable — use is_free_shipping to distinguish.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

is_free_shipping boolean

Whether shipping is free to the buyer's country.

original_price object

The display price. For UK buyers, includes base + shipping (DMCC). For others, base price only.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discounted_price object nullable

The sale price. For UK buyers, includes base + shipping. For others, base price only. Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_amount object nullable

The discount amount as money (original_price - discounted_price). Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_percentage integer <int64> nullable

The discount percentage (e.g. 20 for 20% off). Null if no active promotion or if the promotion is a fixed-amount discount.

has_discount boolean

Whether an active promotion applies to this listing.

discount_start_epoch integer <int64> nullable

The start timestamp of the active promotion. Null if no active promotion.

discount_end_epoch integer <int64> nullable

The end timestamp of the active promotion. Null if no active promotion.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string",
      "shipping_profile": {
        "shipping_profile_id": 1,
        "title": "string",
        "user_id": 1,
        "origin_country_iso": "string",
        "is_deleted": true,
        "shipping_profile_destinations": [
          {
            "shipping_profile_destination_id": 1,
            "shipping_profile_id": 1,
            "origin_country_iso": "string",
            "destination_country_iso": "string",
            "destination_region": "eu",
            "primary_cost": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "secondary_cost": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "shipping_carrier_id": 0,
            "mail_class": "string",
            "min_delivery_days": 1,
            "max_delivery_days": 1
          }
        ],
        "shipping_profile_upgrades": [
          {
            "shipping_profile_id": 1,
            "upgrade_id": 1,
            "upgrade_name": "string",
            "type": 0,
            "rank": 0,
            "language": "string",
            "price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "secondary_price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "shipping_carrier_id": 0,
            "mail_class": "string",
            "min_delivery_days": 1,
            "max_delivery_days": 1
          }
        ],
        "origin_postal_code": "string",
        "profile_type": "manual",
        "domestic_handling_fee": 0,
        "international_handling_fee": 0
      },
      "user": {
        "user_id": 1,
        "primary_email": "string",
        "first_name": "string",
        "last_name": "string",
        "image_url_75x75": "string"
      },
      "shop": {
        "shop_id": 1,
        "user_id": 1,
        "shop_name": "string",
        "create_date": 0,
        "created_timestamp": 0,
        "title": "string",
        "announcement": "string",
        "currency_code": "string",
        "is_vacation": true,
        "vacation_message": "string",
        "sale_message": "string",
        "digital_sale_message": "string",
        "update_date": 0,
        "updated_timestamp": 0,
        "listing_active_count": 0,
        "digital_listing_count": 0,
        "login_name": "string",
        "accepts_custom_requests": true,
        "policy_welcome": "string",
        "policy_payment": "string",
        "policy_shipping": "string",
        "policy_refunds": "string",
        "policy_additional": "string",
        "policy_seller_info": "string",
        "policy_update_date": 0,
        "policy_has_private_receipt_info": true,
        "has_unstructured_policies": true,
        "policy_privacy": "string",
        "vacation_autoreply": "string",
        "url": "string",
        "image_url_760x100": "string",
        "num_favorers": 0,
        "languages": [
          "string"
        ],
        "icon_url_fullxfull": "string",
        "is_using_structured_policies": true,
        "has_onboarded_structured_policies": true,
        "include_dispute_form_link": true,
        "is_direct_checkout_onboarded": true,
        "is_etsy_payments_onboarded": true,
        "is_calculated_eligible": true,
        "is_opted_in_to_buyer_promise": true,
        "is_shop_us_based": true,
        "transaction_sold_count": 0,
        "shipping_from_country_iso": "string",
        "shop_location_country_iso": "string",
        "review_count": 0,
        "review_average": 0.0
      },
      "images": [
        {
          "listing_id": 1,
          "listing_image_id": 1,
          "hex_code": "string",
          "red": 0,
          "green": 0,
          "blue": 0,
          "hue": 0,
          "saturation": 0,
          "brightness": 0,
          "is_black_and_white": true,
          "creation_tsz": 0,
          "created_timestamp": 0,
          "rank": 0,
          "url_75x75": "string",
          "url_170x135": "string",
          "url_570xN": "string",
          "url_fullxfull": "string",
          "full_height": 0,
          "full_width": 0,
          "alt_text": "string"
        }
      ],
      "videos": [
        {
          "video_id": 1,
          "height": 0,
          "width": 0,
          "thumbnail_url": "string",
          "video_url": "string",
          "video_state": "active"
        }
      ],
      "inventory": {
        "products": [
          {
            "product_id": 1,
            "sku": "string",
            "is_deleted": true,
            "offerings": [
              {
                "offering_id": 1,
                "quantity": 0,
                "is_enabled": true,
                "is_deleted": true,
                "price": {},
                "readiness_state_id": 1
              }
            ],
            "property_values": [
              {
                "property_id": 1,
                "property_name": "string",
                "scale_id": 1,
                "scale_name": "string",
                "value_ids": [
                  1
                ],
                "values": [
                  "string"
                ]
              }
            ]
          }
        ],
        "price_on_property": [
          0
        ],
        "quantity_on_property": [
          0
        ],
        "sku_on_property": [
          0
        ],
        "readiness_state_on_property": [
          1
        ]
      },
      "production_partners": [
        {
          "production_partner_id": 1,
          "partner_name": "string",
          "location": "string"
        }
      ],
      "skus": [
        "string"
      ],
      "translations": {
        "de": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-GB": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-IN": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-US": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "es": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "fr": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "it": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "ja": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "nl": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "pl": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "pt": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "ru": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "sv": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        }
      },
      "views": 0,
      "personalization": {
        "personalization_questions": [
          {
            "question_id": 1,
            "question_text": "string",
            "instructions": "string",
            "question_type": "string",
            "required": true,
            "max_allowed_characters": 0,
            "max_allowed_files": 0,
            "add_on_price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "options": [
              {
                "option_id": 1,
                "label": "string"
              }
            ]
          }
        ]
      },
      "buyer_price": {
        "base_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "shipping_cost": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "is_free_shipping": true,
        "original_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discounted_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discount_amount": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discount_percentage": 0,
        "has_discount": true,
        "discount_start_epoch": 0,
        "discount_end_epoch": 0
      }
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#createDraftListing

POSThttps://eto.tools/api/v1/shops/{shop_id}/listings

General Release

This endpoint is ready for production use.

Creates a physical draft listing product in a shop on the Etsy channel.

AuthorizationAPI keyconnected storeoperation shop_listings

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Request bodyapplication/x-www-form-urlencoded

quantity integer <int64> required

title string required

description string required

A description string of the product for sale in the listing.

price number <float> required

who_made string required

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string required

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

taxonomy_id integer <int64> required ≥ 1

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

materials array of string nullable

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shop_section_id integer <int64> nullable≥ 1

The numeric ID of the shop section for this listing. Default value is null.

processing_min integer <int64> nullable

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable

The maximum number of days required to process this listing. Default value is null.

readiness_state_id integer <int64> nullable≥ 1

tags array of string nullable

styles array of string nullable

item_weight number <float> nullable≥ 0≤ 1.79769313486e+308

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_length number <float> nullable≥ 0≤ 1.79769313486e+308

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable≥ 0≤ 1.79769313486e+308

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable≥ 0≤ 1.79769313486e+308

The numeric height of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_personalizable boolean

[DEPRECATED] When true, this listing is personalizable. The default value is false. NOTE: This field will be removed on Apr. 9th, 2026. See https://developers.etsy.com/documentation/tutorials/personalization-migration for migration details.

personalization_is_required boolean

[DEPRECATED] When true, this listing requires personalization. The default value is false. NOTE: This field will be removed on Apr. 9th, 2026. See https://developers.etsy.com/documentation/tutorials/personalization-migration for migration details.

personalization_char_count_max integer <int64>

[DEPRECATED] This is an integer value representing the maximum length for the personalization message entered by the buyer. Will only change if is_personalizable is 'true'. Note: This field will be removed on Apr. 9th, 2026. See https://developers.etsy.com/documentation/tutorials/personalization-migration for migration details.

personalization_instructions string

[DEPRECATED] A string representing instructions for the buyer to enter the personalization. Will only change if is_personalizable is 'true'. Note: This field will be removed on Apr. 9th, 2026. See https://developers.etsy.com/documentation/tutorials/personalization-migration for migration details.

production_partner_ids array of integer <int64> nullable

An array of unique IDs of production partner ids.

image_ids array of integer <int64> nullable

An array of numeric image IDs of the images in a listing, which can include up to 20 images.

is_supply boolean

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

Responses

201

A single ShopListing

Response schemaapplication/jsonShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

Example response

201 · application/json

{
  "listing_id": 1,
  "user_id": 1,
  "shop_id": 1,
  "title": "string",
  "description": "string",
  "rich_description": "string",
  "state": "active",
  "creation_timestamp": 946684800,
  "created_timestamp": 946684800,
  "ending_timestamp": 946684800,
  "original_creation_timestamp": 946684800,
  "last_modified_timestamp": 946684800,
  "updated_timestamp": 946684800,
  "state_timestamp": 946684800,
  "quantity": 0,
  "shop_section_id": 1,
  "featured_rank": 0,
  "url": "string",
  "num_favorers": 0,
  "non_taxable": true,
  "is_taxable": true,
  "is_customizable": true,
  "is_personalizable": true,
  "listing_type": "physical",
  "tags": [
    "string"
  ],
  "materials": [
    "string"
  ],
  "shipping_profile_id": 1,
  "return_policy_id": 1,
  "processing_min": 0,
  "processing_max": 0,
  "who_made": "i_did",
  "when_made": "made_to_order",
  "is_supply": true,
  "item_weight": 0.0,
  "item_weight_unit": "oz",
  "item_length": 0.0,
  "item_width": 0.0,
  "item_height": 0.0,
  "item_dimensions_unit": "in",
  "is_private": true,
  "style": [
    "string"
  ],
  "file_data": "string",
  "has_variations": true,
  "should_auto_renew": true,
  "language": "string",
  "price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "converted_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "taxonomy_id": 0,
  "readiness_state_id": 1,
  "suggested_title": "string"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListing

GEThttps://eto.tools/api/v1/listings/{listing_id}

General Release

This endpoint is ready for production use.

Retrieves a listing record by listing ID.

AuthorizationAPI keyoperation listing_detail

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Query parameters

includes array of string

An enumerated string that attaches a valid association. Acceptable inputs are 'Shop', 'Images', 'User', 'Translations', 'Videos', 'Personalization' and 'BuyerPrice'.

Defaultnull

Enum"Images""Shop""User""Translations""Videos""Personalization""BuyerPrice"

language string

The IETF language tag for the language of this translation. Ex: de, en, es, fr, it, ja, nl, pl, pt.

Defaultnull

allow_suggested_title boolean

This parameter will include in the response a suggested title for the listing, if one is available. Since suggestions are only available to the listing's owner, client must submit an oauth_access_token scoped to the owner of the listing.

Responses

200

A single Listing.

Response schemaapplication/jsonShopListingWithAssociations

A listing from a shop, which contains a product quantity, title, description, price, etc. and additional fields which represent associations.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

shipping_profile object nullable

An array of data representing the shipping profile resource.

ShopShippingProfile

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

title string nullable

The name string of this shipping profile.

user_id integer <int64> ≥ 1

The numeric ID for the user who owns the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

is_deleted boolean

When true, someone deleted this shipping profile.

shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

origin_postal_code string nullable

profile_type string

Default"manual"

Enum"manual""calculated"

domestic_handling_fee number <float> ≥ 0

The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

international_handling_fee number <float> ≥ 0

The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

user object nullable

Represents a single user of the site

User

user_id integer <int64> ≥ 1

The numeric ID of a user. This number is also a valid shop ID for the user's shop.

primary_email string <email> nullable

An email address string for the user's primary email address. Access to this field is granted on a case by case basis for third-party integrations that require full access

first_name string nullable

The user's first name.

last_name string nullable

The user's last name.

image_url_75x75 string nullable

The user's avatar URL.

shop object nullable

A shop created by an Etsy user.

Shop

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

user_id integer <int64> ≥ 1

The numeric user ID of the user who owns this shop.

shop_name string

The shop's name string.

create_date integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

title string nullable

A brief heading string for the shop's main page.

announcement string nullable

An announcement string to buyers that displays on the shop's homepage.

currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

is_vacation boolean

When true, this shop is not accepting purchases.

vacation_message string nullable

The shop's message string displayed when is_vacation is true.

sale_message string nullable

A message string sent to users who complete a purchase from this shop.

digital_sale_message string nullable

A message string sent to users who purchase a digital item from this shop.

update_date integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

updated_timestamp integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

listing_active_count integer <int64> ≥ 0

The number of active listings in the shop.

digital_listing_count integer <int64> ≥ 0

The number of digital listings in the shop.

login_name string

The shop owner's login name string.

accepts_custom_requests boolean

When true, the shop accepts customization requests.

policy_welcome string nullable

The shop's policy welcome string (may be blank).

policy_payment string nullable

The shop's payment policy string (may be blank).

policy_shipping string nullable

The shop's shipping policy string (may be blank).

policy_refunds string nullable

The shop's refund policy string (may be blank).

policy_additional string nullable

The shop's additional policies string (may be blank).

policy_seller_info string nullable

The shop's seller information string (may be blank).

policy_update_date integer <int64> ≥ 0

The date and time of the last update to the shop's policies, in epoch seconds.

policy_has_private_receipt_info boolean

When true, EU receipts display private info.

has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

policy_privacy string nullable

The shop's privacy policy string (may be blank).

vacation_autoreply string nullable

The shop's automatic reply string displayed in new conversations when is_vacation is true.

url string

The URL string for this shop.

image_url_760x100 string nullable

The URL string for this shop's banner image.

num_favorers integer <int64> ≥ 0

The number of users who marked this shop a favorite.

languages array of string

A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.

icon_url_fullxfull string nullable

The URL string for this shop's icon image.

is_using_structured_policies boolean

When true, the shop accepted using structured policies.

has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

is_direct_checkout_onboarded boolean

(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.

is_etsy_payments_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

is_calculated_eligible boolean

When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)

is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

is_shop_us_based boolean

When true, the shop is based in the US.

transaction_sold_count integer <int64> ≥ 0

The total number of sales (transactions) for this shop.

shipping_from_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO the shop is shipping from.

shop_location_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO where the shop is located.

review_count integer <int64> nullable

Number of reviews of shop listings in the past year.

review_average number <float> nullable

Average rating based on reviews of shop listings in the past year.

images array of ListingImage

Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image

ListingImage

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> ≥ 1

The numeric ID of the primary listing image for this transaction.

hex_code string nullable

The webhex string for the image's average color, in webhex notation.

red integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

green integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

blue integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

hue integer <int64> nullable≥ 0

The numeric hue equal to the image's average hue, from 0-360 (HSV color).

saturation integer <int64> nullable≥ 0

The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).

brightness integer <int64> nullable≥ 0

The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).

is_black_and_white boolean nullable

When true, the image is in black & white.

creation_tsz integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

url_75x75 string

The url string for a 75x75 pixel thumbnail of the image.

url_170x135 string

The url string for a 170x135 pixel thumbnail of the image.

url_570xN string

The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.

url_fullxfull string

The url string for the full-size image, up to 3000 pixels in each dimension.

full_height integer <int64> nullable≥ 0

The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.

full_width integer <int64> nullable≥ 0

The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.

alt_text string nullable

Alt text for the listing image. Max length 500 characters.

videos array of ListingVideo

The single video associated with a listing.

ListingVideo

Reference urls and metadata for a video associated with a specific listing.

video_id integer <int64> ≥ 1

The unique ID of a video associated with a listing.

height integer <int64>

The video height dimension in pixels.

width integer <int64>

The video width dimension in pixels.

thumbnail_url string

The url of the video thumbnail.

video_url string

The url of the video file.

video_state string

The current state of a given video. Value is one of active, inactive, deleted or flagged.

Default"active"

Enum"active""inactive""deleted""flagged"

inventory object nullable

An enumerated string that attaches a valid association. Default value is null.

ListingInventory

A representation of a single listing's inventory record.

products array of ListingInventoryProduct

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

ListingInventoryProduct

A representation of a product for a listing.

product_id integer <int64> ≥ 1

The numeric ID for a specific product purchased from a listing.

sku string

The SKU string for the product

is_deleted boolean

When true, someone deleted this product.

offerings array of ListingInventoryProductOffering

A list of product offering entries for this product.

ListingInventoryProductOffering

A representation of an offering for a listing.

offering_id integer <int64> ≥ 1

The ID for the ProductOffering

quantity integer <int64> ≥ 0

The quantity the ProductOffering

is_enabled boolean

Whether or not the offering can be shown to buyers.

is_deleted boolean

Whether or not the offering has been deleted.

price object

Price data for this ProductOffering

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

readiness_state_id integer <int64> nullable≥ 1

Processing Profile for this ProductOffering

property_values array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

price_on_property array of integer <int64>

quantity_on_property array of integer <int64>

sku_on_property array of integer <int64>

readiness_state_on_property array of integer <int64>

production_partners array of ShopProductionPartner

Represents a list of production partners for a shop.

ShopProductionPartner

Represents a description of a shop production partner.

production_partner_id integer <int64> ≥ 1

The numeric ID of a production partner.

partner_name string

The name or title of the production partner.

location string

A string representing the production partner location.

skus array of string

translations object nullable

A map of translations for the listing. Default value is a map of all supported languages keyed to null.

ListingTranslations

Container for all current supported translations of a listing. Note that Etsy periodically adds/removes languages, so this list may change in the future.

de object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-GB object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-IN object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-US object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

es object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

fr object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

it object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ja object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

nl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pt object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ru object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

sv object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

views integer <int64>

personalization object nullable

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization

personalization_questions array of Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

question_id integer <int64> nullable≥ 1

question_text string

instructions string nullable

question_type string

required boolean

max_allowed_characters integer <int64> nullable

max_allowed_files integer <int64> nullable

add_on_price object nullable

A representation of an amount of money.

Money

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

options array of object nullable

item

option_id integer <int64> required nullable≥ 1

label string required

buyer_price object nullable

ListingBuyerPrice

The buyer-facing price for a listing, including VAT, inclusive shipping (UK), and active promotions.

base_price object

The pre-discount listing price with VAT applied, excluding shipping. When a promotion is active, this is the price before the discount is applied.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object nullable

The shipping cost to the buyer's country. Includes VAT where applicable. Null when shipping is free or unavailable — use is_free_shipping to distinguish.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

is_free_shipping boolean

Whether shipping is free to the buyer's country.

original_price object

The display price. For UK buyers, includes base + shipping (DMCC). For others, base price only.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discounted_price object nullable

The sale price. For UK buyers, includes base + shipping. For others, base price only. Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_amount object nullable

The discount amount as money (original_price - discounted_price). Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_percentage integer <int64> nullable

The discount percentage (e.g. 20 for 20% off). Null if no active promotion or if the promotion is a fixed-amount discount.

has_discount boolean

Whether an active promotion applies to this listing.

discount_start_epoch integer <int64> nullable

The start timestamp of the active promotion. Null if no active promotion.

discount_end_epoch integer <int64> nullable

The end timestamp of the active promotion. Null if no active promotion.

Example response

200 · application/json

{
  "listing_id": 1,
  "user_id": 1,
  "shop_id": 1,
  "title": "string",
  "description": "string",
  "rich_description": "string",
  "state": "active",
  "creation_timestamp": 946684800,
  "created_timestamp": 946684800,
  "ending_timestamp": 946684800,
  "original_creation_timestamp": 946684800,
  "last_modified_timestamp": 946684800,
  "updated_timestamp": 946684800,
  "state_timestamp": 946684800,
  "quantity": 0,
  "shop_section_id": 1,
  "featured_rank": 0,
  "url": "string",
  "num_favorers": 0,
  "non_taxable": true,
  "is_taxable": true,
  "is_customizable": true,
  "is_personalizable": true,
  "listing_type": "physical",
  "tags": [
    "string"
  ],
  "materials": [
    "string"
  ],
  "shipping_profile_id": 1,
  "return_policy_id": 1,
  "processing_min": 0,
  "processing_max": 0,
  "who_made": "i_did",
  "when_made": "made_to_order",
  "is_supply": true,
  "item_weight": 0.0,
  "item_weight_unit": "oz",
  "item_length": 0.0,
  "item_width": 0.0,
  "item_height": 0.0,
  "item_dimensions_unit": "in",
  "is_private": true,
  "style": [
    "string"
  ],
  "file_data": "string",
  "has_variations": true,
  "should_auto_renew": true,
  "language": "string",
  "price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "converted_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "taxonomy_id": 0,
  "readiness_state_id": 1,
  "suggested_title": "string",
  "shipping_profile": {
    "shipping_profile_id": 1,
    "title": "string",
    "user_id": 1,
    "origin_country_iso": "string",
    "is_deleted": true,
    "shipping_profile_destinations": [
      {
        "shipping_profile_destination_id": 1,
        "shipping_profile_id": 1,
        "origin_country_iso": "string",
        "destination_country_iso": "string",
        "destination_region": "eu",
        "primary_cost": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "secondary_cost": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "shipping_carrier_id": 0,
        "mail_class": "string",
        "min_delivery_days": 1,
        "max_delivery_days": 1
      }
    ],
    "shipping_profile_upgrades": [
      {
        "shipping_profile_id": 1,
        "upgrade_id": 1,
        "upgrade_name": "string",
        "type": 0,
        "rank": 0,
        "language": "string",
        "price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "secondary_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "shipping_carrier_id": 0,
        "mail_class": "string",
        "min_delivery_days": 1,
        "max_delivery_days": 1
      }
    ],
    "origin_postal_code": "string",
    "profile_type": "manual",
    "domestic_handling_fee": 0,
    "international_handling_fee": 0
  },
  "user": {
    "user_id": 1,
    "primary_email": "string",
    "first_name": "string",
    "last_name": "string",
    "image_url_75x75": "string"
  },
  "shop": {
    "shop_id": 1,
    "user_id": 1,
    "shop_name": "string",
    "create_date": 0,
    "created_timestamp": 0,
    "title": "string",
    "announcement": "string",
    "currency_code": "string",
    "is_vacation": true,
    "vacation_message": "string",
    "sale_message": "string",
    "digital_sale_message": "string",
    "update_date": 0,
    "updated_timestamp": 0,
    "listing_active_count": 0,
    "digital_listing_count": 0,
    "login_name": "string",
    "accepts_custom_requests": true,
    "policy_welcome": "string",
    "policy_payment": "string",
    "policy_shipping": "string",
    "policy_refunds": "string",
    "policy_additional": "string",
    "policy_seller_info": "string",
    "policy_update_date": 0,
    "policy_has_private_receipt_info": true,
    "has_unstructured_policies": true,
    "policy_privacy": "string",
    "vacation_autoreply": "string",
    "url": "string",
    "image_url_760x100": "string",
    "num_favorers": 0,
    "languages": [
      "string"
    ],
    "icon_url_fullxfull": "string",
    "is_using_structured_policies": true,
    "has_onboarded_structured_policies": true,
    "include_dispute_form_link": true,
    "is_direct_checkout_onboarded": true,
    "is_etsy_payments_onboarded": true,
    "is_calculated_eligible": true,
    "is_opted_in_to_buyer_promise": true,
    "is_shop_us_based": true,
    "transaction_sold_count": 0,
    "shipping_from_country_iso": "string",
    "shop_location_country_iso": "string",
    "review_count": 0,
    "review_average": 0.0
  },
  "images": [
    {
      "listing_id": 1,
      "listing_image_id": 1,
      "hex_code": "string",
      "red": 0,
      "green": 0,
      "blue": 0,
      "hue": 0,
      "saturation": 0,
      "brightness": 0,
      "is_black_and_white": true,
      "creation_tsz": 0,
      "created_timestamp": 0,
      "rank": 0,
      "url_75x75": "string",
      "url_170x135": "string",
      "url_570xN": "string",
      "url_fullxfull": "string",
      "full_height": 0,
      "full_width": 0,
      "alt_text": "string"
    }
  ],
  "videos": [
    {
      "video_id": 1,
      "height": 0,
      "width": 0,
      "thumbnail_url": "string",
      "video_url": "string",
      "video_state": "active"
    }
  ],
  "inventory": {
    "products": [
      {
        "product_id": 1,
        "sku": "string",
        "is_deleted": true,
        "offerings": [
          {
            "offering_id": 1,
            "quantity": 0,
            "is_enabled": true,
            "is_deleted": true,
            "price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "readiness_state_id": 1
          }
        ],
        "property_values": [
          {
            "property_id": 1,
            "property_name": "string",
            "scale_id": 1,
            "scale_name": "string",
            "value_ids": [
              1
            ],
            "values": [
              "string"
            ]
          }
        ]
      }
    ],
    "price_on_property": [
      0
    ],
    "quantity_on_property": [
      0
    ],
    "sku_on_property": [
      0
    ],
    "readiness_state_on_property": [
      1
    ]
  },
  "production_partners": [
    {
      "production_partner_id": 1,
      "partner_name": "string",
      "location": "string"
    }
  ],
  "skus": [
    "string"
  ],
  "translations": {
    "de": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "en-GB": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "en-IN": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "en-US": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "es": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "fr": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "it": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "ja": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "nl": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "pl": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "pt": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "ru": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    },
    "sv": {
      "listing_id": 1,
      "language": "string",
      "title": "string",
      "description": "string",
      "tags": [
        "string"
      ]
    }
  },
  "views": 0,
  "personalization": {
    "personalization_questions": [
      {
        "question_id": 1,
        "question_text": "string",
        "instructions": "string",
        "question_type": "string",
        "required": true,
        "max_allowed_characters": 0,
        "max_allowed_files": 0,
        "add_on_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "options": [
          {
            "option_id": 1,
            "label": "string"
          }
        ]
      }
    ]
  },
  "buyer_price": {
    "base_price": {
      "amount": 0,
      "divisor": 0,
      "currency_code": "string"
    },
    "shipping_cost": {
      "amount": 0,
      "divisor": 0,
      "currency_code": "string"
    },
    "is_free_shipping": true,
    "original_price": {
      "amount": 0,
      "divisor": 0,
      "currency_code": "string"
    },
    "discounted_price": {
      "amount": 0,
      "divisor": 0,
      "currency_code": "string"
    },
    "discount_amount": {
      "amount": 0,
      "divisor": 0,
      "currency_code": "string"
    },
    "discount_percentage": 0,
    "has_discount": true,
    "discount_start_epoch": 0,
    "discount_end_epoch": 0
  }
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#deleteListing

DELETEhttps://eto.tools/api/v1/listings/{listing_id}

General Release

This endpoint is ready for production use.

Open API V3 endpoint to delete a ShopListing. A ShopListing can be deleted only if the state is one of the following: SOLD_OUT, DRAFT, EXPIRED, INACTIVE, ACTIVE and is_available or ACTIVE and has seller flags: SUPRESSED (frozen), VACATION, CUSTOM_SHOPS (pattern), SELL_ON_FACEBOOK

AuthorizationAPI keyconnected storeoperation listing_detail

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Responses

204

The Listing resource was correctly deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#findAllListingsActive

GEThttps://eto.tools/api/v1/listings/search

General Release

This endpoint is ready for production use.

A list of all active listings on Etsy paginated by their creation date. Without sort_order listings will be returned newest-first by default.

AuthorizationAPI keyoperation listings_search

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

keywords string

Search term or phrase that must appear in all results.

Defaultnull

sort_on string

Default"created"

Enum"created""price""updated""score"

sort_order string

The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).

Default"desc"

Enum"asc""ascending""desc""descending""up""down"

min_price number <float>

The minimum price of listings to be returned by a search result.

Defaultnull

max_price number <float>

The maximum price of listings to be returned by a search result.

Defaultnull

taxonomy_id integer <int64> ≥ 1

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

Defaultnull

shop_location string

Filters by shop location. If location cannot be parsed, Etsy responds with an error.

Defaultnull

is_safe boolean

When true, filters out mature/adult content from search results.

currency string

The ISO 4217 alphabetic currency code (e.g., EUR, MXN) for price conversion. If provided, the listing price will be converted to this currency.

Defaultnull

buyer_country string <ISO 3166-1 alpha-2>

The ISO 3166-1 alpha-2 country code (e.g., DE, MX). Filters results to listings that ship to this country.

Defaultnull

Responses

200

A list of all active listings on Etsy paginated by their creation date. Without sort_order listings will be returned newest-first by default.

Response schemaapplication/jsonShopListings

A set of ShopListing resources.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListing

The ShopListing resources found.

ShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string"
    }
  ]
}

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#findAllActiveListingsByShop

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/active

General Release

This endpoint is ready for production use.

Retrieves a list of all active listings on Etsy in a specific shop, paginated by listing creation date.

AuthorizationAPI keyoperation shop_active_listings

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

sort_on string

Default"created"

Enum"created""price""updated""score"

sort_order string

The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).

Default"desc"

Enum"asc""ascending""desc""descending""up""down"

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

keywords string

Search term or phrase that must appear in all results.

Defaultnull

Responses

200

Retrieves a list of all active listings on Etsy in a specific shop, paginated by listing creation date.

Response schemaapplication/jsonShopListings

A set of ShopListing resources.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListing

The ShopListing resources found.

ShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingsByListingIds

GEThttps://eto.tools/api/v1/listings/batch

General Release

This endpoint is ready for production use.

Allows to query multiple listing ids at once. Limit 100 ids maximum per query.

AuthorizationAPI keyoperation listings_batch

Query parameters

listing_ids array of integer <int64> required

The list of numeric IDS for the listings in a specific Etsy shop.

includes array of string

An enumerated string that attaches a valid association. Acceptable inputs are 'Shop', 'Images', 'User', 'Translations', 'Videos', 'Personalization' and 'BuyerPrice'.

Defaultnull

Enum"Images""Shop""User""Translations""Videos""Personalization""BuyerPrice"

legacy boolean

This parameter is needed to enable new parameters and response values related to processing profiles.

currency string

The ISO 4217 alphabetic currency code (e.g., EUR, MXN) for price conversion. If provided, the listing price will be converted to this currency.

Defaultnull

buyer_country string <ISO 3166-1 alpha-2>

The ISO 3166-1 alpha-2 country code (e.g., GB, DE). Used for buyer-facing price calculations (VAT, inclusive shipping). Does not filter listings.

Defaultnull

Responses

200

A list of Listings

Response schemaapplication/jsonShopListingsWithAssociations

A set of ShopListing resources with associations.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListingWithAssociations

The ShopListing resources found.

ShopListingWithAssociations

A listing from a shop, which contains a product quantity, title, description, price, etc. and additional fields which represent associations.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

shipping_profile object nullable

An array of data representing the shipping profile resource.

ShopShippingProfile

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

title string nullable

The name string of this shipping profile.

user_id integer <int64> ≥ 1

The numeric ID for the user who owns the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

is_deleted boolean

When true, someone deleted this shipping profile.

shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

origin_postal_code string nullable

profile_type string

Default"manual"

Enum"manual""calculated"

domestic_handling_fee number <float> ≥ 0

The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

international_handling_fee number <float> ≥ 0

The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

user object nullable

Represents a single user of the site

User

user_id integer <int64> ≥ 1

The numeric ID of a user. This number is also a valid shop ID for the user's shop.

primary_email string <email> nullable

An email address string for the user's primary email address. Access to this field is granted on a case by case basis for third-party integrations that require full access

first_name string nullable

The user's first name.

last_name string nullable

The user's last name.

image_url_75x75 string nullable

The user's avatar URL.

shop object nullable

A shop created by an Etsy user.

Shop

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

user_id integer <int64> ≥ 1

The numeric user ID of the user who owns this shop.

shop_name string

The shop's name string.

create_date integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

title string nullable

A brief heading string for the shop's main page.

announcement string nullable

An announcement string to buyers that displays on the shop's homepage.

currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

is_vacation boolean

When true, this shop is not accepting purchases.

vacation_message string nullable

The shop's message string displayed when is_vacation is true.

sale_message string nullable

A message string sent to users who complete a purchase from this shop.

digital_sale_message string nullable

A message string sent to users who purchase a digital item from this shop.

update_date integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

updated_timestamp integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

listing_active_count integer <int64> ≥ 0

The number of active listings in the shop.

digital_listing_count integer <int64> ≥ 0

The number of digital listings in the shop.

login_name string

The shop owner's login name string.

accepts_custom_requests boolean

When true, the shop accepts customization requests.

policy_welcome string nullable

The shop's policy welcome string (may be blank).

policy_payment string nullable

The shop's payment policy string (may be blank).

policy_shipping string nullable

The shop's shipping policy string (may be blank).

policy_refunds string nullable

The shop's refund policy string (may be blank).

policy_additional string nullable

The shop's additional policies string (may be blank).

policy_seller_info string nullable

The shop's seller information string (may be blank).

policy_update_date integer <int64> ≥ 0

The date and time of the last update to the shop's policies, in epoch seconds.

policy_has_private_receipt_info boolean

When true, EU receipts display private info.

has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

policy_privacy string nullable

The shop's privacy policy string (may be blank).

vacation_autoreply string nullable

The shop's automatic reply string displayed in new conversations when is_vacation is true.

url string

The URL string for this shop.

image_url_760x100 string nullable

The URL string for this shop's banner image.

num_favorers integer <int64> ≥ 0

The number of users who marked this shop a favorite.

languages array of string

A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.

icon_url_fullxfull string nullable

The URL string for this shop's icon image.

is_using_structured_policies boolean

When true, the shop accepted using structured policies.

has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

is_direct_checkout_onboarded boolean

(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.

is_etsy_payments_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

is_calculated_eligible boolean

When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)

is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

is_shop_us_based boolean

When true, the shop is based in the US.

transaction_sold_count integer <int64> ≥ 0

The total number of sales (transactions) for this shop.

shipping_from_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO the shop is shipping from.

shop_location_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO where the shop is located.

review_count integer <int64> nullable

Number of reviews of shop listings in the past year.

review_average number <float> nullable

Average rating based on reviews of shop listings in the past year.

images array of ListingImage

Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image

ListingImage

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> ≥ 1

The numeric ID of the primary listing image for this transaction.

hex_code string nullable

The webhex string for the image's average color, in webhex notation.

red integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

green integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

blue integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

hue integer <int64> nullable≥ 0

The numeric hue equal to the image's average hue, from 0-360 (HSV color).

saturation integer <int64> nullable≥ 0

The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).

brightness integer <int64> nullable≥ 0

The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).

is_black_and_white boolean nullable

When true, the image is in black & white.

creation_tsz integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

url_75x75 string

The url string for a 75x75 pixel thumbnail of the image.

url_170x135 string

The url string for a 170x135 pixel thumbnail of the image.

url_570xN string

The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.

url_fullxfull string

The url string for the full-size image, up to 3000 pixels in each dimension.

full_height integer <int64> nullable≥ 0

The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.

full_width integer <int64> nullable≥ 0

The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.

alt_text string nullable

Alt text for the listing image. Max length 500 characters.

videos array of ListingVideo

The single video associated with a listing.

ListingVideo

Reference urls and metadata for a video associated with a specific listing.

video_id integer <int64> ≥ 1

The unique ID of a video associated with a listing.

height integer <int64>

The video height dimension in pixels.

width integer <int64>

The video width dimension in pixels.

thumbnail_url string

The url of the video thumbnail.

video_url string

The url of the video file.

video_state string

The current state of a given video. Value is one of active, inactive, deleted or flagged.

Default"active"

Enum"active""inactive""deleted""flagged"

inventory object nullable

An enumerated string that attaches a valid association. Default value is null.

ListingInventory

A representation of a single listing's inventory record.

products array of ListingInventoryProduct

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

ListingInventoryProduct

A representation of a product for a listing.

product_id integer <int64> ≥ 1

The numeric ID for a specific product purchased from a listing.

sku string

The SKU string for the product

is_deleted boolean

When true, someone deleted this product.

offerings array of ListingInventoryProductOffering

A list of product offering entries for this product.

ListingInventoryProductOffering

A representation of an offering for a listing.

offering_id integer <int64> ≥ 1

The ID for the ProductOffering

quantity integer <int64> ≥ 0

The quantity the ProductOffering

is_enabled boolean

Whether or not the offering can be shown to buyers.

is_deleted boolean

Whether or not the offering has been deleted.

price object

Price data for this ProductOffering

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

readiness_state_id integer <int64> nullable≥ 1

Processing Profile for this ProductOffering

property_values array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

price_on_property array of integer <int64>

quantity_on_property array of integer <int64>

sku_on_property array of integer <int64>

readiness_state_on_property array of integer <int64>

production_partners array of ShopProductionPartner

Represents a list of production partners for a shop.

ShopProductionPartner

Represents a description of a shop production partner.

production_partner_id integer <int64> ≥ 1

The numeric ID of a production partner.

partner_name string

The name or title of the production partner.

location string

A string representing the production partner location.

skus array of string

translations object nullable

A map of translations for the listing. Default value is a map of all supported languages keyed to null.

ListingTranslations

Container for all current supported translations of a listing. Note that Etsy periodically adds/removes languages, so this list may change in the future.

de object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-GB object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-IN object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-US object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

es object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

fr object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

it object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ja object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

nl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pt object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ru object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

sv object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

views integer <int64>

personalization object nullable

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization

personalization_questions array of Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

question_id integer <int64> nullable≥ 1

question_text string

instructions string nullable

question_type string

required boolean

max_allowed_characters integer <int64> nullable

max_allowed_files integer <int64> nullable

add_on_price object nullable

A representation of an amount of money.

Money

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

options array of object nullable

item

option_id integer <int64> required nullable≥ 1

label string required

buyer_price object nullable

ListingBuyerPrice

The buyer-facing price for a listing, including VAT, inclusive shipping (UK), and active promotions.

base_price object

The pre-discount listing price with VAT applied, excluding shipping. When a promotion is active, this is the price before the discount is applied.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object nullable

The shipping cost to the buyer's country. Includes VAT where applicable. Null when shipping is free or unavailable — use is_free_shipping to distinguish.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

is_free_shipping boolean

Whether shipping is free to the buyer's country.

original_price object

The display price. For UK buyers, includes base + shipping (DMCC). For others, base price only.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discounted_price object nullable

The sale price. For UK buyers, includes base + shipping. For others, base price only. Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_amount object nullable

The discount amount as money (original_price - discounted_price). Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_percentage integer <int64> nullable

The discount percentage (e.g. 20 for 20% off). Null if no active promotion or if the promotion is a fixed-amount discount.

has_discount boolean

Whether an active promotion applies to this listing.

discount_start_epoch integer <int64> nullable

The start timestamp of the active promotion. Null if no active promotion.

discount_end_epoch integer <int64> nullable

The end timestamp of the active promotion. Null if no active promotion.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string",
      "shipping_profile": {
        "shipping_profile_id": 1,
        "title": "string",
        "user_id": 1,
        "origin_country_iso": "string",
        "is_deleted": true,
        "shipping_profile_destinations": [
          {
            "shipping_profile_destination_id": 1,
            "shipping_profile_id": 1,
            "origin_country_iso": "string",
            "destination_country_iso": "string",
            "destination_region": "eu",
            "primary_cost": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "secondary_cost": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "shipping_carrier_id": 0,
            "mail_class": "string",
            "min_delivery_days": 1,
            "max_delivery_days": 1
          }
        ],
        "shipping_profile_upgrades": [
          {
            "shipping_profile_id": 1,
            "upgrade_id": 1,
            "upgrade_name": "string",
            "type": 0,
            "rank": 0,
            "language": "string",
            "price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "secondary_price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "shipping_carrier_id": 0,
            "mail_class": "string",
            "min_delivery_days": 1,
            "max_delivery_days": 1
          }
        ],
        "origin_postal_code": "string",
        "profile_type": "manual",
        "domestic_handling_fee": 0,
        "international_handling_fee": 0
      },
      "user": {
        "user_id": 1,
        "primary_email": "string",
        "first_name": "string",
        "last_name": "string",
        "image_url_75x75": "string"
      },
      "shop": {
        "shop_id": 1,
        "user_id": 1,
        "shop_name": "string",
        "create_date": 0,
        "created_timestamp": 0,
        "title": "string",
        "announcement": "string",
        "currency_code": "string",
        "is_vacation": true,
        "vacation_message": "string",
        "sale_message": "string",
        "digital_sale_message": "string",
        "update_date": 0,
        "updated_timestamp": 0,
        "listing_active_count": 0,
        "digital_listing_count": 0,
        "login_name": "string",
        "accepts_custom_requests": true,
        "policy_welcome": "string",
        "policy_payment": "string",
        "policy_shipping": "string",
        "policy_refunds": "string",
        "policy_additional": "string",
        "policy_seller_info": "string",
        "policy_update_date": 0,
        "policy_has_private_receipt_info": true,
        "has_unstructured_policies": true,
        "policy_privacy": "string",
        "vacation_autoreply": "string",
        "url": "string",
        "image_url_760x100": "string",
        "num_favorers": 0,
        "languages": [
          "string"
        ],
        "icon_url_fullxfull": "string",
        "is_using_structured_policies": true,
        "has_onboarded_structured_policies": true,
        "include_dispute_form_link": true,
        "is_direct_checkout_onboarded": true,
        "is_etsy_payments_onboarded": true,
        "is_calculated_eligible": true,
        "is_opted_in_to_buyer_promise": true,
        "is_shop_us_based": true,
        "transaction_sold_count": 0,
        "shipping_from_country_iso": "string",
        "shop_location_country_iso": "string",
        "review_count": 0,
        "review_average": 0.0
      },
      "images": [
        {
          "listing_id": 1,
          "listing_image_id": 1,
          "hex_code": "string",
          "red": 0,
          "green": 0,
          "blue": 0,
          "hue": 0,
          "saturation": 0,
          "brightness": 0,
          "is_black_and_white": true,
          "creation_tsz": 0,
          "created_timestamp": 0,
          "rank": 0,
          "url_75x75": "string",
          "url_170x135": "string",
          "url_570xN": "string",
          "url_fullxfull": "string",
          "full_height": 0,
          "full_width": 0,
          "alt_text": "string"
        }
      ],
      "videos": [
        {
          "video_id": 1,
          "height": 0,
          "width": 0,
          "thumbnail_url": "string",
          "video_url": "string",
          "video_state": "active"
        }
      ],
      "inventory": {
        "products": [
          {
            "product_id": 1,
            "sku": "string",
            "is_deleted": true,
            "offerings": [
              {
                "offering_id": 1,
                "quantity": 0,
                "is_enabled": true,
                "is_deleted": true,
                "price": {},
                "readiness_state_id": 1
              }
            ],
            "property_values": [
              {
                "property_id": 1,
                "property_name": "string",
                "scale_id": 1,
                "scale_name": "string",
                "value_ids": [
                  1
                ],
                "values": [
                  "string"
                ]
              }
            ]
          }
        ],
        "price_on_property": [
          0
        ],
        "quantity_on_property": [
          0
        ],
        "sku_on_property": [
          0
        ],
        "readiness_state_on_property": [
          1
        ]
      },
      "production_partners": [
        {
          "production_partner_id": 1,
          "partner_name": "string",
          "location": "string"
        }
      ],
      "skus": [
        "string"
      ],
      "translations": {
        "de": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-GB": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-IN": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-US": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "es": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "fr": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "it": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "ja": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "nl": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "pl": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "pt": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "ru": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "sv": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        }
      },
      "views": 0,
      "personalization": {
        "personalization_questions": [
          {
            "question_id": 1,
            "question_text": "string",
            "instructions": "string",
            "question_type": "string",
            "required": true,
            "max_allowed_characters": 0,
            "max_allowed_files": 0,
            "add_on_price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "options": [
              {
                "option_id": 1,
                "label": "string"
              }
            ]
          }
        ]
      },
      "buyer_price": {
        "base_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "shipping_cost": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "is_free_shipping": true,
        "original_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discounted_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discount_amount": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discount_percentage": 0,
        "has_discount": true,
        "discount_start_epoch": 0,
        "discount_end_epoch": 0
      }
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getFeaturedListingsByShop

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/featured

General Release

This endpoint is ready for production use.

Retrieves Listings associated to a Shop that are featured.

AuthorizationAPI keyoperation shop_featured_listings

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

legacy boolean

This parameter is needed to enable new parameters and response values related to processing profiles.

Responses

200

A list of Listings

Response schemaapplication/jsonShopListings

A set of ShopListing resources.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListing

The ShopListing resources found.

ShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateListingProperty

PUThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/properties/{property_id}

General Release

This endpoint is ready for production use.

Updates or populates the properties list defining product offerings for a listing. Each offering requires both a value and a value_id that are valid for a scale_id assigned to the listing or that you assign to the listing with this request.

AuthorizationAPI keyconnected storeoperation listing_property

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

property_id integer <int64> required ≥ 1

The unique ID of an Etsy listing property.

Request bodyapplication/x-www-form-urlencoded

value_ids array of integer <int64> required

An array of unique IDs of multiple Etsy listing property values. For example, if your listing is composed of different materials, then the value ID list contains value IDs for each material.

values array of string required

An array of value strings for multiple Etsy listing property values. For example, if your listing is painted in different colors, then the values array contains the color strings for each color. Note: parenthesis characters (( and )) are not allowed.

scale_id integer <int64> ≥ 1

The numeric ID of a single Etsy.com measurement scale. For example, for shoe size, there are three scale_ids available - UK, US/Canada, and EU, where US/Canada has scale_id 19.

Responses

200

A single listing property.

Response schemaapplication/jsonListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

Example response

200 · application/json

{
  "property_id": 1,
  "property_name": "string",
  "scale_id": 1,
  "scale_name": "string",
  "value_ids": [
    1
  ],
  "values": [
    "string"
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#deleteListingProperty

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/properties/{property_id}

General Release

This endpoint is ready for production use.

Deletes a property for a Listing.

AuthorizationAPI keyconnected storeoperation listing_property

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

property_id integer <int64> required ≥ 1

The unique ID of an Etsy listing property.

Responses

204

The ListingProperty resource was correctly deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingProperty

GEThttps://eto.tools/api/v1/listings/{listing_id}/properties/{property_id}

Feedback only Give feedback

Development for this endpoint is in progress. It will only return a 501 response.

Retrieves a listing's property

AuthorizationAPI keyoperation listing_property_public

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

property_id integer <int64> required ≥ 1

The unique ID of an Etsy listing property.

Responses

200

A single ListingProperty.

Response schemaapplication/jsonListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

Example response

200 · application/json

{
  "property_id": 1,
  "property_name": "string",
  "scale_id": 1,
  "scale_name": "string",
  "value_ids": [
    1
  ],
  "values": [
    "string"
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

501

This endpoint is not functional at this time.

Response schemaapplication/jsonErrorSchema

error string required

#getListingProperties

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/properties

General Release

This endpoint is ready for production use.

Get a listing's properties

AuthorizationAPI keyoperation listing_properties_all

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Responses

200

A Listing's Properties

Response schemaapplication/jsonListingPropertyValues

Represents several ListingPropertyValues.

count integer <int64> ≥ 0

results array of ListingPropertyValue

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "property_id": 1,
      "property_name": "string",
      "scale_id": 1,
      "scale_name": "string",
      "value_ids": [
        1
      ],
      "values": [
        "string"
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingsShippingByListingIds

GET/v3/application/listings/batch/shipping

Not currently exposed through the Eto API. Documented here for the data model it returns.

General Release

This endpoint is ready for production use.

Retrieves the shipping profile for each listing referenced by listing ID. Requires the shops_r OAuth scope. Limit 100 listing IDs per request. All requested listing IDs must exist — if any single ID is not found, the entire request returns a 404. Shipping profile data (including shipping_profile_id) is only returned for listings owned by the authenticated user; it is nulled out for listings owned by other sellers.

AuthorizationAPI keyconnected store

Query parameters

listing_ids array of integer <int64> required

The list of numeric IDS for the listings in a specific Etsy shop.

Responses

200

A list of listings with their shipping profiles.

Response schemaapplication/jsonShopListingsWithAssociations

A set of ShopListing resources with associations.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListingWithAssociations

The ShopListing resources found.

ShopListingWithAssociations

A listing from a shop, which contains a product quantity, title, description, price, etc. and additional fields which represent associations.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

shipping_profile object nullable

An array of data representing the shipping profile resource.

ShopShippingProfile

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

title string nullable

The name string of this shipping profile.

user_id integer <int64> ≥ 1

The numeric ID for the user who owns the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

is_deleted boolean

When true, someone deleted this shipping profile.

shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

origin_postal_code string nullable

profile_type string

Default"manual"

Enum"manual""calculated"

domestic_handling_fee number <float> ≥ 0

The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

international_handling_fee number <float> ≥ 0

The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

user object nullable

Represents a single user of the site

User

user_id integer <int64> ≥ 1

The numeric ID of a user. This number is also a valid shop ID for the user's shop.

primary_email string <email> nullable

An email address string for the user's primary email address. Access to this field is granted on a case by case basis for third-party integrations that require full access

first_name string nullable

The user's first name.

last_name string nullable

The user's last name.

image_url_75x75 string nullable

The user's avatar URL.

shop object nullable

A shop created by an Etsy user.

Shop

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

user_id integer <int64> ≥ 1

The numeric user ID of the user who owns this shop.

shop_name string

The shop's name string.

create_date integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

title string nullable

A brief heading string for the shop's main page.

announcement string nullable

An announcement string to buyers that displays on the shop's homepage.

currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

is_vacation boolean

When true, this shop is not accepting purchases.

vacation_message string nullable

The shop's message string displayed when is_vacation is true.

sale_message string nullable

A message string sent to users who complete a purchase from this shop.

digital_sale_message string nullable

A message string sent to users who purchase a digital item from this shop.

update_date integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

updated_timestamp integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

listing_active_count integer <int64> ≥ 0

The number of active listings in the shop.

digital_listing_count integer <int64> ≥ 0

The number of digital listings in the shop.

login_name string

The shop owner's login name string.

accepts_custom_requests boolean

When true, the shop accepts customization requests.

policy_welcome string nullable

The shop's policy welcome string (may be blank).

policy_payment string nullable

The shop's payment policy string (may be blank).

policy_shipping string nullable

The shop's shipping policy string (may be blank).

policy_refunds string nullable

The shop's refund policy string (may be blank).

policy_additional string nullable

The shop's additional policies string (may be blank).

policy_seller_info string nullable

The shop's seller information string (may be blank).

policy_update_date integer <int64> ≥ 0

The date and time of the last update to the shop's policies, in epoch seconds.

policy_has_private_receipt_info boolean

When true, EU receipts display private info.

has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

policy_privacy string nullable

The shop's privacy policy string (may be blank).

vacation_autoreply string nullable

The shop's automatic reply string displayed in new conversations when is_vacation is true.

url string

The URL string for this shop.

image_url_760x100 string nullable

The URL string for this shop's banner image.

num_favorers integer <int64> ≥ 0

The number of users who marked this shop a favorite.

languages array of string

A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.

icon_url_fullxfull string nullable

The URL string for this shop's icon image.

is_using_structured_policies boolean

When true, the shop accepted using structured policies.

has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

is_direct_checkout_onboarded boolean

(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.

is_etsy_payments_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

is_calculated_eligible boolean

When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)

is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

is_shop_us_based boolean

When true, the shop is based in the US.

transaction_sold_count integer <int64> ≥ 0

The total number of sales (transactions) for this shop.

shipping_from_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO the shop is shipping from.

shop_location_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO where the shop is located.

review_count integer <int64> nullable

Number of reviews of shop listings in the past year.

review_average number <float> nullable

Average rating based on reviews of shop listings in the past year.

images array of ListingImage

Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image

ListingImage

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> ≥ 1

The numeric ID of the primary listing image for this transaction.

hex_code string nullable

The webhex string for the image's average color, in webhex notation.

red integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

green integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

blue integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

hue integer <int64> nullable≥ 0

The numeric hue equal to the image's average hue, from 0-360 (HSV color).

saturation integer <int64> nullable≥ 0

The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).

brightness integer <int64> nullable≥ 0

The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).

is_black_and_white boolean nullable

When true, the image is in black & white.

creation_tsz integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

url_75x75 string

The url string for a 75x75 pixel thumbnail of the image.

url_170x135 string

The url string for a 170x135 pixel thumbnail of the image.

url_570xN string

The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.

url_fullxfull string

The url string for the full-size image, up to 3000 pixels in each dimension.

full_height integer <int64> nullable≥ 0

The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.

full_width integer <int64> nullable≥ 0

The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.

alt_text string nullable

Alt text for the listing image. Max length 500 characters.

videos array of ListingVideo

The single video associated with a listing.

ListingVideo

Reference urls and metadata for a video associated with a specific listing.

video_id integer <int64> ≥ 1

The unique ID of a video associated with a listing.

height integer <int64>

The video height dimension in pixels.

width integer <int64>

The video width dimension in pixels.

thumbnail_url string

The url of the video thumbnail.

video_url string

The url of the video file.

video_state string

The current state of a given video. Value is one of active, inactive, deleted or flagged.

Default"active"

Enum"active""inactive""deleted""flagged"

inventory object nullable

An enumerated string that attaches a valid association. Default value is null.

ListingInventory

A representation of a single listing's inventory record.

products array of ListingInventoryProduct

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

ListingInventoryProduct

A representation of a product for a listing.

product_id integer <int64> ≥ 1

The numeric ID for a specific product purchased from a listing.

sku string

The SKU string for the product

is_deleted boolean

When true, someone deleted this product.

offerings array of ListingInventoryProductOffering

A list of product offering entries for this product.

ListingInventoryProductOffering

A representation of an offering for a listing.

offering_id integer <int64> ≥ 1

The ID for the ProductOffering

quantity integer <int64> ≥ 0

The quantity the ProductOffering

is_enabled boolean

Whether or not the offering can be shown to buyers.

is_deleted boolean

Whether or not the offering has been deleted.

price object

Price data for this ProductOffering

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

readiness_state_id integer <int64> nullable≥ 1

Processing Profile for this ProductOffering

property_values array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

price_on_property array of integer <int64>

quantity_on_property array of integer <int64>

sku_on_property array of integer <int64>

readiness_state_on_property array of integer <int64>

production_partners array of ShopProductionPartner

Represents a list of production partners for a shop.

ShopProductionPartner

Represents a description of a shop production partner.

production_partner_id integer <int64> ≥ 1

The numeric ID of a production partner.

partner_name string

The name or title of the production partner.

location string

A string representing the production partner location.

skus array of string

translations object nullable

A map of translations for the listing. Default value is a map of all supported languages keyed to null.

ListingTranslations

Container for all current supported translations of a listing. Note that Etsy periodically adds/removes languages, so this list may change in the future.

de object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-GB object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-IN object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-US object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

es object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

fr object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

it object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ja object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

nl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pt object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ru object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

sv object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

views integer <int64>

personalization object nullable

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization

personalization_questions array of Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

question_id integer <int64> nullable≥ 1

question_text string

instructions string nullable

question_type string

required boolean

max_allowed_characters integer <int64> nullable

max_allowed_files integer <int64> nullable

add_on_price object nullable

A representation of an amount of money.

Money

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

options array of object nullable

item

option_id integer <int64> required nullable≥ 1

label string required

buyer_price object nullable

ListingBuyerPrice

The buyer-facing price for a listing, including VAT, inclusive shipping (UK), and active promotions.

base_price object

The pre-discount listing price with VAT applied, excluding shipping. When a promotion is active, this is the price before the discount is applied.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object nullable

The shipping cost to the buyer's country. Includes VAT where applicable. Null when shipping is free or unavailable — use is_free_shipping to distinguish.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

is_free_shipping boolean

Whether shipping is free to the buyer's country.

original_price object

The display price. For UK buyers, includes base + shipping (DMCC). For others, base price only.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discounted_price object nullable

The sale price. For UK buyers, includes base + shipping. For others, base price only. Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_amount object nullable

The discount amount as money (original_price - discounted_price). Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_percentage integer <int64> nullable

The discount percentage (e.g. 20 for 20% off). Null if no active promotion or if the promotion is a fixed-amount discount.

has_discount boolean

Whether an active promotion applies to this listing.

discount_start_epoch integer <int64> nullable

The start timestamp of the active promotion. Null if no active promotion.

discount_end_epoch integer <int64> nullable

The end timestamp of the active promotion. Null if no active promotion.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string",
      "shipping_profile": {
        "shipping_profile_id": 1,
        "title": "string",
        "user_id": 1,
        "origin_country_iso": "string",
        "is_deleted": true,
        "shipping_profile_destinations": [
          {
            "shipping_profile_destination_id": 1,
            "shipping_profile_id": 1,
            "origin_country_iso": "string",
            "destination_country_iso": "string",
            "destination_region": "eu",
            "primary_cost": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "secondary_cost": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "shipping_carrier_id": 0,
            "mail_class": "string",
            "min_delivery_days": 1,
            "max_delivery_days": 1
          }
        ],
        "shipping_profile_upgrades": [
          {
            "shipping_profile_id": 1,
            "upgrade_id": 1,
            "upgrade_name": "string",
            "type": 0,
            "rank": 0,
            "language": "string",
            "price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "secondary_price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "shipping_carrier_id": 0,
            "mail_class": "string",
            "min_delivery_days": 1,
            "max_delivery_days": 1
          }
        ],
        "origin_postal_code": "string",
        "profile_type": "manual",
        "domestic_handling_fee": 0,
        "international_handling_fee": 0
      },
      "user": {
        "user_id": 1,
        "primary_email": "string",
        "first_name": "string",
        "last_name": "string",
        "image_url_75x75": "string"
      },
      "shop": {
        "shop_id": 1,
        "user_id": 1,
        "shop_name": "string",
        "create_date": 0,
        "created_timestamp": 0,
        "title": "string",
        "announcement": "string",
        "currency_code": "string",
        "is_vacation": true,
        "vacation_message": "string",
        "sale_message": "string",
        "digital_sale_message": "string",
        "update_date": 0,
        "updated_timestamp": 0,
        "listing_active_count": 0,
        "digital_listing_count": 0,
        "login_name": "string",
        "accepts_custom_requests": true,
        "policy_welcome": "string",
        "policy_payment": "string",
        "policy_shipping": "string",
        "policy_refunds": "string",
        "policy_additional": "string",
        "policy_seller_info": "string",
        "policy_update_date": 0,
        "policy_has_private_receipt_info": true,
        "has_unstructured_policies": true,
        "policy_privacy": "string",
        "vacation_autoreply": "string",
        "url": "string",
        "image_url_760x100": "string",
        "num_favorers": 0,
        "languages": [
          "string"
        ],
        "icon_url_fullxfull": "string",
        "is_using_structured_policies": true,
        "has_onboarded_structured_policies": true,
        "include_dispute_form_link": true,
        "is_direct_checkout_onboarded": true,
        "is_etsy_payments_onboarded": true,
        "is_calculated_eligible": true,
        "is_opted_in_to_buyer_promise": true,
        "is_shop_us_based": true,
        "transaction_sold_count": 0,
        "shipping_from_country_iso": "string",
        "shop_location_country_iso": "string",
        "review_count": 0,
        "review_average": 0.0
      },
      "images": [
        {
          "listing_id": 1,
          "listing_image_id": 1,
          "hex_code": "string",
          "red": 0,
          "green": 0,
          "blue": 0,
          "hue": 0,
          "saturation": 0,
          "brightness": 0,
          "is_black_and_white": true,
          "creation_tsz": 0,
          "created_timestamp": 0,
          "rank": 0,
          "url_75x75": "string",
          "url_170x135": "string",
          "url_570xN": "string",
          "url_fullxfull": "string",
          "full_height": 0,
          "full_width": 0,
          "alt_text": "string"
        }
      ],
      "videos": [
        {
          "video_id": 1,
          "height": 0,
          "width": 0,
          "thumbnail_url": "string",
          "video_url": "string",
          "video_state": "active"
        }
      ],
      "inventory": {
        "products": [
          {
            "product_id": 1,
            "sku": "string",
            "is_deleted": true,
            "offerings": [
              {
                "offering_id": 1,
                "quantity": 0,
                "is_enabled": true,
                "is_deleted": true,
                "price": {},
                "readiness_state_id": 1
              }
            ],
            "property_values": [
              {
                "property_id": 1,
                "property_name": "string",
                "scale_id": 1,
                "scale_name": "string",
                "value_ids": [
                  1
                ],
                "values": [
                  "string"
                ]
              }
            ]
          }
        ],
        "price_on_property": [
          0
        ],
        "quantity_on_property": [
          0
        ],
        "sku_on_property": [
          0
        ],
        "readiness_state_on_property": [
          1
        ]
      },
      "production_partners": [
        {
          "production_partner_id": 1,
          "partner_name": "string",
          "location": "string"
        }
      ],
      "skus": [
        "string"
      ],
      "translations": {
        "de": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-GB": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-IN": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-US": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "es": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "fr": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "it": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "ja": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "nl": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "pl": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "pt": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "ru": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "sv": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        }
      },
      "views": 0,
      "personalization": {
        "personalization_questions": [
          {
            "question_id": 1,
            "question_text": "string",
            "instructions": "string",
            "question_type": "string",
            "required": true,
            "max_allowed_characters": 0,
            "max_allowed_files": 0,
            "add_on_price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "options": [
              {
                "option_id": 1,
                "label": "string"
              }
            ]
          }
        ]
      },
      "buyer_price": {
        "base_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "shipping_cost": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "is_free_shipping": true,
        "original_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discounted_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discount_amount": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discount_percentage": 0,
        "has_discount": true,
        "discount_start_epoch": 0,
        "discount_end_epoch": 0
      }
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateListing

PATCHhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}

General Release

This endpoint is ready for production use.

Updates a listing, identified by a listing ID, for a specific shop identified by a shop ID. Note that this is a PATCH method type. When activating, or manually renewing a physical listing, the shipping profile referenced by the shipping_profile_id, and all of its fields, along with its entries and upgrades must be complete and valid. If the shipping profile is not complete and valid, we will throw an exception with an error message that guides the request sender to update whatever data is bad. Digital listings that are not made to order must have a file upload associated with it to be activated. While the listing is a draft, shipping profile and file upload are not required in any case.

AuthorizationAPI keyconnected storeoperation shop_listing_update

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Request bodyapplication/x-www-form-urlencoded

image_ids array of integer <int64>

An array of numeric image IDs of the images in a listing, which can include up to 20 images.

title string

description string

A description string of the product for sale in the listing.

materials array of string nullable

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy. Required for active physical listings. This requirement does not apply to listings of EU-based shops.

shop_section_id integer <int64> nullable

The numeric ID of the shop section for this listing. Default value is null.

item_weight number <float> nullable≥ 0≤ 1.79769313486e+308

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_length number <float> nullable≥ 0≤ 1.79769313486e+308

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable≥ 0≤ 1.79769313486e+308

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable≥ 0≤ 1.79769313486e+308

The numeric height of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"""oz""lb""g""kg"

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"""in""ft""mm""cm""m""yd""inches"

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

taxonomy_id integer <int64> ≥ 1

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

tags array of string nullable

who_made string

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

featured_rank integer <int64> nullable

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

is_personalizable boolean

personalization_is_required boolean

personalization_char_count_max integer <int64>

personalization_instructions string

state string

Enum"active""inactive"

is_supply boolean

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

production_partner_ids array of integer <int64> nullable

An array of unique IDs of production partner ids.

type string nullable

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

Responses

200

A single ShopListing

Response schemaapplication/jsonShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

Example response

200 · application/json

{
  "listing_id": 1,
  "user_id": 1,
  "shop_id": 1,
  "title": "string",
  "description": "string",
  "rich_description": "string",
  "state": "active",
  "creation_timestamp": 946684800,
  "created_timestamp": 946684800,
  "ending_timestamp": 946684800,
  "original_creation_timestamp": 946684800,
  "last_modified_timestamp": 946684800,
  "updated_timestamp": 946684800,
  "state_timestamp": 946684800,
  "quantity": 0,
  "shop_section_id": 1,
  "featured_rank": 0,
  "url": "string",
  "num_favorers": 0,
  "non_taxable": true,
  "is_taxable": true,
  "is_customizable": true,
  "is_personalizable": true,
  "listing_type": "physical",
  "tags": [
    "string"
  ],
  "materials": [
    "string"
  ],
  "shipping_profile_id": 1,
  "return_policy_id": 1,
  "processing_min": 0,
  "processing_max": 0,
  "who_made": "i_did",
  "when_made": "made_to_order",
  "is_supply": true,
  "item_weight": 0.0,
  "item_weight_unit": "oz",
  "item_length": 0.0,
  "item_width": 0.0,
  "item_height": 0.0,
  "item_dimensions_unit": "in",
  "is_private": true,
  "style": [
    "string"
  ],
  "file_data": "string",
  "has_variations": true,
  "should_auto_renew": true,
  "language": "string",
  "price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "converted_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "taxonomy_id": 0,
  "readiness_state_id": 1,
  "suggested_title": "string"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingsByShopReceipt

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}/listings

General Release

This endpoint is ready for production use.

Gets all listings associated with a receipt.

AuthorizationAPI keyconnected storeoperation order_listings

Path parameters

receipt_id integer <int64> required ≥ 1

The numeric ID for the receipt associated to this transaction.

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

legacy boolean

This parameter is needed to enable new parameters and response values related to processing profiles.

Responses

200

A set of ShopListing resources.

Response schemaapplication/jsonShopListings

A set of ShopListing resources.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListing

The ShopListing resources found.

ShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingsByShopReturnPolicy

GEThttps://eto.tools/api/v1/shops/{shop_id}/return-policies/{policy_id}/listings

General Release

This endpoint is ready for production use.

Gets all listings associated with a Return Policy.

AuthorizationAPI keyconnected storeoperation return_policy_listings

Path parameters

return_policy_id integer <int64> required ≥ 1

The numeric ID of the Return Policy.

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

legacy boolean

This parameter is needed to enable new parameters and response values related to processing profiles.

Responses

200

A set of ShopListing resources.

Response schemaapplication/jsonShopListings

A set of ShopListing resources.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListing

The ShopListing resources found.

ShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingsByShopSectionId

GEThttps://eto.tools/api/v1/shops/{shop_id}/section-listings

General Release

This endpoint is ready for production use.

Retrieves all the listings from the section of a specific shop.

AuthorizationAPI keyoperation section_listings

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

shop_section_ids array of integer <int64> required

A list of numeric IDS for all sections in a specific Etsy shop.

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

sort_on string

Default"created"

Enum"created""price""updated""score"

sort_order string

The ascending(up) or descending(down) order to sort listings by. NOTE: sort_order only works when combined with one of the search options (keywords, region, etc.).

Default"desc"

Enum"asc""ascending""desc""descending""up""down"

legacy boolean

This parameter is needed to enable new parameters and response values related to processing profiles.

Responses

200

A list of listings from a shop section.

Response schemaapplication/jsonShopListings

A set of ShopListing resources.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListing

The ShopListing resources found.

ShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Shop ProcessingProfiles

#getShopReadinessStateDefinitions

GEThttps://eto.tools/api/v1/shops/{shop_id}/listing-requirements

General Release

This endpoint is ready for production use.

Retrieves a list of ProcessingProfiles available in the specific Etsy shop identified by its shop ID.

AuthorizationAPI keyconnected storeoperation shop_listing_requirements

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

Responses

200

A list of ProcessingProfiles

Response schemaapplication/jsonShopProcessingProfiles

Represents several ProcessingProfiles.

count integer <int64> ≥ 0

results array of ShopProcessingProfile

ShopProcessingProfile

Represents a processing profile to set a product offering's readiness state and processing time info.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

readiness_state_id integer <int64> ≥ 1

readiness_state string

The readiness state of a product: \"1\" means \"ready_to_ship\", and \"2\" means \"made_to_order\"

Enum"ready_to_ship""made_to_order"

min_processing_days integer <int64> ≥ 0

The minimum number of days for processing a specific product.

max_processing_days integer <int64> ≥ 0

The maximum number of days for processing a specific product.

processing_days_display_label string

Translated display label string for processing days, for example "3 - 5 days".

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "shop_id": 1,
      "readiness_state_id": 1,
      "readiness_state": "ready_to_ship",
      "min_processing_days": 0,
      "max_processing_days": 0,
      "processing_days_display_label": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#createShopReadinessStateDefinition

POSThttps://eto.tools/api/v1/shops/{shop_id}/listing-requirements

General Release

This endpoint is ready for production use.

Creates a new ReadinessStateDefinition. If an existing definition matches the input values, this endpoint will throw a Conflict error, please refer to the Content-Location header to obtain the get endpoint url for the values of the existing definition. Does not affect the product offering-readiness states definition relationship.

AuthorizationAPI keyconnected storeoperation shop_listing_requirements

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Request bodyapplication/x-www-form-urlencoded

readiness_state string required

The readiness state of a product: \"1\" means \"ready_to_ship\", and \"2\" means \"made_to_order\"

Enum"ready_to_ship""made_to_order"

min_processing_time integer <int64> required ≥ 1≤ 10

The minimum number of days or weeks for processing a specific product.

max_processing_time integer <int64> required ≥ 1≤ 10

The maximum number of days or weeks for processing a specific product.

processing_time_unit string

The unit used to represent how long a processing time is. A week is equivalent to how many days the seller works per week as stated in their processing schedule. If none is provided, the unit is set to \"days\".

Default"days"

Enum"days""weeks"

Responses

201

A single ReadinessStateDefinition

Response schemaapplication/jsonShopProcessingProfile

Represents a processing profile to set a product offering's readiness state and processing time info.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

readiness_state_id integer <int64> ≥ 1

readiness_state string

The readiness state of a product: \"1\" means \"ready_to_ship\", and \"2\" means \"made_to_order\"

Enum"ready_to_ship""made_to_order"

min_processing_days integer <int64> ≥ 0

The minimum number of days for processing a specific product.

max_processing_days integer <int64> ≥ 0

The maximum number of days for processing a specific product.

processing_days_display_label string

Translated display label string for processing days, for example "3 - 5 days".

Example response

201 · application/json

{
  "shop_id": 1,
  "readiness_state_id": 1,
  "readiness_state": "ready_to_ship",
  "min_processing_days": 0,
  "max_processing_days": 0,
  "processing_days_display_label": "string"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopReadinessStateDefinition

GEThttps://eto.tools/api/v1/shops/{shop_id}/listing-requirements/{requirement_id}

General Release

This endpoint is ready for production use.

Retrieves a ProcessingProfile referenced by readiness state definition ID.

AuthorizationAPI keyconnected storeoperation listing_requirement_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

readiness_state_definition_id integer <int64> required ≥ 1

Responses

200

A single ProcessingProfile

Response schemaapplication/jsonShopProcessingProfile

Represents a processing profile to set a product offering's readiness state and processing time info.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

readiness_state_id integer <int64> ≥ 1

readiness_state string

The readiness state of a product: \"1\" means \"ready_to_ship\", and \"2\" means \"made_to_order\"

Enum"ready_to_ship""made_to_order"

min_processing_days integer <int64> ≥ 0

The minimum number of days for processing a specific product.

max_processing_days integer <int64> ≥ 0

The maximum number of days for processing a specific product.

processing_days_display_label string

Translated display label string for processing days, for example "3 - 5 days".

Example response

200 · application/json

{
  "shop_id": 1,
  "readiness_state_id": 1,
  "readiness_state": "ready_to_ship",
  "min_processing_days": 0,
  "max_processing_days": 0,
  "processing_days_display_label": "string"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateShopReadinessStateDefinition

PUThttps://eto.tools/api/v1/shops/{shop_id}/listing-requirements/{requirement_id}

General Release

This endpoint is ready for production use.

Updates an existing ReadinessStateDefinition. If an existing definition matches the input values, this endpoint will throw a Conflict error, please refer to the Content-Location header to obtain the get endpoint url for the values of the existing definition. Does not affect the product offering-readiness states definition relationship.

AuthorizationAPI keyconnected storeoperation listing_requirement_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

readiness_state_definition_id integer <int64> required ≥ 1

Request bodyapplication/x-www-form-urlencoded

readiness_state string

The readiness state of a product: \"1\" means \"ready_to_ship\", and \"2\" means \"made_to_order\"

Enum"ready_to_ship""made_to_order"

min_processing_time integer <int64> ≥ 1≤ 10

The minimum number of days or weeks for processing a specific product.

max_processing_time integer <int64> ≥ 1≤ 10

The maximum number of days or weeks for processing a specific product.

processing_time_unit string

Default"days"

Enum"days""weeks"

Responses

200

The updated ReadinessStateDefinition

Response schemaapplication/jsonShopProcessingProfile

Represents a processing profile to set a product offering's readiness state and processing time info.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

readiness_state_id integer <int64> ≥ 1

readiness_state string

The readiness state of a product: \"1\" means \"ready_to_ship\", and \"2\" means \"made_to_order\"

Enum"ready_to_ship""made_to_order"

min_processing_days integer <int64> ≥ 0

The minimum number of days for processing a specific product.

max_processing_days integer <int64> ≥ 0

The maximum number of days for processing a specific product.

processing_days_display_label string

Translated display label string for processing days, for example "3 - 5 days".

Example response

200 · application/json

{
  "shop_id": 1,
  "readiness_state_id": 1,
  "readiness_state": "ready_to_ship",
  "min_processing_days": 0,
  "max_processing_days": 0,
  "processing_days_display_label": "string"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#deleteShopReadinessStateDefinition

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/listing-requirements/{requirement_id}

General Release

This endpoint is ready for production use.

Deletes a ReadinessStateDefinition by given readiness state definition ID. If there any active offerings linked to the definition, this endpoint will throw a Bad Request error. If you want to delete a ReadinessStateDefinition that is linked to active offerings, you must link the offerings to a different readiness state definition.

AuthorizationAPI keyconnected storeoperation listing_requirement_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

readiness_state_definition_id integer <int64> required ≥ 1

Responses

204

The ReadinessStateDefinition was successfully deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Shop ProductionPartner

#getShopProductionPartners

GEThttps://eto.tools/api/v1/shops/{shop_id}/production-partners

General Release

This endpoint is ready for production use.

Retrieves a list of production partners available in the specific Etsy shop identified by its shop ID.

AuthorizationAPI keyconnected storeoperation shop_production_partners

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Responses

200

A list of shop production partners

Response schemaapplication/jsonShopProductionPartners

Represents a list of shop production partners.

count integer <int64> ≥ 0

The number of results.

results array of ShopProductionPartner

The list of requested resources.

ShopProductionPartner

Represents a description of a shop production partner.

production_partner_id integer <int64> ≥ 1

The numeric ID of a production partner.

partner_name string

The name or title of the production partner.

location string

A string representing the production partner location.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "production_partner_id": 1,
      "partner_name": "string",
      "location": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Shop Return Policy

#consolidateShopReturnPolicies

POSThttps://eto.tools/api/v1/shops/{shop_id}/return-policies/consolidate

General Release

This endpoint is ready for production use.

Consolidates Return Policies by moving all listings from a source return policy to a destination return policy, and deleting the source return policy. This is commonly used in the event that a user attempts to update a Return Policy such that its data is a duplicate of some other Return Policy, which is prevented.

AuthorizationAPI keyconnected storeoperation return_policy_consolidate

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Request bodyapplication/x-www-form-urlencoded

source_return_policy_id integer <int64> required ≥ 1

The numeric ID of the Return Policy.

destination_return_policy_id integer <int64> required ≥ 1

The numeric ID of the Return Policy.

Responses

200

The updated target Return Policy

Response schemaapplication/jsonShopReturnPolicy

Represents a listing-level return policy.

return_policy_id integer <int64> ≥ 1

The numeric ID of the Return Policy.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

accepts_returns boolean

return_policy_accepts_returns

accepts_exchanges boolean

return_policy_accepts_exchanges

return_deadline integer <int64> nullable

The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].

Example response

200 · application/json

{
  "return_policy_id": 1,
  "shop_id": 1,
  "accepts_returns": true,
  "accepts_exchanges": true,
  "return_deadline": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopReturnPolicies

GEThttps://eto.tools/api/v1/shops/{shop_id}/return-policies

General Release

This endpoint is ready for production use.

Returns a shop's list of existing Return Policies

AuthorizationAPI keyoperation shop_return_policies

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Responses

200

List of shop's Return Policies

Response schemaapplication/jsonShopReturnPolicies

Represents a shop's listing-level return policies list.

count integer <int64> ≥ 0

results array of ShopReturnPolicy

ShopReturnPolicy

Represents a listing-level return policy.

return_policy_id integer <int64> ≥ 1

The numeric ID of the Return Policy.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

accepts_returns boolean

return_policy_accepts_returns

accepts_exchanges boolean

return_policy_accepts_exchanges

return_deadline integer <int64> nullable

The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "return_policy_id": 1,
      "shop_id": 1,
      "accepts_returns": true,
      "accepts_exchanges": true,
      "return_deadline": 0
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#createShopReturnPolicy

POSThttps://eto.tools/api/v1/shops/{shop_id}/return-policies

General Release

This endpoint is ready for production use.

Creates a new Return Policy. Note: if either accepts_returns or accepts_exchanges is true, then a return_deadline is required.

AuthorizationAPI keyconnected storeoperation shop_return_policies

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Request bodyapplication/x-www-form-urlencoded

accepts_returns boolean required

accepts_exchanges boolean required

return_deadline integer <int64> nullable

The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].

Responses

200

A single Return Policy

Response schemaapplication/jsonShopReturnPolicy

Represents a listing-level return policy.

return_policy_id integer <int64> ≥ 1

The numeric ID of the Return Policy.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

accepts_returns boolean

return_policy_accepts_returns

accepts_exchanges boolean

return_policy_accepts_exchanges

return_deadline integer <int64> nullable

The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].

Example response

200 · application/json

{
  "return_policy_id": 1,
  "shop_id": 1,
  "accepts_returns": true,
  "accepts_exchanges": true,
  "return_deadline": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopReturnPolicy

GEThttps://eto.tools/api/v1/shops/{shop_id}/return-policies/{policy_id}

General Release

This endpoint is ready for production use.

Retrieves an existing Return Policy.

AuthorizationAPI keyoperation return_policy_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

return_policy_id integer <int64> required ≥ 1

The numeric ID of the Return Policy.

Responses

200

A single Return Policy

Response schemaapplication/jsonShopReturnPolicy

Represents a listing-level return policy.

return_policy_id integer <int64> ≥ 1

The numeric ID of the Return Policy.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

accepts_returns boolean

return_policy_accepts_returns

accepts_exchanges boolean

return_policy_accepts_exchanges

return_deadline integer <int64> nullable

The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].

Example response

200 · application/json

{
  "return_policy_id": 1,
  "shop_id": 1,
  "accepts_returns": true,
  "accepts_exchanges": true,
  "return_deadline": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateShopReturnPolicy

PUThttps://eto.tools/api/v1/shops/{shop_id}/return-policies/{policy_id}

General Release

This endpoint is ready for production use.

Updates an existing Return Policy. Note: if either accepts_returns or accepts_exchanges is true, then a return_deadline is required.

AuthorizationAPI keyconnected storeoperation return_policy_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

return_policy_id integer <int64> required ≥ 1

The numeric ID of the Return Policy.

Request bodyapplication/x-www-form-urlencoded

accepts_returns boolean required

accepts_exchanges boolean required

return_deadline integer <int64> nullable

The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].

Responses

200

An updated Return Policy

Response schemaapplication/jsonShopReturnPolicy

Represents a listing-level return policy.

return_policy_id integer <int64> ≥ 1

The numeric ID of the Return Policy.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

accepts_returns boolean

return_policy_accepts_returns

accepts_exchanges boolean

return_policy_accepts_exchanges

return_deadline integer <int64> nullable

The deadline for the Return Policy, measured in days. The value must be one of the following: [7, 14, 21, 30, 45, 60, 90].

Example response

200 · application/json

{
  "return_policy_id": 1,
  "shop_id": 1,
  "accepts_returns": true,
  "accepts_exchanges": true,
  "return_deadline": 0
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#deleteShopReturnPolicy

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/return-policies/{policy_id}

General Release

This endpoint is ready for production use.

Deletes an existing Return Policy. Deletion is only allowed for policies which have no associated listings – move them to another policy before attempting deletion.

AuthorizationAPI keyconnected storeoperation return_policy_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

return_policy_id integer <int64> required ≥ 1

The numeric ID of the Return Policy.

Responses

204

The Return Policy was successfully deleted.

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Shop HolidayPreferences

#getHolidayPreferences

GEThttps://eto.tools/api/v1/shops/{shop_id}/holiday-preferences

General Release

This endpoint is ready for production use.

Retrieves a list of holidays that are available to a shop to set a preference for. Currently only supported in the US and CA

AuthorizationAPI keyconnected storeoperation shop_holidays

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Responses

200

A list of holiday preferences

Response schemaapplication/json

Example response

200 · application/json

[
  {
    "shop_id": 1,
    "holiday_id": 0,
    "country_iso": "string",
    "is_working": true,
    "holiday_name": "string"
  }
]

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateHolidayPreferences

PUThttps://eto.tools/api/v1/shops/{shop_id}/holiday-preferences/{holiday_id}

General Release

This endpoint is ready for production use.

Updates the preference for whether the seller will process orders or not on the holiday. Currently only supported in the US and CA

AuthorizationAPI keyconnected storeoperation shop_holiday_update

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

holiday_id integer <int64> required

The unique id that maps to the holiday a country observes. See the Fulfillment Tutorial docs for more info

Enum123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105

Request bodyapplication/x-www-form-urlencoded

is_working boolean required

A boolean value for whether the shop will process orders on a particular holiday.

Responses

200

The updated holiday preferences

Response schemaapplication/jsonShopHolidayPreference

Represents a shop's holiday preference

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

holiday_id integer <int64>

The unique id that maps to the holiday a country observes. See the Fulfillment Tutorial docs for more info

country_iso string <ISO 3166-1 alpha-2>

The country ISO where the shop is located.

is_working boolean

A boolean value for whether the shop will process orders on a particular holiday.

holiday_name string

The name of the holiday that a country observes.

Example response

200 · application/json

{
  "shop_id": 1,
  "holiday_id": 0,
  "country_iso": "string",
  "is_working": true,
  "holiday_name": "string"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#SellerTaxonomy

#getSellerTaxonomyNodes

GEThttps://eto.tools/api/v1/categories

General Release

This endpoint is ready for production use.

Retrieves the full hierarchy tree of seller taxonomy nodes.

AuthorizationAPI keyoperation categories

Responses

200

List the full hierarchy tree of seller taxonomy nodes.

Response schemaapplication/jsonSellerTaxonomyNodes

A list of taxonomy nodes from the seller taxonomy tree.

count integer <int64> ≥ 0

The number of results.

results array of SellerTaxonomyNode

The list of requested resources.

SellerTaxonomyNode

A taxonomy node in the seller taxonomy tree.

id integer <int64> ≥ 1

The unique numeric ID of an Etsy taxonomy node, which is a metadata category for listings organized into the seller taxonomy hierarchy tree. For example, the "shoes" taxonomy node (ID: 1429, level: 1) is higher in the hierarchy than "girls' shoes" (ID: 1440, level: 2). The taxonomy nodes assigned to a listing support access to specific standardized product scales and properties. For example, listings assigned the taxonomy nodes "shoes" or "girls' shoes" support access to the "EU" shoe size scale with its associated property names and IDs for EU shoe sizes, such as property value_id:"1394", and name:"38".

level integer <int64> ≥ 0

The integer depth of this taxonomy node in the seller taxonomy tree, with roots at level 0.

name string

The name string for this taxonomy node.

parent_id integer <int64> nullable≥ 1

The numeric taxonomy ID of the parent of this node.

Defaultnull

children array of SellerTaxonomyNode

An array of taxonomy nodes for all the direct children of this taxonomy node in the seller taxonomy tree.

recursive: same shape as SellerTaxonomyNode above

full_path_taxonomy_ids array of integer <int64>

An array of taxonomy_ids including this node and all of its direct parents in the seller taxonomy tree up to a root node. They are listed in order from root to leaf.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "id": 1,
      "level": 0,
      "name": "string",
      "parent_id": 1,
      "children": [
        {}
      ],
      "full_path_taxonomy_ids": [
        1
      ]
    }
  ]
}

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

503

The service is unavailable

Response schemaapplication/jsonErrorSchema

error string required

#getPropertiesByTaxonomyId

GEThttps://eto.tools/api/v1/categories/{category_id}/properties

General Release

This endpoint is ready for production use.

Retrieves a list of product properties, with applicable scales and values, supported for a specific seller taxonomy ID.

AuthorizationAPI keyoperation category_properties

Path parameters

taxonomy_id integer <int64> required ≥ 1

Responses

200

A list of product properties, with applicable scales and values.

Response schemaapplication/jsonTaxonomyNodeProperties

A list of product property definitions.

count integer <int64> ≥ 0

The number of results.

results array of TaxonomyNodeProperty

The list of requested resources.

TaxonomyNodeProperty

A product property definition.

property_id integer <int64> ≥ 1

The unique numeric ID of this product property.

name string

The name string for this taxonomy node.

display_name string

The human-readable product property name string.

scales array of TaxonomyPropertyScale

A list of available scales.

TaxonomyPropertyScale

A scale defining the assignable increments for the property values available to specific product properties.

scale_id integer <int64> ≥ 1

The unique numeric ID of a scale.

display_name string

The name string for a scale.

description string

The description string for a scale.

is_required boolean

When true, listings assigned eligible taxonomy IDs require this property.

supports_attributes boolean

When true, you can use this property in listing properties.

supports_variations boolean

When true, you can use this property in listing inventory.

is_multivalued boolean

When true, you can assign multiple property values to this property

max_values_allowed integer <int64> nullable

When true, you can assign multiple property values to this property

possible_values array of TaxonomyPropertyValue

A list of supported property value strings for this property.

TaxonomyPropertyValue

A property value for a specific product property, which may also employ a specific scale.

value_id integer <int64> nullable≥ 1

The numeric ID of this property value.

name string

The name string of this property value.

scale_id integer <int64> nullable≥ 1

The numeric scale ID of the scale to which this property value belongs.

equal_to array of integer <int64>

A list of numeric property value IDs this property value is equal to (if any).

selected_values array of TaxonomyPropertyValue

A list of property value strings automatically and always selected for the given property.

TaxonomyPropertyValue

A property value for a specific product property, which may also employ a specific scale.

value_id integer <int64> nullable≥ 1

The numeric ID of this property value.

name string

The name string of this property value.

scale_id integer <int64> nullable≥ 1

The numeric scale ID of the scale to which this property value belongs.

equal_to array of integer <int64>

A list of numeric property value IDs this property value is equal to (if any).

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "property_id": 1,
      "name": "string",
      "display_name": "string",
      "scales": [
        {
          "scale_id": 1,
          "display_name": "string",
          "description": "string"
        }
      ],
      "is_required": true,
      "supports_attributes": true,
      "supports_variations": true,
      "is_multivalued": true,
      "max_values_allowed": 0,
      "possible_values": [
        {
          "value_id": 1,
          "name": "string",
          "scale_id": 1,
          "equal_to": [
            0
          ]
        }
      ],
      "selected_values": [
        {
          "value_id": 1,
          "name": "string",
          "scale_id": 1,
          "equal_to": [
            0
          ]
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Review

#getReviewsByListing

GEThttps://eto.tools/api/v1/listings/{listing_id}/reviews

General Release

This endpoint is ready for production use.

Open API V3 to retrieve the reviews for a listing given its ID.

AuthorizationAPI keyoperation listing_reviews

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

min_created integer <int64> nullable≥ 946684800

The earliest unix timestamp for when a record was created.

max_created integer <int64> nullable≥ 946684800

The latest unix timestamp for when a record was created.

Responses

200

A set of Transaction Reviews by Listing ID

Response schemaapplication/jsonListingReviews

A set of listing review records left by Users.

count integer <int64> ≥ 0

The number of TransactionReview resources found.

results array of ListingReview

The TransactionReview resources found.

ListingReview

A listing review record left by a User.

shop_id integer <int64> ≥ 1

The shop's numeric ID.

listing_id integer <int64> ≥ 1

The ID of the ShopListing that the TransactionReview belongs to.

rating integer <int64> ≥ 1≤ 5

Rating value on scale from 1 to 5

review string nullable

A message left by the author, explaining the feedback, if provided.

language string

The language of the TransactionReview

image_url_fullxfull string nullable

The url to a photo provided with the feedback, dimensions fullxfull. Note: This field may be absent, depending on the buyer's privacy settings.

create_timestamp integer <int64> ≥ 946684800

The date and time the TransactionReview was created in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The date and time the TransactionReview was created in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time the TransactionReview was updated in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time the TransactionReview was updated in epoch seconds.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "shop_id": 1,
      "listing_id": 1,
      "rating": 1,
      "review": "string",
      "language": "string",
      "image_url_fullxfull": "string",
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "update_timestamp": 946684800,
      "updated_timestamp": 946684800
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getReviewsByShop

GEThttps://eto.tools/api/v1/shops/{shop_id}/reviews

General Release

This endpoint is ready for production use.

Open API V3 to retrieve the reviews from a shop given its ID.

AuthorizationAPI keyoperation shop_reviews

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

min_created integer <int64> nullable≥ 946684800

The earliest unix timestamp for when a record was created.

max_created integer <int64> nullable≥ 946684800

The latest unix timestamp for when a record was created.

Responses

200

A set of Transaction Reviews By Shop ID

Response schemaapplication/jsonTransactionReviews

A set of transaction review records left by Users.

count integer <int64> ≥ 0

The number of TransactionReview resources found.

results array of TransactionReview

The TransactionReview resources found.

TransactionReview

A transaction review record left by a User.

shop_id integer <int64> ≥ 1

The shop's numeric ID.

listing_id integer <int64> ≥ 1

The ID of the ShopListing that the TransactionReview belongs to.

transaction_id integer <int64> ≥ 1

The ID of the ShopReceipt Transaction that the TransactionReview belongs to.

buyer_user_id integer <int64> nullable≥ 1

The numeric ID of the user who was the buyer in this transaction. Note: This field may be absent, depending on the buyer's privacy settings.

rating integer <int64> ≥ 1≤ 5

Rating value on scale from 1 to 5

review string

A message left by the author, explaining the feedback, if provided.

Default""

language string

The language of the TransactionReview

image_url_fullxfull string nullable

The url to a photo provided with the feedback, dimensions fullxfull. Note: This field may be absent, depending on the buyer's privacy settings.

create_timestamp integer <int64> ≥ 946684800

The date and time the TransactionReview was created in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The date and time the TransactionReview was created in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time the TransactionReview was updated in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time the TransactionReview was updated in epoch seconds.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "shop_id": 1,
      "listing_id": 1,
      "transaction_id": 1,
      "buyer_user_id": 1,
      "rating": 1,
      "review": "",
      "language": "string",
      "image_url_fullxfull": "string",
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "update_timestamp": 946684800,
      "updated_timestamp": 946684800
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Shop Receipt

#getShopReceipt

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}

General Release

This endpoint is ready for production use.

Retrieves a receipt, identified by a receipt id, from an Etsy shop. **NOTE** Access to ShopReceipt's first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy

AuthorizationAPI keyconnected storeoperation shop_order_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

receipt_id integer <int64> required ≥ 1

The numeric ID for the receipt associated to this transaction.

Query parameters

legacy boolean

This parameter needed to enable new parameters and response values related to processing profiles.

Responses

200

A single Shop Receipt

Response schemaapplication/jsonShopReceipt

The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

receipt_type integer <int64> ≥ 0

The numeric value for the Etsy channel that serviced the purchase: 0 or 5 for Etsy.com, 1 for a Pattern shop.

seller_user_id integer <int64> ≥ 1

The numeric ID for the user (seller) fulfilling the purchase.

seller_email string <email> nullable

The email address string for the seller of the listing.

buyer_user_id integer <int64> ≥ 1

The numeric ID for the user making the purchase.

buyer_email string nullable

The email address string for the buyer of the listing. It will be null if access hasn't been granted. Access is case-by-case and subject to approval.

name string

The name string for the recipient in the shipping address.

first_line string nullable

The first address line string for the recipient in the shipping address.

second_line string nullable

The optional second address line string for the recipient in the shipping address.

city string nullable

The city string for the recipient in the shipping address.

state string nullable

The state string for the recipient in the shipping address.

zip string nullable

The zip code string (not necessarily a number) for the recipient in the shipping address.

status string

The current order status string. One of: paid, completed, open, payment processing or canceled.

Enum"paid""completed""open""payment processing""canceled""fully refunded""partially refunded"

formatted_address string nullable

The formatted shipping address string for the recipient in the shipping address.

country_iso string nullable

The ISO-3166 alpha-2 country code string for the recipient in the shipping address.

payment_method string

The payment method string identifying purchaser's payment method, which must be one of: 'cc' (credit card), 'paypal', 'check', 'mo' (money order), 'bt' (bank transfer), 'other', 'ideal', 'sofort', 'apple_pay', 'google', 'android_pay', 'google_pay', 'klarna', 'k_pay_in_4' (klarna), 'k_pay_in_3' (klarna), or 'k_financing' (klarna).

payment_email string nullable

The email address string for the email address to which to send payment confirmation

message_from_seller string nullable

An optional message string from the seller.

message_from_buyer string nullable

An optional message string from the buyer.

message_from_payment string nullable

The machine-generated acknowledgement string from the payment system.

is_paid boolean

When true, buyer paid for this purchase.

is_shipped boolean

When true, seller shipped the products.

create_timestamp integer <int64> ≥ 946684800

The receipt's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The receipt's creation time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The time of the last update to the receipt, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the receipt, in epoch seconds.

is_gift boolean

When true, the buyer indicated this purchase is a gift.

gift_message string

A gift message string the buyer requests delivered with the product.

gift_sender string

The name of the person who sent the gift.

grandtotal object

A number equal to the total_price minus the coupon discount plus tax and shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

subtotal object

A number equal to the total_price minus coupon discounts. Does not include tax or shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_price object

A number equal to the sum of the individual listings' (price * quantity). Does not include tax or shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_shipping_cost object

A number equal to the total shipping cost of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_tax_cost object

The total sales tax of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_vat_cost object

A number equal to the total value-added tax (VAT) of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_amt object

The numeric total discounted price for the receipt when using a discount (percent or fixed) coupon. Free shipping coupons are not included in this discount amount.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

gift_wrap_price object

The numeric price of gift wrap for this receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipments array of ShopReceiptShipment

A list of shipment statements for this receipt.

ShopReceiptShipment

The record of one shipment event for a ShopReceipt. A receipt may have many ShopReceiptShipment records.

receipt_shipping_id integer <int64> nullable≥ 1

The unique numeric ID of a Shop Receipt Shipment record.

shipment_notification_timestamp integer <int64> ≥ 946684800

The time at which Etsy notified the buyer of the shipment event, in epoch seconds.

carrier_name string

The name string for the carrier/company responsible for delivering the shipment.

tracking_code string

The tracking code string provided by the carrier/company for the shipment.

transactions array of ShopReceiptTransaction

Array of transactions for the receipt.

ShopReceiptTransaction

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

transaction_id integer <int64> ≥ 1

The unique numeric ID for a transaction.

title string nullable

The title string of the listing purchased in this transaction.

description string nullable

The description string of the listing purchased in this transaction.

seller_user_id integer <int64> ≥ 1

The numeric user ID for the seller in this transaction.

buyer_user_id integer <int64> ≥ 1

The numeric user ID for the buyer in this transaction.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

paid_timestamp integer <int64> nullable≥ 946684800

The transaction's paid date and time, in epoch seconds.

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

quantity integer <int64> ≥ 0

The numeric quantity of products purchased in this transaction.

listing_image_id integer <int64> nullable≥ 1

The numeric ID of the primary listing image for this transaction.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

is_digital boolean

When true, the transaction recorded the purchase of a digital listing.

file_data string

A string describing the files purchased in this transaction.

listing_id integer <int64> nullable≥ 0

The numeric ID for the listing associated to this transaction.

transaction_type string

The type string for the transaction, usually "listing".

product_id integer <int64> nullable≥ 1

The numeric ID for a specific product purchased from a listing.

sku string nullable

The SKU string for the product

price object

A money object representing the price recorded the transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object

A money object representing the shipping cost for this transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

variations array of TransactionVariations

Array of variations and personalizations the buyer chose.

TransactionVariations

A list of variations chosen by the buyer during checkout.

property_id integer <int64>

The variation property ID.

value_id integer <int64> nullable

The ID of the variation value selected.

formatted_name string

Formatted name of the variation.

formatted_value string

Value of the variation entered by the buyer.

question_id integer <int64> nullable

[Personalization only] The ID of the original personalization question.

product_data array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

shipping_profile_id integer <int64> nullable≥ 1

The ID of the shipping profile selected for this listing.

min_processing_days integer <int64> nullable≥ 0

The minimum number of days for processing the listing.

max_processing_days integer <int64> nullable≥ 0

The maximum number of days for processing the listing.

shipping_method string nullable

Name of the selected shipping method.

shipping_upgrade string nullable

The name of the shipping upgrade selected for this listing. Default value is null.

expected_ship_date integer <int64> nullable≥ 946684800

The date & time of the expected ship date, in epoch seconds.

buyer_coupon number <float>

The amount of the buyer coupon that was discounted in the shop's currency.

Default0

shop_coupon number <float>

The amount of the shop coupon that was discounted in the shop's currency.

Default0

refunds array of ShopRefund

Refunds for a given receipt.

ShopRefund

The refund record for a receipt.

amount object

A number equal to the refund total.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

created_timestamp integer <int64> ≥ 946684800

The date & time of the refund, in epoch seconds.

reason string nullable

The reason string given for the refund.

note_from_issuer string nullable

The note string created by the refund issuer.

status string nullable

The status indication string for the refund.

Example response

200 · application/json

{
  "receipt_id": 1,
  "receipt_type": 0,
  "seller_user_id": 1,
  "seller_email": "string",
  "buyer_user_id": 1,
  "buyer_email": "string",
  "name": "string",
  "first_line": "string",
  "second_line": "string",
  "city": "string",
  "state": "string",
  "zip": "string",
  "status": "paid",
  "formatted_address": "string",
  "country_iso": "string",
  "payment_method": "string",
  "payment_email": "string",
  "message_from_seller": "string",
  "message_from_buyer": "string",
  "message_from_payment": "string",
  "is_paid": true,
  "is_shipped": true,
  "create_timestamp": 946684800,
  "created_timestamp": 946684800,
  "update_timestamp": 946684800,
  "updated_timestamp": 946684800,
  "is_gift": true,
  "gift_message": "string",
  "gift_sender": "string",
  "grandtotal": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "subtotal": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_shipping_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_tax_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_vat_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "discount_amt": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "gift_wrap_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "shipments": [
    {
      "receipt_shipping_id": 1,
      "shipment_notification_timestamp": 946684800,
      "carrier_name": "string",
      "tracking_code": "string"
    }
  ],
  "transactions": [
    {
      "transaction_id": 1,
      "title": "string",
      "description": "string",
      "seller_user_id": 1,
      "buyer_user_id": 1,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "paid_timestamp": 946684800,
      "shipped_timestamp": 946684800,
      "quantity": 0,
      "listing_image_id": 1,
      "receipt_id": 1,
      "is_digital": true,
      "file_data": "string",
      "listing_id": 0,
      "transaction_type": "string",
      "product_id": 1,
      "sku": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "variations": [
        {
          "property_id": 0,
          "value_id": 0,
          "formatted_name": "string",
          "formatted_value": "string",
          "question_id": 0
        }
      ],
      "product_data": [
        {
          "property_id": 1,
          "property_name": "string",
          "scale_id": 1,
          "scale_name": "string",
          "value_ids": [
            1
          ],
          "values": [
            "string"
          ]
        }
      ],
      "shipping_profile_id": 1,
      "min_processing_days": 0,
      "max_processing_days": 0,
      "shipping_method": "string",
      "shipping_upgrade": "string",
      "expected_ship_date": 946684800,
      "buyer_coupon": 0,
      "shop_coupon": 0
    }
  ],
  "refunds": [
    {
      "amount": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "created_timestamp": 946684800,
      "reason": "string",
      "note_from_issuer": "string",
      "status": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateShopReceipt

PUThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}

General Release

This endpoint is ready for production use.

Updates the status of a receipt, identified by a receipt id, from an Etsy shop. **NOTE** Access to ShopReceipt's first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy

AuthorizationAPI keyconnected storeoperation shop_order_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

receipt_id integer <int64> required ≥ 1

The numeric ID for the receipt associated to this transaction.

Query parameters

legacy boolean

This parameter needed to enable new parameters and response values related to processing profiles.

Request bodyapplication/x-www-form-urlencoded

was_shipped boolean nullable

When true, returns receipts where the seller shipped the product(s) in this receipt. When false, returns receipts where shipment has not been set.

was_paid boolean nullable

When true, returns receipts where the seller has received payment for the receipt. When false, returns receipts where payment has not been received.

Responses

200

Update A Shop Receipt

Response schemaapplication/jsonShopReceipt

The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

receipt_type integer <int64> ≥ 0

The numeric value for the Etsy channel that serviced the purchase: 0 or 5 for Etsy.com, 1 for a Pattern shop.

seller_user_id integer <int64> ≥ 1

The numeric ID for the user (seller) fulfilling the purchase.

seller_email string <email> nullable

The email address string for the seller of the listing.

buyer_user_id integer <int64> ≥ 1

The numeric ID for the user making the purchase.

buyer_email string nullable

The email address string for the buyer of the listing. It will be null if access hasn't been granted. Access is case-by-case and subject to approval.

name string

The name string for the recipient in the shipping address.

first_line string nullable

The first address line string for the recipient in the shipping address.

second_line string nullable

The optional second address line string for the recipient in the shipping address.

city string nullable

The city string for the recipient in the shipping address.

state string nullable

The state string for the recipient in the shipping address.

zip string nullable

The zip code string (not necessarily a number) for the recipient in the shipping address.

status string

The current order status string. One of: paid, completed, open, payment processing or canceled.

Enum"paid""completed""open""payment processing""canceled""fully refunded""partially refunded"

formatted_address string nullable

The formatted shipping address string for the recipient in the shipping address.

country_iso string nullable

The ISO-3166 alpha-2 country code string for the recipient in the shipping address.

payment_method string

payment_email string nullable

The email address string for the email address to which to send payment confirmation

message_from_seller string nullable

An optional message string from the seller.

message_from_buyer string nullable

An optional message string from the buyer.

message_from_payment string nullable

The machine-generated acknowledgement string from the payment system.

is_paid boolean

When true, buyer paid for this purchase.

is_shipped boolean

When true, seller shipped the products.

create_timestamp integer <int64> ≥ 946684800

The receipt's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The receipt's creation time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The time of the last update to the receipt, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the receipt, in epoch seconds.

is_gift boolean

When true, the buyer indicated this purchase is a gift.

gift_message string

A gift message string the buyer requests delivered with the product.

gift_sender string

The name of the person who sent the gift.

grandtotal object

A number equal to the total_price minus the coupon discount plus tax and shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

subtotal object

A number equal to the total_price minus coupon discounts. Does not include tax or shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_price object

A number equal to the sum of the individual listings' (price * quantity). Does not include tax or shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_shipping_cost object

A number equal to the total shipping cost of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_tax_cost object

The total sales tax of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_vat_cost object

A number equal to the total value-added tax (VAT) of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_amt object

The numeric total discounted price for the receipt when using a discount (percent or fixed) coupon. Free shipping coupons are not included in this discount amount.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

gift_wrap_price object

The numeric price of gift wrap for this receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipments array of ShopReceiptShipment

A list of shipment statements for this receipt.

ShopReceiptShipment

The record of one shipment event for a ShopReceipt. A receipt may have many ShopReceiptShipment records.

receipt_shipping_id integer <int64> nullable≥ 1

The unique numeric ID of a Shop Receipt Shipment record.

shipment_notification_timestamp integer <int64> ≥ 946684800

The time at which Etsy notified the buyer of the shipment event, in epoch seconds.

carrier_name string

The name string for the carrier/company responsible for delivering the shipment.

tracking_code string

The tracking code string provided by the carrier/company for the shipment.

transactions array of ShopReceiptTransaction

Array of transactions for the receipt.

ShopReceiptTransaction

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

transaction_id integer <int64> ≥ 1

The unique numeric ID for a transaction.

title string nullable

The title string of the listing purchased in this transaction.

description string nullable

The description string of the listing purchased in this transaction.

seller_user_id integer <int64> ≥ 1

The numeric user ID for the seller in this transaction.

buyer_user_id integer <int64> ≥ 1

The numeric user ID for the buyer in this transaction.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

paid_timestamp integer <int64> nullable≥ 946684800

The transaction's paid date and time, in epoch seconds.

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

quantity integer <int64> ≥ 0

The numeric quantity of products purchased in this transaction.

listing_image_id integer <int64> nullable≥ 1

The numeric ID of the primary listing image for this transaction.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

is_digital boolean

When true, the transaction recorded the purchase of a digital listing.

file_data string

A string describing the files purchased in this transaction.

listing_id integer <int64> nullable≥ 0

The numeric ID for the listing associated to this transaction.

transaction_type string

The type string for the transaction, usually "listing".

product_id integer <int64> nullable≥ 1

The numeric ID for a specific product purchased from a listing.

sku string nullable

The SKU string for the product

price object

A money object representing the price recorded the transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object

A money object representing the shipping cost for this transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

variations array of TransactionVariations

Array of variations and personalizations the buyer chose.

TransactionVariations

A list of variations chosen by the buyer during checkout.

property_id integer <int64>

The variation property ID.

value_id integer <int64> nullable

The ID of the variation value selected.

formatted_name string

Formatted name of the variation.

formatted_value string

Value of the variation entered by the buyer.

question_id integer <int64> nullable

[Personalization only] The ID of the original personalization question.

product_data array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

shipping_profile_id integer <int64> nullable≥ 1

The ID of the shipping profile selected for this listing.

min_processing_days integer <int64> nullable≥ 0

The minimum number of days for processing the listing.

max_processing_days integer <int64> nullable≥ 0

The maximum number of days for processing the listing.

shipping_method string nullable

Name of the selected shipping method.

shipping_upgrade string nullable

The name of the shipping upgrade selected for this listing. Default value is null.

expected_ship_date integer <int64> nullable≥ 946684800

The date & time of the expected ship date, in epoch seconds.

buyer_coupon number <float>

The amount of the buyer coupon that was discounted in the shop's currency.

Default0

shop_coupon number <float>

The amount of the shop coupon that was discounted in the shop's currency.

Default0

refunds array of ShopRefund

Refunds for a given receipt.

ShopRefund

The refund record for a receipt.

amount object

A number equal to the refund total.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

created_timestamp integer <int64> ≥ 946684800

The date & time of the refund, in epoch seconds.

reason string nullable

The reason string given for the refund.

note_from_issuer string nullable

The note string created by the refund issuer.

status string nullable

The status indication string for the refund.

Example response

200 · application/json

{
  "receipt_id": 1,
  "receipt_type": 0,
  "seller_user_id": 1,
  "seller_email": "string",
  "buyer_user_id": 1,
  "buyer_email": "string",
  "name": "string",
  "first_line": "string",
  "second_line": "string",
  "city": "string",
  "state": "string",
  "zip": "string",
  "status": "paid",
  "formatted_address": "string",
  "country_iso": "string",
  "payment_method": "string",
  "payment_email": "string",
  "message_from_seller": "string",
  "message_from_buyer": "string",
  "message_from_payment": "string",
  "is_paid": true,
  "is_shipped": true,
  "create_timestamp": 946684800,
  "created_timestamp": 946684800,
  "update_timestamp": 946684800,
  "updated_timestamp": 946684800,
  "is_gift": true,
  "gift_message": "string",
  "gift_sender": "string",
  "grandtotal": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "subtotal": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_shipping_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_tax_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_vat_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "discount_amt": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "gift_wrap_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "shipments": [
    {
      "receipt_shipping_id": 1,
      "shipment_notification_timestamp": 946684800,
      "carrier_name": "string",
      "tracking_code": "string"
    }
  ],
  "transactions": [
    {
      "transaction_id": 1,
      "title": "string",
      "description": "string",
      "seller_user_id": 1,
      "buyer_user_id": 1,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "paid_timestamp": 946684800,
      "shipped_timestamp": 946684800,
      "quantity": 0,
      "listing_image_id": 1,
      "receipt_id": 1,
      "is_digital": true,
      "file_data": "string",
      "listing_id": 0,
      "transaction_type": "string",
      "product_id": 1,
      "sku": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "variations": [
        {
          "property_id": 0,
          "value_id": 0,
          "formatted_name": "string",
          "formatted_value": "string",
          "question_id": 0
        }
      ],
      "product_data": [
        {
          "property_id": 1,
          "property_name": "string",
          "scale_id": 1,
          "scale_name": "string",
          "value_ids": [
            1
          ],
          "values": [
            "string"
          ]
        }
      ],
      "shipping_profile_id": 1,
      "min_processing_days": 0,
      "max_processing_days": 0,
      "shipping_method": "string",
      "shipping_upgrade": "string",
      "expected_ship_date": 946684800,
      "buyer_coupon": 0,
      "shop_coupon": 0
    }
  ],
  "refunds": [
    {
      "amount": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "created_timestamp": 946684800,
      "reason": "string",
      "note_from_issuer": "string",
      "status": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopReceipts

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders

General Release

This endpoint is ready for production use.

Requests the Shop Receipts from a specific Shop, unfiltered or filtered by receipt id range or offset, date, paid, and/or shipped purchases. **NOTE** Access to ShopReceipt's first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy

AuthorizationAPI keyconnected storeoperation shop_orders

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

min_created integer <int64> ≥ 946684800

The earliest unix timestamp for when a record was created.

Defaultnull

max_created integer <int64> ≥ 946684800

The latest unix timestamp for when a record was created.

Defaultnull

min_last_modified integer <int64> ≥ 946684800

The earliest unix timestamp for when a record last changed.

Defaultnull

max_last_modified integer <int64> ≥ 946684800

The latest unix timestamp for when a record last changed.

Defaultnull

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

sort_on string

The value to sort a search result of listings on.

Default"created"

Enum"created""updated""receipt_id"

sort_order string

The ascending(up) or descending(down) order to sort receipts by.

Default"desc"

Enum"asc""ascending""desc""descending""up""down"

was_paid boolean nullable

When true, returns receipts where the seller has received payment for the receipt. When false, returns receipts where payment has not been received.

was_shipped boolean nullable

When true, returns receipts where the seller shipped the product(s) in this receipt. When false, returns receipts where shipment has not been set.

was_delivered boolean nullable

When true, returns receipts that have been marked as delivered. When false, returns receipts where shipment has not been marked as delivered.

was_canceled boolean nullable

When true, the endpoint will only return the canceled receipts. When false, the endpoint will only return non-canceled receipts.

legacy boolean

This parameter needed to enable new parameters and response values related to processing profiles.

Responses

200

A list of Shop Receipts

Response schemaapplication/jsonShopReceipts

The receipts for a specific Shop.

count integer <int64>

The number of Shop Receipts found.

results array of ShopReceipt

List of Shop Receipt resources found, with all Shop Receipt fields for each resource.

ShopReceipt

The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

receipt_type integer <int64> ≥ 0

The numeric value for the Etsy channel that serviced the purchase: 0 or 5 for Etsy.com, 1 for a Pattern shop.

seller_user_id integer <int64> ≥ 1

The numeric ID for the user (seller) fulfilling the purchase.

seller_email string <email> nullable

The email address string for the seller of the listing.

buyer_user_id integer <int64> ≥ 1

The numeric ID for the user making the purchase.

buyer_email string nullable

The email address string for the buyer of the listing. It will be null if access hasn't been granted. Access is case-by-case and subject to approval.

name string

The name string for the recipient in the shipping address.

first_line string nullable

The first address line string for the recipient in the shipping address.

second_line string nullable

The optional second address line string for the recipient in the shipping address.

city string nullable

The city string for the recipient in the shipping address.

state string nullable

The state string for the recipient in the shipping address.

zip string nullable

The zip code string (not necessarily a number) for the recipient in the shipping address.

status string

The current order status string. One of: paid, completed, open, payment processing or canceled.

Enum"paid""completed""open""payment processing""canceled""fully refunded""partially refunded"

formatted_address string nullable

The formatted shipping address string for the recipient in the shipping address.

country_iso string nullable

The ISO-3166 alpha-2 country code string for the recipient in the shipping address.

payment_method string

payment_email string nullable

The email address string for the email address to which to send payment confirmation

message_from_seller string nullable

An optional message string from the seller.

message_from_buyer string nullable

An optional message string from the buyer.

message_from_payment string nullable

The machine-generated acknowledgement string from the payment system.

is_paid boolean

When true, buyer paid for this purchase.

is_shipped boolean

When true, seller shipped the products.

create_timestamp integer <int64> ≥ 946684800

The receipt's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The receipt's creation time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The time of the last update to the receipt, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the receipt, in epoch seconds.

is_gift boolean

When true, the buyer indicated this purchase is a gift.

gift_message string

A gift message string the buyer requests delivered with the product.

gift_sender string

The name of the person who sent the gift.

grandtotal object

A number equal to the total_price minus the coupon discount plus tax and shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

subtotal object

A number equal to the total_price minus coupon discounts. Does not include tax or shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_price object

A number equal to the sum of the individual listings' (price * quantity). Does not include tax or shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_shipping_cost object

A number equal to the total shipping cost of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_tax_cost object

The total sales tax of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_vat_cost object

A number equal to the total value-added tax (VAT) of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_amt object

The numeric total discounted price for the receipt when using a discount (percent or fixed) coupon. Free shipping coupons are not included in this discount amount.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

gift_wrap_price object

The numeric price of gift wrap for this receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipments array of ShopReceiptShipment

A list of shipment statements for this receipt.

ShopReceiptShipment

The record of one shipment event for a ShopReceipt. A receipt may have many ShopReceiptShipment records.

receipt_shipping_id integer <int64> nullable≥ 1

The unique numeric ID of a Shop Receipt Shipment record.

shipment_notification_timestamp integer <int64> ≥ 946684800

The time at which Etsy notified the buyer of the shipment event, in epoch seconds.

carrier_name string

The name string for the carrier/company responsible for delivering the shipment.

tracking_code string

The tracking code string provided by the carrier/company for the shipment.

transactions array of ShopReceiptTransaction

Array of transactions for the receipt.

ShopReceiptTransaction

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

transaction_id integer <int64> ≥ 1

The unique numeric ID for a transaction.

title string nullable

The title string of the listing purchased in this transaction.

description string nullable

The description string of the listing purchased in this transaction.

seller_user_id integer <int64> ≥ 1

The numeric user ID for the seller in this transaction.

buyer_user_id integer <int64> ≥ 1

The numeric user ID for the buyer in this transaction.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

paid_timestamp integer <int64> nullable≥ 946684800

The transaction's paid date and time, in epoch seconds.

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

quantity integer <int64> ≥ 0

The numeric quantity of products purchased in this transaction.

listing_image_id integer <int64> nullable≥ 1

The numeric ID of the primary listing image for this transaction.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

is_digital boolean

When true, the transaction recorded the purchase of a digital listing.

file_data string

A string describing the files purchased in this transaction.

listing_id integer <int64> nullable≥ 0

The numeric ID for the listing associated to this transaction.

transaction_type string

The type string for the transaction, usually "listing".

product_id integer <int64> nullable≥ 1

The numeric ID for a specific product purchased from a listing.

sku string nullable

The SKU string for the product

price object

A money object representing the price recorded the transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object

A money object representing the shipping cost for this transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

variations array of TransactionVariations

Array of variations and personalizations the buyer chose.

TransactionVariations

A list of variations chosen by the buyer during checkout.

property_id integer <int64>

The variation property ID.

value_id integer <int64> nullable

The ID of the variation value selected.

formatted_name string

Formatted name of the variation.

formatted_value string

Value of the variation entered by the buyer.

question_id integer <int64> nullable

[Personalization only] The ID of the original personalization question.

product_data array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

shipping_profile_id integer <int64> nullable≥ 1

The ID of the shipping profile selected for this listing.

min_processing_days integer <int64> nullable≥ 0

The minimum number of days for processing the listing.

max_processing_days integer <int64> nullable≥ 0

The maximum number of days for processing the listing.

shipping_method string nullable

Name of the selected shipping method.

shipping_upgrade string nullable

The name of the shipping upgrade selected for this listing. Default value is null.

expected_ship_date integer <int64> nullable≥ 946684800

The date & time of the expected ship date, in epoch seconds.

buyer_coupon number <float>

The amount of the buyer coupon that was discounted in the shop's currency.

Default0

shop_coupon number <float>

The amount of the shop coupon that was discounted in the shop's currency.

Default0

refunds array of ShopRefund

Refunds for a given receipt.

ShopRefund

The refund record for a receipt.

amount object

A number equal to the refund total.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

created_timestamp integer <int64> ≥ 946684800

The date & time of the refund, in epoch seconds.

reason string nullable

The reason string given for the refund.

note_from_issuer string nullable

The note string created by the refund issuer.

status string nullable

The status indication string for the refund.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "receipt_id": 1,
      "receipt_type": 0,
      "seller_user_id": 1,
      "seller_email": "string",
      "buyer_user_id": 1,
      "buyer_email": "string",
      "name": "string",
      "first_line": "string",
      "second_line": "string",
      "city": "string",
      "state": "string",
      "zip": "string",
      "status": "paid",
      "formatted_address": "string",
      "country_iso": "string",
      "payment_method": "string",
      "payment_email": "string",
      "message_from_seller": "string",
      "message_from_buyer": "string",
      "message_from_payment": "string",
      "is_paid": true,
      "is_shipped": true,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "update_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "is_gift": true,
      "gift_message": "string",
      "gift_sender": "string",
      "grandtotal": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "subtotal": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "total_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "total_shipping_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "total_tax_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "total_vat_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "discount_amt": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "gift_wrap_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipments": [
        {
          "receipt_shipping_id": 1,
          "shipment_notification_timestamp": 946684800,
          "carrier_name": "string",
          "tracking_code": "string"
        }
      ],
      "transactions": [
        {
          "transaction_id": 1,
          "title": "string",
          "description": "string",
          "seller_user_id": 1,
          "buyer_user_id": 1,
          "create_timestamp": 946684800,
          "created_timestamp": 946684800,
          "paid_timestamp": 946684800,
          "shipped_timestamp": 946684800,
          "quantity": 0,
          "listing_image_id": 1,
          "receipt_id": 1,
          "is_digital": true,
          "file_data": "string",
          "listing_id": 0,
          "transaction_type": "string",
          "product_id": 1,
          "sku": "string",
          "price": {
            "amount": 0,
            "divisor": 0,
            "currency_code": "string"
          },
          "shipping_cost": {
            "amount": 0,
            "divisor": 0,
            "currency_code": "string"
          },
          "variations": [
            {
              "property_id": 0,
              "value_id": 0,
              "formatted_name": "string",
              "formatted_value": "string",
              "question_id": 0
            }
          ],
          "product_data": [
            {
              "property_id": 1,
              "property_name": "string",
              "scale_id": 1,
              "scale_name": "string",
              "value_ids": [
                1
              ],
              "values": [
                "string"
              ]
            }
          ],
          "shipping_profile_id": 1,
          "min_processing_days": 0,
          "max_processing_days": 0,
          "shipping_method": "string",
          "shipping_upgrade": "string",
          "expected_ship_date": 946684800,
          "buyer_coupon": 0,
          "shop_coupon": 0
        }
      ],
      "refunds": [
        {
          "amount": {
            "amount": 0,
            "divisor": 0,
            "currency_code": "string"
          },
          "created_timestamp": 946684800,
          "reason": "string",
          "note_from_issuer": "string",
          "status": "string"
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#createReceiptShipment

POSThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}/tracking

General Release

This endpoint is ready for production use.

Submits tracking information for a Shop Receipt, which creates a Shop Receipt Shipment entry for the given receipt_id. Each time you successfully submit tracking info, Etsy sends a notification email to the buyer User. When send_bcc is true, Etsy sends shipping notifications to the seller as well. When tracking_code and carrier_name aren't sent, the receipt is marked as shipped only. If the carrier is not supported, you may use other as the carrier name so you can provide the tracking code. **NOTES** When shipping within the United States AND the order is over $10 _or_ when shipping to India, tracking code and carrier name ARE required. Access to ShopReceipt's first_line, second_line, city, state, zip, country_iso and formatted_address is contingent in some regions to a preferred partnership status with Etsy

AuthorizationAPI keyconnected storeoperation shop_order_tracking

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

receipt_id integer <int64> required ≥ 1

The receipt to submit tracking for.

Query parameters

legacy boolean

This parameter needed to enable new parameters and response values related to processing profiles.

Request bodyapplication/json

tracking_code string

The tracking code for this receipt.

carrier_name string

The carrier name for this receipt.

send_bcc boolean

If true, the shipping notification will be sent to the seller as well

note_to_buyer string

Message to include in notification to the buyer.

mail_class string nullable

The service level of postal or carrier service selected for the shipment (e.g., First-Class, Priority, Ground, Express).

weight number <float> nullable

The total weight of the package.

weight_units string nullable

Unit of measurement used for package weight (oz, grams, etc.).

length number <float> nullable

Longest side of the package.

width number <float> nullable

Second longest side of the package.

height number <float> nullable

Third longest side of the package.

dimension_units string nullable

Unit of measurement used for package dimensions (in, cm...).

shipping_label_cost number <float> nullable

The purchase price the seller paid for the shipping label.

shipping_label_currency string nullable

The currency in which the shipping label was purchased.

revenue_eligibility string nullable

A flag indicating if the shipment is tied to a revenue share agreement between Etsy and the vendor.

ship_from_country string nullable

Where the package ships from.

ship_to_country string nullable

Package destination.

incoterm string nullable

The specific incoterm (e.g., DDU, DDP) designated for the shipment.

customs_data array of object nullable

Contains custom data like country of origin, declared value and HS code.

item

country_of_origin string required nullable

The country in which the goods originate from.

Defaultnull

declared_value number <float> required nullable

The commercial value of the goods.

Defaultnull

HS_code string required nullable

The standardized global system (Harmonized System) for classifying traded products.

Defaultnull

duty_amount number <float> nullable

The estimated or actual amount of import duties and taxes assessed by customs for the shipment.

duty_currency string nullable

The currency in which the duty was paid.

ship_date string nullable

The date package was shipped.

Responses

200

A single ShopReceipt

Response schemaapplication/jsonShopReceipt

The record of a purchase from a shop. Shop receipts display monetary values using the shop's currency.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

receipt_type integer <int64> ≥ 0

The numeric value for the Etsy channel that serviced the purchase: 0 or 5 for Etsy.com, 1 for a Pattern shop.

seller_user_id integer <int64> ≥ 1

The numeric ID for the user (seller) fulfilling the purchase.

seller_email string <email> nullable

The email address string for the seller of the listing.

buyer_user_id integer <int64> ≥ 1

The numeric ID for the user making the purchase.

buyer_email string nullable

The email address string for the buyer of the listing. It will be null if access hasn't been granted. Access is case-by-case and subject to approval.

name string

The name string for the recipient in the shipping address.

first_line string nullable

The first address line string for the recipient in the shipping address.

second_line string nullable

The optional second address line string for the recipient in the shipping address.

city string nullable

The city string for the recipient in the shipping address.

state string nullable

The state string for the recipient in the shipping address.

zip string nullable

The zip code string (not necessarily a number) for the recipient in the shipping address.

status string

The current order status string. One of: paid, completed, open, payment processing or canceled.

Enum"paid""completed""open""payment processing""canceled""fully refunded""partially refunded"

formatted_address string nullable

The formatted shipping address string for the recipient in the shipping address.

country_iso string nullable

The ISO-3166 alpha-2 country code string for the recipient in the shipping address.

payment_method string

payment_email string nullable

The email address string for the email address to which to send payment confirmation

message_from_seller string nullable

An optional message string from the seller.

message_from_buyer string nullable

An optional message string from the buyer.

message_from_payment string nullable

The machine-generated acknowledgement string from the payment system.

is_paid boolean

When true, buyer paid for this purchase.

is_shipped boolean

When true, seller shipped the products.

create_timestamp integer <int64> ≥ 946684800

The receipt's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The receipt's creation time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The time of the last update to the receipt, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the receipt, in epoch seconds.

is_gift boolean

When true, the buyer indicated this purchase is a gift.

gift_message string

A gift message string the buyer requests delivered with the product.

gift_sender string

The name of the person who sent the gift.

grandtotal object

A number equal to the total_price minus the coupon discount plus tax and shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

subtotal object

A number equal to the total_price minus coupon discounts. Does not include tax or shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_price object

A number equal to the sum of the individual listings' (price * quantity). Does not include tax or shipping costs.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_shipping_cost object

A number equal to the total shipping cost of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_tax_cost object

The total sales tax of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

total_vat_cost object

A number equal to the total value-added tax (VAT) of the receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_amt object

The numeric total discounted price for the receipt when using a discount (percent or fixed) coupon. Free shipping coupons are not included in this discount amount.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

gift_wrap_price object

The numeric price of gift wrap for this receipt.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipments array of ShopReceiptShipment

A list of shipment statements for this receipt.

ShopReceiptShipment

The record of one shipment event for a ShopReceipt. A receipt may have many ShopReceiptShipment records.

receipt_shipping_id integer <int64> nullable≥ 1

The unique numeric ID of a Shop Receipt Shipment record.

shipment_notification_timestamp integer <int64> ≥ 946684800

The time at which Etsy notified the buyer of the shipment event, in epoch seconds.

carrier_name string

The name string for the carrier/company responsible for delivering the shipment.

tracking_code string

The tracking code string provided by the carrier/company for the shipment.

transactions array of ShopReceiptTransaction

Array of transactions for the receipt.

ShopReceiptTransaction

A transaction object associated with a shop receipt. Etsy generates one transaction per listing purchased as recorded on the order receipt.

transaction_id integer <int64> ≥ 1

The unique numeric ID for a transaction.

title string nullable

The title string of the listing purchased in this transaction.

description string nullable

The description string of the listing purchased in this transaction.

seller_user_id integer <int64> ≥ 1

The numeric user ID for the seller in this transaction.

buyer_user_id integer <int64> ≥ 1

The numeric user ID for the buyer in this transaction.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

paid_timestamp integer <int64> nullable≥ 946684800

The transaction's paid date and time, in epoch seconds.

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

quantity integer <int64> ≥ 0

The numeric quantity of products purchased in this transaction.

listing_image_id integer <int64> nullable≥ 1

The numeric ID of the primary listing image for this transaction.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

is_digital boolean

When true, the transaction recorded the purchase of a digital listing.

file_data string

A string describing the files purchased in this transaction.

listing_id integer <int64> nullable≥ 0

The numeric ID for the listing associated to this transaction.

transaction_type string

The type string for the transaction, usually "listing".

product_id integer <int64> nullable≥ 1

The numeric ID for a specific product purchased from a listing.

sku string nullable

The SKU string for the product

price object

A money object representing the price recorded the transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object

A money object representing the shipping cost for this transaction.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

variations array of TransactionVariations

Array of variations and personalizations the buyer chose.

TransactionVariations

A list of variations chosen by the buyer during checkout.

property_id integer <int64>

The variation property ID.

value_id integer <int64> nullable

The ID of the variation value selected.

formatted_name string

Formatted name of the variation.

formatted_value string

Value of the variation entered by the buyer.

question_id integer <int64> nullable

[Personalization only] The ID of the original personalization question.

product_data array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

shipping_profile_id integer <int64> nullable≥ 1

The ID of the shipping profile selected for this listing.

min_processing_days integer <int64> nullable≥ 0

The minimum number of days for processing the listing.

max_processing_days integer <int64> nullable≥ 0

The maximum number of days for processing the listing.

shipping_method string nullable

Name of the selected shipping method.

shipping_upgrade string nullable

The name of the shipping upgrade selected for this listing. Default value is null.

expected_ship_date integer <int64> nullable≥ 946684800

The date & time of the expected ship date, in epoch seconds.

buyer_coupon number <float>

The amount of the buyer coupon that was discounted in the shop's currency.

Default0

shop_coupon number <float>

The amount of the shop coupon that was discounted in the shop's currency.

Default0

refunds array of ShopRefund

Refunds for a given receipt.

ShopRefund

The refund record for a receipt.

amount object

A number equal to the refund total.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

created_timestamp integer <int64> ≥ 946684800

The date & time of the refund, in epoch seconds.

reason string nullable

The reason string given for the refund.

note_from_issuer string nullable

The note string created by the refund issuer.

status string nullable

The status indication string for the refund.

Example response

200 · application/json

{
  "receipt_id": 1,
  "receipt_type": 0,
  "seller_user_id": 1,
  "seller_email": "string",
  "buyer_user_id": 1,
  "buyer_email": "string",
  "name": "string",
  "first_line": "string",
  "second_line": "string",
  "city": "string",
  "state": "string",
  "zip": "string",
  "status": "paid",
  "formatted_address": "string",
  "country_iso": "string",
  "payment_method": "string",
  "payment_email": "string",
  "message_from_seller": "string",
  "message_from_buyer": "string",
  "message_from_payment": "string",
  "is_paid": true,
  "is_shipped": true,
  "create_timestamp": 946684800,
  "created_timestamp": 946684800,
  "update_timestamp": 946684800,
  "updated_timestamp": 946684800,
  "is_gift": true,
  "gift_message": "string",
  "gift_sender": "string",
  "grandtotal": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "subtotal": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_shipping_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_tax_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "total_vat_cost": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "discount_amt": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "gift_wrap_price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "shipments": [
    {
      "receipt_shipping_id": 1,
      "shipment_notification_timestamp": 946684800,
      "carrier_name": "string",
      "tracking_code": "string"
    }
  ],
  "transactions": [
    {
      "transaction_id": 1,
      "title": "string",
      "description": "string",
      "seller_user_id": 1,
      "buyer_user_id": 1,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "paid_timestamp": 946684800,
      "shipped_timestamp": 946684800,
      "quantity": 0,
      "listing_image_id": 1,
      "receipt_id": 1,
      "is_digital": true,
      "file_data": "string",
      "listing_id": 0,
      "transaction_type": "string",
      "product_id": 1,
      "sku": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "shipping_cost": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "variations": [
        {
          "property_id": 0,
          "value_id": 0,
          "formatted_name": "string",
          "formatted_value": "string",
          "question_id": 0
        }
      ],
      "product_data": [
        {
          "property_id": 1,
          "property_name": "string",
          "scale_id": 1,
          "scale_name": "string",
          "value_ids": [
            1
          ],
          "values": [
            "string"
          ]
        }
      ],
      "shipping_profile_id": 1,
      "min_processing_days": 0,
      "max_processing_days": 0,
      "shipping_method": "string",
      "shipping_upgrade": "string",
      "expected_ship_date": 946684800,
      "buyer_coupon": 0,
      "shop_coupon": 0
    }
  ],
  "refunds": [
    {
      "amount": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "created_timestamp": 946684800,
      "reason": "string",
      "note_from_issuer": "string",
      "status": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Payment

#getPaymentAccountLedgerEntryPayments

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/payments

General Release

This endpoint is ready for production use.

Get a Payment from a PaymentAccount Ledger Entry ID, if applicable

AuthorizationAPI keyconnected storeoperation shop_finance_payments

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

ledger_entry_ids array of integer <int64> required

Responses

200

A list of Payments

Response schemaapplication/jsonPayments

Represents several payments made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

count integer <int64> ≥ 0

The number of payments in the response.

results array of Payment

A list of payments.

Payment

Represents a payment made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

payment_id integer <int64> ≥ 1

A unique numeric ID for a payment to a specific Etsy shop.

buyer_user_id integer <int64> ≥ 1

The numeric ID for the user who paid the purchase.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

amount_gross object

An integer equal to gross amount of the order, in pennies, including shipping and taxes.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

amount_fees object

An integer equal to the original card processing fee of the order in pennies.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

amount_net object

An integer equal to the payment value, in pennies, less fees (amount_gross - amount_fees).

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

posted_gross object nullable

The total gross value of the payment posted once the purchase ships. This is equal to the amount_gross UNLESS the seller issues a refund prior to shipping. We consider "shipping" to be the event which "posts" to the ledger. Therefore, if the seller refunds first, we reduce the amount_gross first and post then that amount. The seller never sees the refunded amount in their ledger. This is equal to the "Credit" amount in the ledger entry.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

posted_fees object nullable

The total value of the fees posted once the purchase ships. Etsy refunds a proportional amount of the fees when a seller refunds a buyer. When the seller issues a refund prior to shipping, the posted amount is less than the original.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

posted_net object nullable

The total value of the payment at the time of posting, less fees. (posted_gross - posted_fees)

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

adjusted_gross object nullable

The gross payment amount after the seller refunds a payment, partially or fully.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

adjusted_fees object nullable

The new fee amount after a seller refunds a payment, partially or fully.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

adjusted_net object nullable

The total value of the payment after refunds, less fees (adjusted_gross - adjusted_fees).

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

currency string

The ISO (alphabetic) code string for the payment's currency.

shop_currency string nullable

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

buyer_currency string nullable

The currency string of the buyer.

shipping_user_id integer <int64> nullable≥ 1

The numeric ID of the user to which the seller ships the order.

shipping_address_id integer <int64> ≥ 1

The numeric id identifying the shipping address.

billing_address_id integer <int64> ≥ 0≤ 9223372036854775807

The numeric ID identifying the billing address of the buyer.

status string

A string indicating the current status of the payment, most commonly "settled" or "authed".

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

payment_adjustments array of PaymentAdjustment

List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.

PaymentAdjustment

Represents a refund, which applies to a prior Etsy payment. All monetary amounts are in USD pennies unless otherwise specified.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_id integer <int64> ≥ 1

A unique numeric ID for a payment to a specific Etsy shop.

status string

The status string of the payment adjustment.

is_success boolean

When true, the payment adjustment was or is likely to complete successfully.

user_id integer <int64> ≥ 1

The numeric ID for the user (seller) fulfilling the purchase.

reason_code string

A human-readable string describing the reason for the refund.

total_adjustment_amount integer <int64> nullable≥ 0

The total numeric amount of the refund in the payment currency.

shop_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the shop currency.

buyer_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the buyer currency.

total_fee_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of card processing fees associated with a payment adjustment.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

payment_adjustment_items array of PaymentAdjustmentItem

List of payment adjustment line items.

PaymentAdjustmentItem

A payment adjustment line item for a payment adjustment.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_adjustment_item_id integer <int64> ≥ 1

Unique ID for the adjustment line item.

adjustment_type string nullable

String indicating the type of adjustment for this line item.

amount integer <int64>

Integer value for the amount of the adjustment in original currency.

Default0

shop_amount integer <int64>

Integer value for the amount of the adjustment in currency for the shop.

Default0

transaction_id integer <int64> nullable≥ 1

The unique numeric ID for a transaction.

bill_payment_id integer <int64> nullable≥ 1

Unique ID for the bill payment adjustment.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The update date and time the payment adjustment in epoch seconds.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "payment_id": 1,
      "buyer_user_id": 1,
      "shop_id": 1,
      "receipt_id": 1,
      "amount_gross": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "amount_fees": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "amount_net": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "posted_gross": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "posted_fees": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "posted_net": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "adjusted_gross": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "adjusted_fees": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "adjusted_net": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "currency": "string",
      "shop_currency": "string",
      "buyer_currency": "string",
      "shipping_user_id": 1,
      "shipping_address_id": 1,
      "billing_address_id": 0,
      "status": "string",
      "shipped_timestamp": 946684800,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "update_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "payment_adjustments": [
        {
          "payment_adjustment_id": 1,
          "payment_id": 1,
          "status": "string",
          "is_success": true,
          "user_id": 1,
          "reason_code": "string",
          "total_adjustment_amount": 0,
          "shop_total_adjustment_amount": 0,
          "buyer_total_adjustment_amount": 0,
          "total_fee_adjustment_amount": 0,
          "create_timestamp": 946684800,
          "created_timestamp": 946684800,
          "update_timestamp": 946684800,
          "updated_timestamp": 946684800,
          "payment_adjustment_items": [
            {
              "payment_adjustment_id": 1,
              "payment_adjustment_item_id": 1,
              "adjustment_type": "string",
              "amount": 0,
              "shop_amount": 0,
              "transaction_id": 1,
              "bill_payment_id": 1,
              "created_timestamp": 946684800,
              "updated_timestamp": 946684800
            }
          ]
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopPaymentByReceiptId

GEThttps://eto.tools/api/v1/shops/{shop_id}/orders/{order_id}/payments

General Release

This endpoint is ready for production use.

Retrieves a payment from a specific receipt, identified by receipt_id, from a specific shop, identified by shop_id

AuthorizationAPI keyconnected storeoperation order_payments

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

receipt_id integer <int64> required ≥ 1

The numeric ID for the receipt associated to this transaction.

Responses

200

A single payment

Response schemaapplication/jsonPayments

Represents several payments made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

count integer <int64> ≥ 0

The number of payments in the response.

results array of Payment

A list of payments.

Payment

Represents a payment made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

payment_id integer <int64> ≥ 1

A unique numeric ID for a payment to a specific Etsy shop.

buyer_user_id integer <int64> ≥ 1

The numeric ID for the user who paid the purchase.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

amount_gross object

An integer equal to gross amount of the order, in pennies, including shipping and taxes.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

amount_fees object

An integer equal to the original card processing fee of the order in pennies.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

amount_net object

An integer equal to the payment value, in pennies, less fees (amount_gross - amount_fees).

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

posted_gross object nullable

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

posted_fees object nullable

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

posted_net object nullable

The total value of the payment at the time of posting, less fees. (posted_gross - posted_fees)

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

adjusted_gross object nullable

The gross payment amount after the seller refunds a payment, partially or fully.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

adjusted_fees object nullable

The new fee amount after a seller refunds a payment, partially or fully.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

adjusted_net object nullable

The total value of the payment after refunds, less fees (adjusted_gross - adjusted_fees).

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

currency string

The ISO (alphabetic) code string for the payment's currency.

shop_currency string nullable

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

buyer_currency string nullable

The currency string of the buyer.

shipping_user_id integer <int64> nullable≥ 1

The numeric ID of the user to which the seller ships the order.

shipping_address_id integer <int64> ≥ 1

The numeric id identifying the shipping address.

billing_address_id integer <int64> ≥ 0≤ 9223372036854775807

The numeric ID identifying the billing address of the buyer.

status string

A string indicating the current status of the payment, most commonly "settled" or "authed".

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

payment_adjustments array of PaymentAdjustment

List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.

PaymentAdjustment

Represents a refund, which applies to a prior Etsy payment. All monetary amounts are in USD pennies unless otherwise specified.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_id integer <int64> ≥ 1

A unique numeric ID for a payment to a specific Etsy shop.

status string

The status string of the payment adjustment.

is_success boolean

When true, the payment adjustment was or is likely to complete successfully.

user_id integer <int64> ≥ 1

The numeric ID for the user (seller) fulfilling the purchase.

reason_code string

A human-readable string describing the reason for the refund.

total_adjustment_amount integer <int64> nullable≥ 0

The total numeric amount of the refund in the payment currency.

shop_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the shop currency.

buyer_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the buyer currency.

total_fee_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of card processing fees associated with a payment adjustment.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

payment_adjustment_items array of PaymentAdjustmentItem

List of payment adjustment line items.

PaymentAdjustmentItem

A payment adjustment line item for a payment adjustment.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_adjustment_item_id integer <int64> ≥ 1

Unique ID for the adjustment line item.

adjustment_type string nullable

String indicating the type of adjustment for this line item.

amount integer <int64>

Integer value for the amount of the adjustment in original currency.

Default0

shop_amount integer <int64>

Integer value for the amount of the adjustment in currency for the shop.

Default0

transaction_id integer <int64> nullable≥ 1

The unique numeric ID for a transaction.

bill_payment_id integer <int64> nullable≥ 1

Unique ID for the bill payment adjustment.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The update date and time the payment adjustment in epoch seconds.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "payment_id": 1,
      "buyer_user_id": 1,
      "shop_id": 1,
      "receipt_id": 1,
      "amount_gross": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "amount_fees": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "amount_net": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "posted_gross": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "posted_fees": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "posted_net": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "adjusted_gross": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "adjusted_fees": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "adjusted_net": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "currency": "string",
      "shop_currency": "string",
      "buyer_currency": "string",
      "shipping_user_id": 1,
      "shipping_address_id": 1,
      "billing_address_id": 0,
      "status": "string",
      "shipped_timestamp": 946684800,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "update_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "payment_adjustments": [
        {
          "payment_adjustment_id": 1,
          "payment_id": 1,
          "status": "string",
          "is_success": true,
          "user_id": 1,
          "reason_code": "string",
          "total_adjustment_amount": 0,
          "shop_total_adjustment_amount": 0,
          "buyer_total_adjustment_amount": 0,
          "total_fee_adjustment_amount": 0,
          "create_timestamp": 946684800,
          "created_timestamp": 946684800,
          "update_timestamp": 946684800,
          "updated_timestamp": 946684800,
          "payment_adjustment_items": [
            {
              "payment_adjustment_id": 1,
              "payment_adjustment_item_id": 1,
              "adjustment_type": "string",
              "amount": 0,
              "shop_amount": 0,
              "transaction_id": 1,
              "bill_payment_id": 1,
              "created_timestamp": 946684800,
              "updated_timestamp": 946684800
            }
          ]
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getPayments

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/all-payments

General Release

This endpoint is ready for production use.

Retrieves a list of payments from a shop identified by shop_id. You can also filter results using a list of payment IDs.

AuthorizationAPI keyconnected storeoperation shop_all_payments

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

payment_ids array of integer <int64> required

A comma-separated array of Payment IDs numbers.

Responses

200

A list of payments from a specific shop.

Response schemaapplication/jsonPayments

Represents several payments made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

count integer <int64> ≥ 0

The number of payments in the response.

results array of Payment

A list of payments.

Payment

Represents a payment made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.

payment_id integer <int64> ≥ 1

A unique numeric ID for a payment to a specific Etsy shop.

buyer_user_id integer <int64> ≥ 1

The numeric ID for the user who paid the purchase.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

receipt_id integer <int64> ≥ 1

The numeric ID for the receipt associated to this transaction.

amount_gross object

An integer equal to gross amount of the order, in pennies, including shipping and taxes.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

amount_fees object

An integer equal to the original card processing fee of the order in pennies.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

amount_net object

An integer equal to the payment value, in pennies, less fees (amount_gross - amount_fees).

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

posted_gross object nullable

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

posted_fees object nullable

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

posted_net object nullable

The total value of the payment at the time of posting, less fees. (posted_gross - posted_fees)

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

adjusted_gross object nullable

The gross payment amount after the seller refunds a payment, partially or fully.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

adjusted_fees object nullable

The new fee amount after a seller refunds a payment, partially or fully.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

adjusted_net object nullable

The total value of the payment after refunds, less fees (adjusted_gross - adjusted_fees).

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

currency string

The ISO (alphabetic) code string for the payment's currency.

shop_currency string nullable

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

buyer_currency string nullable

The currency string of the buyer.

shipping_user_id integer <int64> nullable≥ 1

The numeric ID of the user to which the seller ships the order.

shipping_address_id integer <int64> ≥ 1

The numeric id identifying the shipping address.

billing_address_id integer <int64> ≥ 0≤ 9223372036854775807

The numeric ID identifying the billing address of the buyer.

status string

A string indicating the current status of the payment, most commonly "settled" or "authed".

shipped_timestamp integer <int64> nullable≥ 946684800

The transaction's shipping date and time, in epoch seconds.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

payment_adjustments array of PaymentAdjustment

List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.

PaymentAdjustment

Represents a refund, which applies to a prior Etsy payment. All monetary amounts are in USD pennies unless otherwise specified.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_id integer <int64> ≥ 1

A unique numeric ID for a payment to a specific Etsy shop.

status string

The status string of the payment adjustment.

is_success boolean

When true, the payment adjustment was or is likely to complete successfully.

user_id integer <int64> ≥ 1

The numeric ID for the user (seller) fulfilling the purchase.

reason_code string

A human-readable string describing the reason for the refund.

total_adjustment_amount integer <int64> nullable≥ 0

The total numeric amount of the refund in the payment currency.

shop_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the shop currency.

buyer_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the buyer currency.

total_fee_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of card processing fees associated with a payment adjustment.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

payment_adjustment_items array of PaymentAdjustmentItem

List of payment adjustment line items.

PaymentAdjustmentItem

A payment adjustment line item for a payment adjustment.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_adjustment_item_id integer <int64> ≥ 1

Unique ID for the adjustment line item.

adjustment_type string nullable

String indicating the type of adjustment for this line item.

amount integer <int64>

Integer value for the amount of the adjustment in original currency.

Default0

shop_amount integer <int64>

Integer value for the amount of the adjustment in currency for the shop.

Default0

transaction_id integer <int64> nullable≥ 1

The unique numeric ID for a transaction.

bill_payment_id integer <int64> nullable≥ 1

Unique ID for the bill payment adjustment.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The update date and time the payment adjustment in epoch seconds.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "payment_id": 1,
      "buyer_user_id": 1,
      "shop_id": 1,
      "receipt_id": 1,
      "amount_gross": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "amount_fees": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "amount_net": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "posted_gross": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "posted_fees": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "posted_net": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "adjusted_gross": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "adjusted_fees": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "adjusted_net": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "currency": "string",
      "shop_currency": "string",
      "buyer_currency": "string",
      "shipping_user_id": 1,
      "shipping_address_id": 1,
      "billing_address_id": 0,
      "status": "string",
      "shipped_timestamp": 946684800,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "update_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "payment_adjustments": [
        {
          "payment_adjustment_id": 1,
          "payment_id": 1,
          "status": "string",
          "is_success": true,
          "user_id": 1,
          "reason_code": "string",
          "total_adjustment_amount": 0,
          "shop_total_adjustment_amount": 0,
          "buyer_total_adjustment_amount": 0,
          "total_fee_adjustment_amount": 0,
          "create_timestamp": 946684800,
          "created_timestamp": 946684800,
          "update_timestamp": 946684800,
          "updated_timestamp": 946684800,
          "payment_adjustment_items": [
            {
              "payment_adjustment_id": 1,
              "payment_adjustment_item_id": 1,
              "adjustment_type": "string",
              "amount": 0,
              "shop_amount": 0,
              "transaction_id": 1,
              "bill_payment_id": 1,
              "created_timestamp": 946684800,
              "updated_timestamp": 946684800
            }
          ]
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#Ledger Entry

#getShopPaymentAccountLedgerEntry

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/transactions/{entry_id}

General Release

This endpoint is ready for production use.

Get a single Shop Payment Account Ledger's Entry

AuthorizationAPI keyconnected storeoperation single_ledger_entry

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

ledger_entry_id integer <int64> required ≥ 1

The unique ID of the shop owner ledger entry.

Responses

200

A single of PaymentAccountLedgerEntry

Response schemaapplication/jsonPaymentAccountLedgerEntry

Represents an entry in a shop's ledger.

entry_id integer <int64> ≥ 1

The ledger entry's numeric ID.

ledger_id integer <int64> ≥ 1

The ledger's numeric ID.

sequence_number integer <int64>

The sequence allows ledger entries to be sorted chronologically. The higher the sequence, the more recent the entry.

amount integer <int64>

The amount of money credited to the ledger.

currency string

The currency of the entry on the ledger.

description string

Details what kind of ledger entry this is: a payment, refund, reversal of a failed refund, disbursement, returned disbursement, recoupment, miscellaneous credit, miscellaneous debit, or bill payment.

balance integer <int64>

The amount of money in the shop's ledger the moment after this entry was applied.

create_date integer <int64> ≥ 0

The date and time the ledger entry was created in Epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time the ledger entry was created in Epoch seconds.

ledger_type string

The original reference type for the ledger entry.

reference_type string

The object type the ledger entry refers to.

reference_id string nullable

The object id the ledger entry refers to.

parent_entry_id integer <int64> ≥ 0

The parent ledger entry ID used to match related entries (e.g., vat_seller_services to originating seller fees).

payment_adjustments array of PaymentAdjustment

List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.

PaymentAdjustment

Represents a refund, which applies to a prior Etsy payment. All monetary amounts are in USD pennies unless otherwise specified.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_id integer <int64> ≥ 1

A unique numeric ID for a payment to a specific Etsy shop.

status string

The status string of the payment adjustment.

is_success boolean

When true, the payment adjustment was or is likely to complete successfully.

user_id integer <int64> ≥ 1

The numeric ID for the user (seller) fulfilling the purchase.

reason_code string

A human-readable string describing the reason for the refund.

total_adjustment_amount integer <int64> nullable≥ 0

The total numeric amount of the refund in the payment currency.

shop_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the shop currency.

buyer_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the buyer currency.

total_fee_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of card processing fees associated with a payment adjustment.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

payment_adjustment_items array of PaymentAdjustmentItem

List of payment adjustment line items.

PaymentAdjustmentItem

A payment adjustment line item for a payment adjustment.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_adjustment_item_id integer <int64> ≥ 1

Unique ID for the adjustment line item.

adjustment_type string nullable

String indicating the type of adjustment for this line item.

amount integer <int64>

Integer value for the amount of the adjustment in original currency.

Default0

shop_amount integer <int64>

Integer value for the amount of the adjustment in currency for the shop.

Default0

transaction_id integer <int64> nullable≥ 1

The unique numeric ID for a transaction.

bill_payment_id integer <int64> nullable≥ 1

Unique ID for the bill payment adjustment.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The update date and time the payment adjustment in epoch seconds.

Example response

200 · application/json

{
  "entry_id": 1,
  "ledger_id": 1,
  "sequence_number": 0,
  "amount": 0,
  "currency": "string",
  "description": "string",
  "balance": 0,
  "create_date": 0,
  "created_timestamp": 0,
  "ledger_type": "string",
  "reference_type": "string",
  "reference_id": "string",
  "parent_entry_id": 0,
  "payment_adjustments": [
    {
      "payment_adjustment_id": 1,
      "payment_id": 1,
      "status": "string",
      "is_success": true,
      "user_id": 1,
      "reason_code": "string",
      "total_adjustment_amount": 0,
      "shop_total_adjustment_amount": 0,
      "buyer_total_adjustment_amount": 0,
      "total_fee_adjustment_amount": 0,
      "create_timestamp": 946684800,
      "created_timestamp": 946684800,
      "update_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "payment_adjustment_items": [
        {
          "payment_adjustment_id": 1,
          "payment_adjustment_item_id": 1,
          "adjustment_type": "string",
          "amount": 0,
          "shop_amount": 0,
          "transaction_id": 1,
          "bill_payment_id": 1,
          "created_timestamp": 946684800,
          "updated_timestamp": 946684800
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getShopPaymentAccountLedgerEntries

GEThttps://eto.tools/api/v1/shops/{shop_id}/finance/transactions

General Release

This endpoint is ready for production use.

Get a Shop Payment Account Ledger's Entries

AuthorizationAPI keyconnected storeoperation shop_finance_transactions

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Query parameters

min_created integer <int64> required ≥ 946684800

The earliest unix timestamp for when a record was created.

max_created integer <int64> required ≥ 946684800

The latest unix timestamp for when a record was created.

limit integer <int64> ≥ 1≤ 100

The maximum number of results to return.

Default25

offset integer <int64> ≥ 0

The number of records to skip before selecting the first result.

Default0

Responses

200

A list of PaymentAccountLedgerEntries

Response schemaapplication/jsonPaymentAccountLedgerEntries

A set of PaymentAccountLedgerEntry resources

count integer <int64> ≥ 0

The number of PaymentAccountLedgerEntry resources found.

results array of PaymentAccountLedgerEntry

The PaymentAccountLedgerEntry resources found.

PaymentAccountLedgerEntry

Represents an entry in a shop's ledger.

entry_id integer <int64> ≥ 1

The ledger entry's numeric ID.

ledger_id integer <int64> ≥ 1

The ledger's numeric ID.

sequence_number integer <int64>

The sequence allows ledger entries to be sorted chronologically. The higher the sequence, the more recent the entry.

amount integer <int64>

The amount of money credited to the ledger.

currency string

The currency of the entry on the ledger.

description string

Details what kind of ledger entry this is: a payment, refund, reversal of a failed refund, disbursement, returned disbursement, recoupment, miscellaneous credit, miscellaneous debit, or bill payment.

balance integer <int64>

The amount of money in the shop's ledger the moment after this entry was applied.

create_date integer <int64> ≥ 0

The date and time the ledger entry was created in Epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time the ledger entry was created in Epoch seconds.

ledger_type string

The original reference type for the ledger entry.

reference_type string

The object type the ledger entry refers to.

reference_id string nullable

The object id the ledger entry refers to.

parent_entry_id integer <int64> ≥ 0

The parent ledger entry ID used to match related entries (e.g., vat_seller_services to originating seller fees).

payment_adjustments array of PaymentAdjustment

List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.

PaymentAdjustment

Represents a refund, which applies to a prior Etsy payment. All monetary amounts are in USD pennies unless otherwise specified.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_id integer <int64> ≥ 1

A unique numeric ID for a payment to a specific Etsy shop.

status string

The status string of the payment adjustment.

is_success boolean

When true, the payment adjustment was or is likely to complete successfully.

user_id integer <int64> ≥ 1

The numeric ID for the user (seller) fulfilling the purchase.

reason_code string

A human-readable string describing the reason for the refund.

total_adjustment_amount integer <int64> nullable≥ 0

The total numeric amount of the refund in the payment currency.

shop_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the shop currency.

buyer_total_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of the refund in the buyer currency.

total_fee_adjustment_amount integer <int64> nullable≥ 0

The numeric amount of card processing fees associated with a payment adjustment.

create_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

update_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The date and time of the last change to the payment adjustment in epoch seconds.

payment_adjustment_items array of PaymentAdjustmentItem

List of payment adjustment line items.

PaymentAdjustmentItem

A payment adjustment line item for a payment adjustment.

payment_adjustment_id integer <int64> ≥ 1

The numeric ID for a payment adjustment.

payment_adjustment_item_id integer <int64> ≥ 1

Unique ID for the adjustment line item.

adjustment_type string nullable

String indicating the type of adjustment for this line item.

amount integer <int64>

Integer value for the amount of the adjustment in original currency.

Default0

shop_amount integer <int64>

Integer value for the amount of the adjustment in currency for the shop.

Default0

transaction_id integer <int64> nullable≥ 1

The unique numeric ID for a transaction.

bill_payment_id integer <int64> nullable≥ 1

Unique ID for the bill payment adjustment.

created_timestamp integer <int64> ≥ 946684800

The transaction's creation date and time, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The update date and time the payment adjustment in epoch seconds.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "entry_id": 1,
      "ledger_id": 1,
      "sequence_number": 0,
      "amount": 0,
      "currency": "string",
      "description": "string",
      "balance": 0,
      "create_date": 0,
      "created_timestamp": 0,
      "ledger_type": "string",
      "reference_type": "string",
      "reference_id": "string",
      "parent_entry_id": 0,
      "payment_adjustments": [
        {
          "payment_adjustment_id": 1,
          "payment_id": 1,
          "status": "string",
          "is_success": true,
          "user_id": 1,
          "reason_code": "string",
          "total_adjustment_amount": 0,
          "shop_total_adjustment_amount": 0,
          "buyer_total_adjustment_amount": 0,
          "total_fee_adjustment_amount": 0,
          "create_timestamp": 946684800,
          "created_timestamp": 946684800,
          "update_timestamp": 946684800,
          "updated_timestamp": 946684800,
          "payment_adjustment_items": [
            {
              "payment_adjustment_id": 1,
              "payment_adjustment_item_id": 1,
              "adjustment_type": "string",
              "amount": 0,
              "shop_amount": 0,
              "transaction_id": 1,
              "bill_payment_id": 1,
              "created_timestamp": 946684800,
              "updated_timestamp": 946684800
            }
          ]
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing Video

#deleteListingVideo

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/videos/{video_id}

General Release

This endpoint is ready for production use.

Open API V3 endpoint to delete a listing video. A copy of the video remains on our servers, and so a deleted video may be re-associated with the listing without re-uploading the original video; see uploadListingVideo.

AuthorizationAPI keyconnected storeoperation listing_video_delete

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

video_id integer <int64> required ≥ 1

The unique ID of a video associated with a listing.

Responses

204

The ListingVideo resource was correctly deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingVideo

GEThttps://eto.tools/api/v1/listings/{listing_id}/videos/{video_id}

General Release

This endpoint is ready for production use.

Retrieves a single video associated with the given listing. Requesting a video from a listing returns an empty result.

AuthorizationAPI keyoperation listing_video_detail

Path parameters

video_id integer <int64> required ≥ 1

The unique ID of a video associated with a listing.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Responses

200

The metadata for a video associated with a listing.

Response schemaapplication/jsonListingVideo

Reference urls and metadata for a video associated with a specific listing.

video_id integer <int64> ≥ 1

The unique ID of a video associated with a listing.

height integer <int64>

The video height dimension in pixels.

width integer <int64>

The video width dimension in pixels.

thumbnail_url string

The url of the video thumbnail.

video_url string

The url of the video file.

video_state string

The current state of a given video. Value is one of active, inactive, deleted or flagged.

Default"active"

Enum"active""inactive""deleted""flagged"

Example response

200 · application/json

{
  "video_id": 1,
  "height": 0,
  "width": 0,
  "thumbnail_url": "string",
  "video_url": "string",
  "video_state": "active"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingVideos

GEThttps://eto.tools/api/v1/listings/{listing_id}/videos

General Release

This endpoint is ready for production use.

Retrieves all listing video resources for a listing with a specific listing ID.

AuthorizationAPI keyoperation listing_videos

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Responses

200

A list of videos for a listing

Response schemaapplication/jsonListingVideos

Represents a list of listing video resources, each of which contains the reference URLs for the videos.

count integer <int64> ≥ 0

The number of results.

results array of ListingVideo

The list of requested resources.

ListingVideo

Reference urls and metadata for a video associated with a specific listing.

video_id integer <int64> ≥ 1

The unique ID of a video associated with a listing.

height integer <int64>

The video height dimension in pixels.

width integer <int64>

The video width dimension in pixels.

thumbnail_url string

The url of the video thumbnail.

video_url string

The url of the video file.

video_state string

The current state of a given video. Value is one of active, inactive, deleted or flagged.

Default"active"

Enum"active""inactive""deleted""flagged"

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "video_id": 1,
      "height": 0,
      "width": 0,
      "thumbnail_url": "string",
      "video_url": "string",
      "video_state": "active"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#uploadListingVideo

POSThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/videos

General Release

This endpoint is ready for production use.

Uploads a new video for a listing, or associates an existing video with a specific listing. You must either provide the video_id of an existing video, or the name and binary file data for a video to upload. If providing a video_id, the video must already be associated with the same shop as the listing, but it does not need to be currently associated with the listing.

AuthorizationAPI keyconnected storeoperation listing_video_upload

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Request bodymultipart/form-data

video_id integer <int64> ≥ 1

The unique ID of a video associated with a listing.

video string <binary> nullable

A video file to upload.

name string

The file name string for the video to upload.

Responses

201

The metadata for a file associated with a digital listing.

Response schemaapplication/jsonListingVideo

Reference urls and metadata for a video associated with a specific listing.

video_id integer <int64> ≥ 1

The unique ID of a video associated with a listing.

height integer <int64>

The video height dimension in pixels.

width integer <int64>

The video width dimension in pixels.

thumbnail_url string

The url of the video thumbnail.

video_url string

The url of the video file.

video_state string

The current state of a given video. Value is one of active, inactive, deleted or flagged.

Default"active"

Enum"active""inactive""deleted""flagged"

Example response

201 · application/json

{
  "video_id": 1,
  "height": 0,
  "width": 0,
  "thumbnail_url": "string",
  "video_url": "string",
  "video_state": "active"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing VariationImage

#getListingVariationImages

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/variation-images

General Release

This endpoint is ready for production use.

Gets all variation images on a listing.

AuthorizationAPI keyoperation listing_variation_images

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Responses

200

A list of ListingVariationImages

Response schemaapplication/jsonListingVariationImages

Represents several ListingVariationImages.

count integer <int64> ≥ 0

results array of ListingVariationImage

ListingVariationImage

A representation of the associations of variations and images on a listing.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

value_id integer <int64> ≥ 1

The numeric ID of the Value.

value string nullable

The string value of the property.

image_id integer <int64> ≥ 1

The numeric ID of the Image.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "property_id": 1,
      "value_id": 1,
      "value": "string",
      "image_id": 1
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateVariationImages

POSThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/variation-images

General Release

This endpoint is ready for production use.

Creates variation images on a listing. variation_images is an array with inputs for the property_id, value_id, and image_id fields. image_ids are associated with a ListingImage on the listing associated with the provided listing_id. property_id and value_id pairs are associated with a ListingProduct on the listing associated with the provided listing_id. variation_images should not contain any duplicates. variation_images does not contain more than one property_id as variation images can only be associated on one property. The update overwrites all existing variation images on a listing, so if your request is successful, the variation images on the listing will be exactly those you specify.

AuthorizationAPI keyconnected storeoperation listing_variation_images

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Request bodyapplication/json

variation_images array of object required

A list of variation image data.

item

property_id integer <int64> required ≥ 1

value_id integer <int64> required ≥ 1

image_id integer <int64> required ≥ 1

Responses

200

A single ListingVariationImage

Response schemaapplication/jsonListingVariationImages

Represents several ListingVariationImages.

count integer <int64> ≥ 0

results array of ListingVariationImage

ListingVariationImage

A representation of the associations of variations and images on a listing.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

value_id integer <int64> ≥ 1

The numeric ID of the Value.

value string nullable

The string value of the property.

image_id integer <int64> ≥ 1

The numeric ID of the Image.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "property_id": 1,
      "value_id": 1,
      "value": "string",
      "image_id": 1
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing Translation

#getListingTranslation

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/translations/{language}

General Release

This endpoint is ready for production use.

Get a Translation for a Listing in the given language

AuthorizationAPI keyoperation listing_translation

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

language string required

The IETF language tag for the language of this translation. Ex: de, en, es, fr, it, ja, nl, pl, pt.

Responses

200

A single ListingTranslation

Response schemaapplication/jsonListingTranslation

Represents the translation data for a Listing.

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

Example response

200 · application/json

{
  "listing_id": 1,
  "language": "string",
  "title": "string",
  "description": "string",
  "tags": [
    "string"
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#createListingTranslation

POSThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/translations/{language}

General Release

This endpoint is ready for production use.

Creates a ListingTranslation by listing_id and language

AuthorizationAPI keyconnected storeoperation listing_translation

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

language string required

The IETF language tag for the language of this translation. Ex: de, en, es, fr, it, ja, nl, pl, pt.

Request bodyapplication/x-www-form-urlencoded

title string required

The title of the Listing of this Translation.

description string required

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

Responses

200

A single ListingTranslation

Response schemaapplication/jsonListingTranslation

Represents the translation data for a Listing.

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

Example response

200 · application/json

{
  "listing_id": 1,
  "language": "string",
  "title": "string",
  "description": "string",
  "tags": [
    "string"
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateListingTranslation

PUThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/translations/{language}

General Release

This endpoint is ready for production use.

Updates a ListingTranslation by listing_id and language

AuthorizationAPI keyconnected storeoperation listing_translation

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

language string required

The IETF language tag for the language of this translation. Ex: de, en, es, fr, it, ja, nl, pl, pt.

Request bodyapplication/x-www-form-urlencoded

title string required

The title of the Listing of this Translation.

description string required

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

Responses

200

A single ListingTranslation

Response schemaapplication/jsonListingTranslation

Represents the translation data for a Listing.

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

Example response

200 · application/json

{
  "listing_id": 1,
  "language": "string",
  "title": "string",
  "description": "string",
  "tags": [
    "string"
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing Personalization

#updateListingPersonalization

POST/v3/application/shops/{shop_id}/listings/{listing_id}/personalization

Not currently exposed through the Eto API. Documented here for the data model it returns.

General Release

This endpoint is ready for production use.

Creates or updates personalization settings for a listing, allowing the seller to collect personalization from the buyer. This endpoint will fully replace any existing personalization on the listing.

AuthorizationAPI keyconnected store

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Query parameters

supports_multiple_personalization_questions boolean nullable

This query parameter indicates that the caller supports up to 5 personalization questions and the following question types: 'text_input', 'dropdown', 'unlabeled_upload', 'labeled_upload'. Sending this param without updating your application can lead to inadvertently deleting seller-entered data.

Request bodyapplication/json

personalization_questions array of object required

item

question_id integer <int64> nullable≥ 1

The ID of the personalization question. This field is optional. Include it when updating an existing question; omit it when creating a new question. Note: This value may change if the personalization question is updated.

question_text string required

The title of the personalization question. Must be between 1 and 45 characters. See https://developers.etsy.com/documentation/tutorials/personalization-migration#writing-listing-personalization-data

instructions string nullable

Optional instructions for a personalization question. This field is not allowed for 'dropdown' questions. See https://developers.etsy.com/documentation/tutorials/personalization-migration#writing-listing-personalization-data

question_type string required

The type of the personalization question. Note: Currently, only a single question with type 'text_input' is supported. See https://developers.etsy.com/documentation/tutorials/personalization-migration for details about new question types.

Enum"text_input""dropdown""unlabeled_upload""labeled_upload"

required boolean required

When true, the personalization question is required.

max_allowed_files integer <int64> nullable

The maximum number of files the buyer may upload in response to a personalization question. This field is optional and only applicable to 'unlabeled_upload' and 'labeled_upload' questions.

max_allowed_characters integer <int64> nullable

The maximum number of characters the buyer may enter in response to a personalization question. This field is optional and only applicable to 'text_input' questions.

options array of object nullable

The list of options for a personalization question. For 'dropdown' questions, this list contains the options for the dropdown. For 'labeled_upload' questions, this list contains the labels for the files that the buyer may upload, and must match the max_allowed_files value..

item

option_id integer <int64> nullable≥ 1

The ID of the option. This field is optional. Include it when updating an existing option; omit it when creating a new option. Note: This value may change if the option or question is updated.

label string required

The option label. Note: For 'dropdown' questions, max length is 20 characters. For 'labeled_upload' questions, max length is 45 characters.

add_on_price number <float> nullable

The add-on price for a question. This field is optional and only supported for optional questions of type text_input.

Responses

201

A single Listing Personalization record

Response schemaapplication/jsonEtsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization

personalization_questions array of Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

question_id integer <int64> nullable≥ 1

question_text string

instructions string nullable

question_type string

required boolean

max_allowed_characters integer <int64> nullable

max_allowed_files integer <int64> nullable

add_on_price object nullable

A representation of an amount of money.

Money

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

options array of object nullable

item

option_id integer <int64> required nullable≥ 1

label string required

Example response

201 · application/json

{
  "personalization_questions": [
    {
      "question_id": 1,
      "question_text": "string",
      "instructions": "string",
      "question_type": "string",
      "required": true,
      "max_allowed_characters": 0,
      "max_allowed_files": 0,
      "add_on_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "options": [
        {
          "option_id": 1,
          "label": "string"
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#deleteListingPersonalization

DELETE/v3/application/shops/{shop_id}/listings/{listing_id}/personalization

Not currently exposed through the Eto API. Documented here for the data model it returns.

General Release

This endpoint is ready for production use.

Deletes personalization for a listing.

AuthorizationAPI keyconnected store

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Responses

204

The ListingPersonalization resource was correctly deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingPersonalization

GEThttps://eto.tools/api/v1/listings/{listing_id}/personalization

General Release

This endpoint is ready for production use.

Retrieves a listing's personalization questions by listing ID.

AuthorizationAPI keyoperation listing_personalization

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Responses

200

A listing personalization questions

Response schemaapplication/jsonEtsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization

personalization_questions array of Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

question_id integer <int64> nullable≥ 1

question_text string

instructions string nullable

question_type string

required boolean

max_allowed_characters integer <int64> nullable

max_allowed_files integer <int64> nullable

add_on_price object nullable

A representation of an amount of money.

Money

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

options array of object nullable

item

option_id integer <int64> required nullable≥ 1

label string required

Example response

200 · application/json

{
  "personalization_questions": [
    {
      "question_id": 1,
      "question_text": "string",
      "instructions": "string",
      "question_type": "string",
      "required": true,
      "max_allowed_characters": 0,
      "max_allowed_files": 0,
      "add_on_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "options": [
        {
          "option_id": 1,
          "label": "string"
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing Inventory

#getListingInventory

GEThttps://eto.tools/api/v1/listings/{listing_id}/inventory

General Release

This endpoint is ready for production use.

Retrieves the inventory record for a listing. Listings you did not edit using the Etsy.com inventory tools have no inventory records. This endpoint returns SKU data if you are the owner of the inventory records being fetched.

AuthorizationAPI keyconnected storeoperation listing_inventory_get

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Query parameters

show_deleted boolean

A boolean value for inventory whether to include deleted products and their offerings. Default value is false.

includes string

An enumerated string that attaches a valid association. Default value is null.

Enum"Listing"

Responses

200

A single listing inventory record.

Response schemaapplication/jsonListingInventoryWithAssociations

A representation of a single listing's inventory record with associations

products array of ListingInventoryProduct

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

ListingInventoryProduct

A representation of a product for a listing.

product_id integer <int64> ≥ 1

The numeric ID for a specific product purchased from a listing.

sku string

The SKU string for the product

is_deleted boolean

When true, someone deleted this product.

offerings array of ListingInventoryProductOffering

A list of product offering entries for this product.

ListingInventoryProductOffering

A representation of an offering for a listing.

offering_id integer <int64> ≥ 1

The ID for the ProductOffering

quantity integer <int64> ≥ 0

The quantity the ProductOffering

is_enabled boolean

Whether or not the offering can be shown to buyers.

is_deleted boolean

Whether or not the offering has been deleted.

price object

Price data for this ProductOffering

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

readiness_state_id integer <int64> nullable≥ 1

Processing Profile for this ProductOffering

property_values array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

price_on_property array of integer <int64>

quantity_on_property array of integer <int64>

sku_on_property array of integer <int64>

readiness_state_on_property array of integer <int64>

listing object

An enumerated string that attaches a valid association. Default value is null.

ShopListing

A listing from a shop, which contains a product quantity, title, description, price, etc.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

Example response

200 · application/json

{
  "products": [
    {
      "product_id": 1,
      "sku": "string",
      "is_deleted": true,
      "offerings": [
        {
          "offering_id": 1,
          "quantity": 0,
          "is_enabled": true,
          "is_deleted": true,
          "price": {
            "amount": 0,
            "divisor": 0,
            "currency_code": "string"
          },
          "readiness_state_id": 1
        }
      ],
      "property_values": [
        {
          "property_id": 1,
          "property_name": "string",
          "scale_id": 1,
          "scale_name": "string",
          "value_ids": [
            1
          ],
          "values": [
            "string"
          ]
        }
      ]
    }
  ],
  "price_on_property": [
    0
  ],
  "quantity_on_property": [
    0
  ],
  "sku_on_property": [
    0
  ],
  "readiness_state_on_property": [
    1
  ],
  "listing": {
    "listing_id": 1,
    "user_id": 1,
    "shop_id": 1,
    "title": "string",
    "description": "string",
    "rich_description": "string",
    "state": "active",
    "creation_timestamp": 946684800,
    "created_timestamp": 946684800,
    "ending_timestamp": 946684800,
    "original_creation_timestamp": 946684800,
    "last_modified_timestamp": 946684800,
    "updated_timestamp": 946684800,
    "state_timestamp": 946684800,
    "quantity": 0,
    "shop_section_id": 1,
    "featured_rank": 0,
    "url": "string",
    "num_favorers": 0,
    "non_taxable": true,
    "is_taxable": true,
    "is_customizable": true,
    "is_personalizable": true,
    "listing_type": "physical",
    "tags": [
      "string"
    ],
    "materials": [
      "string"
    ],
    "shipping_profile_id": 1,
    "return_policy_id": 1,
    "processing_min": 0,
    "processing_max": 0,
    "who_made": "i_did",
    "when_made": "made_to_order",
    "is_supply": true,
    "item_weight": 0.0,
    "item_weight_unit": "oz",
    "item_length": 0.0,
    "item_width": 0.0,
    "item_height": 0.0,
    "item_dimensions_unit": "in",
    "is_private": true,
    "style": [
      "string"
    ],
    "file_data": "string",
    "has_variations": true,
    "should_auto_renew": true,
    "language": "string",
    "price": {
      "amount": 0,
      "divisor": 0,
      "currency_code": "string"
    },
    "converted_price": {
      "amount": 0,
      "divisor": 0,
      "currency_code": "string"
    },
    "taxonomy_id": 0,
    "readiness_state_id": 1,
    "suggested_title": "string"
  }
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

422

There was a problem processing your request. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#updateListingInventory

PUThttps://eto.tools/api/v1/listings/{listing_id}/inventory

General Release

This endpoint is ready for production use.

Updates the inventory for a listing identified by a listing ID. The update fails if the supplied values for product sku, offering quantity, price, and/or processing profile are incompatible with values in *_on_property fields. When setting a price, assign a float equal to amount divided by divisor as specified in the Money resource.

AuthorizationAPI keyconnected storeoperation listing_inventory_get

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Query parameters

max_variations_supported string

Coming soon: This parameter determines whether a third variation can be added to or updated for a listing. It accepts values of 2 or 3, where 3 enables third-variation support.

Enum"2""3"

Request bodyapplication/json

products array of object required

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

item

sku string nullable

The SKU string for the product

property_values array of object

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

item

property_id integer <int64> required ≥ 1

The unique ID of an Etsy listing property.

value_ids array of integer <int64> required

An array of unique IDs of Etsy listing property values.

scale_id integer <int64> nullable≥ 1

The numeric ID of a single Etsy.com measurement scale. For example, for shoe size, there are three scale_ids available - UK, US/Canada, and EU, where US/Canada has scale_id 19.

property_name string

The name of the property, in the requested locale language.

values array of string required

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

offerings array of object required

A list of product offering entries for this product.

item

price number <float> required

The price of the product.

quantity integer <int64> required

How many of this product are available?

is_enabled boolean required

True if the offering is shown to buyers

readiness_state_id integer <int64> required nullable≥ 1

price_on_property array of integer <int64>

quantity_on_property array of integer <int64>

sku_on_property array of integer <int64>

readiness_state_on_property array of integer <int64> nullable

Responses

200

A single listing's inventory record.

Response schemaapplication/jsonListingInventory

A representation of a single listing's inventory record.

products array of ListingInventoryProduct

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

ListingInventoryProduct

A representation of a product for a listing.

product_id integer <int64> ≥ 1

The numeric ID for a specific product purchased from a listing.

sku string

The SKU string for the product

is_deleted boolean

When true, someone deleted this product.

offerings array of ListingInventoryProductOffering

A list of product offering entries for this product.

ListingInventoryProductOffering

A representation of an offering for a listing.

offering_id integer <int64> ≥ 1

The ID for the ProductOffering

quantity integer <int64> ≥ 0

The quantity the ProductOffering

is_enabled boolean

Whether or not the offering can be shown to buyers.

is_deleted boolean

Whether or not the offering has been deleted.

price object

Price data for this ProductOffering

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

readiness_state_id integer <int64> nullable≥ 1

Processing Profile for this ProductOffering

property_values array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

price_on_property array of integer <int64>

quantity_on_property array of integer <int64>

sku_on_property array of integer <int64>

readiness_state_on_property array of integer <int64>

Example response

200 · application/json

{
  "products": [
    {
      "product_id": 1,
      "sku": "string",
      "is_deleted": true,
      "offerings": [
        {
          "offering_id": 1,
          "quantity": 0,
          "is_enabled": true,
          "is_deleted": true,
          "price": {
            "amount": 0,
            "divisor": 0,
            "currency_code": "string"
          },
          "readiness_state_id": 1
        }
      ],
      "property_values": [
        {
          "property_id": 1,
          "property_name": "string",
          "scale_id": 1,
          "scale_name": "string",
          "value_ids": [
            1
          ],
          "values": [
            "string"
          ]
        }
      ]
    }
  ],
  "price_on_property": [
    0
  ],
  "quantity_on_property": [
    0
  ],
  "sku_on_property": [
    0
  ],
  "readiness_state_on_property": [
    1
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingsInventoryByListingIds

GET/v3/application/listings/batch/inventory

Not currently exposed through the Eto API. Documented here for the data model it returns.

General Release

This endpoint is ready for production use.

Retrieves the inventory record for each listing referenced by listing ID. Requires the listings_r OAuth scope. Limit 100 listing IDs per request. All requested listing IDs must exist — if any single ID is not found, the entire request returns a 404. SKUs within product records are only returned for listings owned by the authenticated user; they are stripped (returned as empty string) for listings owned by other sellers.

AuthorizationAPI keyconnected store

Query parameters

listing_ids array of integer <int64> required

The list of numeric IDS for the listings in a specific Etsy shop.

Responses

200

A list of listings with their inventory records.

Response schemaapplication/jsonShopListingsWithAssociations

A set of ShopListing resources with associations.

count integer <int64> ≥ 0

The number of ShopListing resources found.

results array of ShopListingWithAssociations

The ShopListing resources found.

ShopListingWithAssociations

A listing from a shop, which contains a product quantity, title, description, price, etc. and additional fields which represent associations.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

user_id integer <int64> ≥ 1

The numeric ID for the user posting the listing.

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

title string

description string

A description string of the product for sale in the listing.

rich_description string nullable

state string

Enum"active""inactive""sold_out""draft""expired"

creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

ending_timestamp integer <int64> ≥ 946684800

The listing's expiration time, in epoch seconds.

original_creation_timestamp integer <int64> ≥ 946684800

The listing's creation time, in epoch seconds.

last_modified_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

updated_timestamp integer <int64> ≥ 946684800

The time of the last update to the listing, in epoch seconds.

state_timestamp integer <int64> nullable≥ 946684800

The date and time of the last state change of this listing.

quantity integer <int64> ≥ 0

shop_section_id integer <int64> nullable≥ 1

The numeric ID of a section in a specific Etsy shop.

featured_rank integer <int64>

The positive non-zero numeric position in the featured listings of the shop, with rank 1 listings appearing in the left-most position in featured listing on a shop's home page.

url string

The full URL to the listing's page on Etsy.

num_favorers integer <int64> ≥ 0

The number of users who marked this Listing a favorite.

non_taxable boolean

When true, applicable shop tax rates do not apply to this listing at checkout.

is_taxable boolean

When true, applicable shop tax rates apply to this listing at checkout.

is_customizable boolean

When true, a buyer may contact the seller for a customized order. The default value is true when a shop accepts custom orders. Does not apply to shops that do not accept custom orders.

is_personalizable boolean

When true, this listing is personalizable. The default value is false.

listing_type string

An enumerated type string that indicates whether the listing is physical or a digital download.

Enum"physical""download""both"

tags array of string

materials array of string

A list of material strings for materials used in the product. Valid materials strings contain only letters, numbers, and whitespace characters. (regex: /[^\p{L}\p{Nd}\p{Zs}]/u) Default value is null.

shipping_profile_id integer <int64> nullable≥ 1

The numeric ID of the shipping profile associated with the listing. Required when listing type is physical.

return_policy_id integer <int64> nullable≥ 1

The numeric ID of the Return Policy.

processing_min integer <int64> nullable≥ 0

The minimum number of days required to process this listing. Default value is null.

processing_max integer <int64> nullable≥ 0

The maximum number of days required to process this listing. Default value is null.

who_made string nullable

An enumerated string indicating who made the product. Helps buyers locate the listing under the Handmade heading. Requires 'is_supply' and 'when_made'.

Enum"i_did""someone_else""collective"

when_made string nullable

An enumerated string for the era in which the maker made the product in this listing. Helps buyers locate the listing under the Vintage heading. Requires 'is_supply' and 'who_made'.

Enum"made_to_order""2020_2026""2010_2019""2007_2009""before_2007""2000_2006""1990s""1980s""1970s""1960s""1950s""1940s""1930s""1920s""1910s""1900s""1800s""1700s""before_1700"

is_supply boolean nullable

When true, tags the listing as a supply product, else indicates that it's a finished product. Helps buyers locate the listing under the Supplies heading. Requires 'who_made' and 'when_made'.

item_weight number <float> nullable

The numeric weight of the product measured in units set in 'item_weight_unit'. Default value is null. If set, the value must be greater than 0.

item_weight_unit string nullable

A string defining the units used to measure the weight of the product. Default value is null.

Enum"oz""lb""g""kg"

item_length number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_width number <float> nullable

The numeric width of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_height number <float> nullable

The numeric length of the product measured in units set in 'item_dimensions_unit'. Default value is null. If set, the value must be greater than 0.

item_dimensions_unit string nullable

A string defining the units used to measure the dimensions of the product. Default value is null.

Enum"in""ft""mm""cm""m""yd""inches"

is_private boolean

When true, this is a private listing intended for a specific buyer and hidden from shop view.

style array of string

file_data string nullable

A string describing the files attached to a digital listing.

has_variations boolean

When true, the listing has variations.

should_auto_renew boolean

When true, renews a listing for four months upon expiration.

language string nullable

The IETF language tag for the default language of the listing. Ex: de, en, es, fr, it, ja, nl, pl, pt, ru.

price object

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

converted_price object nullable

The listing price converted to the currency requested via the currency parameter. Only present when the currency parameter is provided. Null if the conversion rate is unavailable.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

taxonomy_id integer <int64> nullable

The numerical taxonomy ID of the listing. See SellerTaxonomy and BuyerTaxonomy for more information.

readiness_state_id integer <int64> nullable≥ 1

suggested_title string nullable

shipping_profile object nullable

An array of data representing the shipping profile resource.

ShopShippingProfile

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

title string nullable

The name string of this shipping profile.

user_id integer <int64> ≥ 1

The numeric ID for the user who owns the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

is_deleted boolean

When true, someone deleted this shipping profile.

shipping_profile_destinations array of ShopShippingProfileDestination

A list of shipping profile destinations available for this shipping profile.

ShopShippingProfileDestination

Represents a shipping destination assigned to a shipping profile.

shipping_profile_destination_id integer <int64> ≥ 1

The numeric ID of the shipping profile destination in the shipping profile associated with the listing.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the shipping profile.

origin_country_iso string <ISO 3166-1 alpha-2>

The ISO code of the country from which the listing ships.

destination_country_iso string

The ISO code of the country to which the listing ships. If null, request sets destination to destination_region. Required if destination_region is null or not provided.

destination_region string

Enum"eu""non_eu""none"

primary_cost object

The cost of shipping to this country/region alone, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_cost object

The cost of shipping to this country/region with another item, measured in the store's default currency.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

shipping_profile_upgrades array of ShopShippingProfileUpgrade

A list of shipping profile upgrades available for this shipping profile.

ShopShippingProfileUpgrade

A representation of a shipping profile upgrade option.

shipping_profile_id integer <int64> ≥ 1

The numeric ID of the base shipping profile.

upgrade_id integer <int64> ≥ 1

The numeric ID that is associated with a shipping upgrade

upgrade_name string

Name for the shipping upgrade shown to shoppers at checkout, e.g. USPS Priority.

type integer <int64>

The type of the shipping upgrade. Domestic (0) or international (1).

Enum01

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

language string

The IETF language tag for the language of the shipping profile. Ex: de, en, es, fr, it, ja, nl, pl, pt

price object

Additional cost of adding the shipping upgrade.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

secondary_price object

Additional cost of adding the shipping upgrade for each additional item.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_carrier_id integer <int64> nullable

The unique ID of a supported shipping carrier, which is used to calculate an Estimated Delivery Date. **Required with mail_class** if min_delivery_days and max_delivery_days are null.

mail_class string nullable

min_delivery_days integer <int64> nullable≥ 1≤ 45

The minimum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with max_delivery_days** if mail_class is null.

max_delivery_days integer <int64> nullable≥ 1≤ 45

The maximum number of business days a buyer can expect to wait to receive their purchased item once it has shipped. **Required with min_delivery_days** if mail_class is null.

origin_postal_code string nullable

profile_type string

Default"manual"

Enum"manual""calculated"

domestic_handling_fee number <float> ≥ 0

The domestic handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

international_handling_fee number <float> ≥ 0

The international handling fee added to buyer's shipping total - only available for calculated shipping profiles.

Default0

user object nullable

Represents a single user of the site

User

user_id integer <int64> ≥ 1

The numeric ID of a user. This number is also a valid shop ID for the user's shop.

primary_email string <email> nullable

An email address string for the user's primary email address. Access to this field is granted on a case by case basis for third-party integrations that require full access

first_name string nullable

The user's first name.

last_name string nullable

The user's last name.

image_url_75x75 string nullable

The user's avatar URL.

shop object nullable

A shop created by an Etsy user.

Shop

shop_id integer <int64> ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

user_id integer <int64> ≥ 1

The numeric user ID of the user who owns this shop.

shop_name string

The shop's name string.

create_date integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The date and time this shop was created, in epoch seconds.

title string nullable

A brief heading string for the shop's main page.

announcement string nullable

An announcement string to buyers that displays on the shop's homepage.

currency_code string

The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.

is_vacation boolean

When true, this shop is not accepting purchases.

vacation_message string nullable

The shop's message string displayed when is_vacation is true.

sale_message string nullable

A message string sent to users who complete a purchase from this shop.

digital_sale_message string nullable

A message string sent to users who purchase a digital item from this shop.

update_date integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

updated_timestamp integer <int64> ≥ 0

The date and time of the last update to the shop, in epoch seconds.

listing_active_count integer <int64> ≥ 0

The number of active listings in the shop.

digital_listing_count integer <int64> ≥ 0

The number of digital listings in the shop.

login_name string

The shop owner's login name string.

accepts_custom_requests boolean

When true, the shop accepts customization requests.

policy_welcome string nullable

The shop's policy welcome string (may be blank).

policy_payment string nullable

The shop's payment policy string (may be blank).

policy_shipping string nullable

The shop's shipping policy string (may be blank).

policy_refunds string nullable

The shop's refund policy string (may be blank).

policy_additional string nullable

The shop's additional policies string (may be blank).

policy_seller_info string nullable

The shop's seller information string (may be blank).

policy_update_date integer <int64> ≥ 0

The date and time of the last update to the shop's policies, in epoch seconds.

policy_has_private_receipt_info boolean

When true, EU receipts display private info.

has_unstructured_policies boolean

When true, the shop displays additional unstructured policy fields.

policy_privacy string nullable

The shop's privacy policy string (may be blank).

vacation_autoreply string nullable

The shop's automatic reply string displayed in new conversations when is_vacation is true.

url string

The URL string for this shop.

image_url_760x100 string nullable

The URL string for this shop's banner image.

num_favorers integer <int64> ≥ 0

The number of users who marked this shop a favorite.

languages array of string

A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.

icon_url_fullxfull string nullable

The URL string for this shop's icon image.

is_using_structured_policies boolean

When true, the shop accepted using structured policies.

has_onboarded_structured_policies boolean

When true, the shop accepted OR declined after viewing structured policies onboarding.

include_dispute_form_link boolean

When true, this shop's policies include a link to an EU online dispute form.

is_direct_checkout_onboarded boolean

(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.

is_etsy_payments_onboarded boolean

When true, the shop has onboarded onto Etsy Payments.

is_calculated_eligible boolean

When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)

is_opted_in_to_buyer_promise boolean

When true, the shop opted in to buyer promise.

is_shop_us_based boolean

When true, the shop is based in the US.

transaction_sold_count integer <int64> ≥ 0

The total number of sales (transactions) for this shop.

shipping_from_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO the shop is shipping from.

shop_location_country_iso string <ISO 3166-1 alpha-2> nullable

The country ISO where the shop is located.

review_count integer <int64> nullable

Number of reviews of shop listings in the past year.

review_average number <float> nullable

Average rating based on reviews of shop listings in the past year.

images array of ListingImage

Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image

ListingImage

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> ≥ 1

The numeric ID of the primary listing image for this transaction.

hex_code string nullable

The webhex string for the image's average color, in webhex notation.

red integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

green integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

blue integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

hue integer <int64> nullable≥ 0

The numeric hue equal to the image's average hue, from 0-360 (HSV color).

saturation integer <int64> nullable≥ 0

The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).

brightness integer <int64> nullable≥ 0

The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).

is_black_and_white boolean nullable

When true, the image is in black & white.

creation_tsz integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

url_75x75 string

The url string for a 75x75 pixel thumbnail of the image.

url_170x135 string

The url string for a 170x135 pixel thumbnail of the image.

url_570xN string

The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.

url_fullxfull string

The url string for the full-size image, up to 3000 pixels in each dimension.

full_height integer <int64> nullable≥ 0

The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.

full_width integer <int64> nullable≥ 0

The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.

alt_text string nullable

Alt text for the listing image. Max length 500 characters.

videos array of ListingVideo

The single video associated with a listing.

ListingVideo

Reference urls and metadata for a video associated with a specific listing.

video_id integer <int64> ≥ 1

The unique ID of a video associated with a listing.

height integer <int64>

The video height dimension in pixels.

width integer <int64>

The video width dimension in pixels.

thumbnail_url string

The url of the video thumbnail.

video_url string

The url of the video file.

video_state string

The current state of a given video. Value is one of active, inactive, deleted or flagged.

Default"active"

Enum"active""inactive""deleted""flagged"

inventory object nullable

An enumerated string that attaches a valid association. Default value is null.

ListingInventory

A representation of a single listing's inventory record.

products array of ListingInventoryProduct

A JSON array of products available in a listing, even if only one product. All field names in the JSON blobs are lowercase.

ListingInventoryProduct

A representation of a product for a listing.

product_id integer <int64> ≥ 1

The numeric ID for a specific product purchased from a listing.

sku string

The SKU string for the product

is_deleted boolean

When true, someone deleted this product.

offerings array of ListingInventoryProductOffering

A list of product offering entries for this product.

ListingInventoryProductOffering

A representation of an offering for a listing.

offering_id integer <int64> ≥ 1

The ID for the ProductOffering

quantity integer <int64> ≥ 0

The quantity the ProductOffering

is_enabled boolean

Whether or not the offering can be shown to buyers.

is_deleted boolean

Whether or not the offering has been deleted.

price object

Price data for this ProductOffering

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

readiness_state_id integer <int64> nullable≥ 1

Processing Profile for this ProductOffering

property_values array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

price_on_property array of integer <int64>

quantity_on_property array of integer <int64>

sku_on_property array of integer <int64>

readiness_state_on_property array of integer <int64>

production_partners array of ShopProductionPartner

Represents a list of production partners for a shop.

ShopProductionPartner

Represents a description of a shop production partner.

production_partner_id integer <int64> ≥ 1

The numeric ID of a production partner.

partner_name string

The name or title of the production partner.

location string

A string representing the production partner location.

skus array of string

translations object nullable

A map of translations for the listing. Default value is a map of all supported languages keyed to null.

ListingTranslations

Container for all current supported translations of a listing. Note that Etsy periodically adds/removes languages, so this list may change in the future.

de object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-GB object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-IN object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

en-US object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

es object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

fr object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

it object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ja object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

nl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pl object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

pt object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

ru object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

sv object nullable

Represents the translation data for a Listing.

ListingTranslation

listing_id integer <int64> ≥ 1

The numeric ID for the Listing.

language string

The IETF language tag (e.g. 'fr') for the language of this translation.

title string nullable

The title of the Listing of this Translation.

description string nullable

The description of the Listing of this Translation.

tags array of string

The tags of the Listing of this Translation.

views integer <int64>

personalization object nullable

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_ListingPersonalization

personalization_questions array of Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

Etsy_Modules_ListingPersonalization_Api_Resources_OpenApi_PersonalizationQuestion

question_id integer <int64> nullable≥ 1

question_text string

instructions string nullable

question_type string

required boolean

max_allowed_characters integer <int64> nullable

max_allowed_files integer <int64> nullable

add_on_price object nullable

A representation of an amount of money.

Money

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

options array of object nullable

item

option_id integer <int64> required nullable≥ 1

label string required

buyer_price object nullable

ListingBuyerPrice

The buyer-facing price for a listing, including VAT, inclusive shipping (UK), and active promotions.

base_price object

The pre-discount listing price with VAT applied, excluding shipping. When a promotion is active, this is the price before the discount is applied.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

shipping_cost object nullable

The shipping cost to the buyer's country. Includes VAT where applicable. Null when shipping is free or unavailable — use is_free_shipping to distinguish.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

is_free_shipping boolean

Whether shipping is free to the buyer's country.

original_price object

The display price. For UK buyers, includes base + shipping (DMCC). For others, base price only.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discounted_price object nullable

The sale price. For UK buyers, includes base + shipping. For others, base price only. Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_amount object nullable

The discount amount as money (original_price - discounted_price). Null if no active promotion.

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

discount_percentage integer <int64> nullable

The discount percentage (e.g. 20 for 20% off). Null if no active promotion or if the promotion is a fixed-amount discount.

has_discount boolean

Whether an active promotion applies to this listing.

discount_start_epoch integer <int64> nullable

The start timestamp of the active promotion. Null if no active promotion.

discount_end_epoch integer <int64> nullable

The end timestamp of the active promotion. Null if no active promotion.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "user_id": 1,
      "shop_id": 1,
      "title": "string",
      "description": "string",
      "rich_description": "string",
      "state": "active",
      "creation_timestamp": 946684800,
      "created_timestamp": 946684800,
      "ending_timestamp": 946684800,
      "original_creation_timestamp": 946684800,
      "last_modified_timestamp": 946684800,
      "updated_timestamp": 946684800,
      "state_timestamp": 946684800,
      "quantity": 0,
      "shop_section_id": 1,
      "featured_rank": 0,
      "url": "string",
      "num_favorers": 0,
      "non_taxable": true,
      "is_taxable": true,
      "is_customizable": true,
      "is_personalizable": true,
      "listing_type": "physical",
      "tags": [
        "string"
      ],
      "materials": [
        "string"
      ],
      "shipping_profile_id": 1,
      "return_policy_id": 1,
      "processing_min": 0,
      "processing_max": 0,
      "who_made": "i_did",
      "when_made": "made_to_order",
      "is_supply": true,
      "item_weight": 0.0,
      "item_weight_unit": "oz",
      "item_length": 0.0,
      "item_width": 0.0,
      "item_height": 0.0,
      "item_dimensions_unit": "in",
      "is_private": true,
      "style": [
        "string"
      ],
      "file_data": "string",
      "has_variations": true,
      "should_auto_renew": true,
      "language": "string",
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "converted_price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "taxonomy_id": 0,
      "readiness_state_id": 1,
      "suggested_title": "string",
      "shipping_profile": {
        "shipping_profile_id": 1,
        "title": "string",
        "user_id": 1,
        "origin_country_iso": "string",
        "is_deleted": true,
        "shipping_profile_destinations": [
          {
            "shipping_profile_destination_id": 1,
            "shipping_profile_id": 1,
            "origin_country_iso": "string",
            "destination_country_iso": "string",
            "destination_region": "eu",
            "primary_cost": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "secondary_cost": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "shipping_carrier_id": 0,
            "mail_class": "string",
            "min_delivery_days": 1,
            "max_delivery_days": 1
          }
        ],
        "shipping_profile_upgrades": [
          {
            "shipping_profile_id": 1,
            "upgrade_id": 1,
            "upgrade_name": "string",
            "type": 0,
            "rank": 0,
            "language": "string",
            "price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "secondary_price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "shipping_carrier_id": 0,
            "mail_class": "string",
            "min_delivery_days": 1,
            "max_delivery_days": 1
          }
        ],
        "origin_postal_code": "string",
        "profile_type": "manual",
        "domestic_handling_fee": 0,
        "international_handling_fee": 0
      },
      "user": {
        "user_id": 1,
        "primary_email": "string",
        "first_name": "string",
        "last_name": "string",
        "image_url_75x75": "string"
      },
      "shop": {
        "shop_id": 1,
        "user_id": 1,
        "shop_name": "string",
        "create_date": 0,
        "created_timestamp": 0,
        "title": "string",
        "announcement": "string",
        "currency_code": "string",
        "is_vacation": true,
        "vacation_message": "string",
        "sale_message": "string",
        "digital_sale_message": "string",
        "update_date": 0,
        "updated_timestamp": 0,
        "listing_active_count": 0,
        "digital_listing_count": 0,
        "login_name": "string",
        "accepts_custom_requests": true,
        "policy_welcome": "string",
        "policy_payment": "string",
        "policy_shipping": "string",
        "policy_refunds": "string",
        "policy_additional": "string",
        "policy_seller_info": "string",
        "policy_update_date": 0,
        "policy_has_private_receipt_info": true,
        "has_unstructured_policies": true,
        "policy_privacy": "string",
        "vacation_autoreply": "string",
        "url": "string",
        "image_url_760x100": "string",
        "num_favorers": 0,
        "languages": [
          "string"
        ],
        "icon_url_fullxfull": "string",
        "is_using_structured_policies": true,
        "has_onboarded_structured_policies": true,
        "include_dispute_form_link": true,
        "is_direct_checkout_onboarded": true,
        "is_etsy_payments_onboarded": true,
        "is_calculated_eligible": true,
        "is_opted_in_to_buyer_promise": true,
        "is_shop_us_based": true,
        "transaction_sold_count": 0,
        "shipping_from_country_iso": "string",
        "shop_location_country_iso": "string",
        "review_count": 0,
        "review_average": 0.0
      },
      "images": [
        {
          "listing_id": 1,
          "listing_image_id": 1,
          "hex_code": "string",
          "red": 0,
          "green": 0,
          "blue": 0,
          "hue": 0,
          "saturation": 0,
          "brightness": 0,
          "is_black_and_white": true,
          "creation_tsz": 0,
          "created_timestamp": 0,
          "rank": 0,
          "url_75x75": "string",
          "url_170x135": "string",
          "url_570xN": "string",
          "url_fullxfull": "string",
          "full_height": 0,
          "full_width": 0,
          "alt_text": "string"
        }
      ],
      "videos": [
        {
          "video_id": 1,
          "height": 0,
          "width": 0,
          "thumbnail_url": "string",
          "video_url": "string",
          "video_state": "active"
        }
      ],
      "inventory": {
        "products": [
          {
            "product_id": 1,
            "sku": "string",
            "is_deleted": true,
            "offerings": [
              {
                "offering_id": 1,
                "quantity": 0,
                "is_enabled": true,
                "is_deleted": true,
                "price": {},
                "readiness_state_id": 1
              }
            ],
            "property_values": [
              {
                "property_id": 1,
                "property_name": "string",
                "scale_id": 1,
                "scale_name": "string",
                "value_ids": [
                  1
                ],
                "values": [
                  "string"
                ]
              }
            ]
          }
        ],
        "price_on_property": [
          0
        ],
        "quantity_on_property": [
          0
        ],
        "sku_on_property": [
          0
        ],
        "readiness_state_on_property": [
          1
        ]
      },
      "production_partners": [
        {
          "production_partner_id": 1,
          "partner_name": "string",
          "location": "string"
        }
      ],
      "skus": [
        "string"
      ],
      "translations": {
        "de": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-GB": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-IN": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "en-US": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "es": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "fr": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "it": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "ja": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "nl": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "pl": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "pt": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "ru": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        },
        "sv": {
          "listing_id": 1,
          "language": "string",
          "title": "string",
          "description": "string",
          "tags": [
            "string"
          ]
        }
      },
      "views": 0,
      "personalization": {
        "personalization_questions": [
          {
            "question_id": 1,
            "question_text": "string",
            "instructions": "string",
            "question_type": "string",
            "required": true,
            "max_allowed_characters": 0,
            "max_allowed_files": 0,
            "add_on_price": {
              "amount": 0,
              "divisor": 0,
              "currency_code": "string"
            },
            "options": [
              {
                "option_id": 1,
                "label": "string"
              }
            ]
          }
        ]
      },
      "buyer_price": {
        "base_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "shipping_cost": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "is_free_shipping": true,
        "original_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discounted_price": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discount_amount": {
          "amount": 0,
          "divisor": 0,
          "currency_code": "string"
        },
        "discount_percentage": 0,
        "has_discount": true,
        "discount_start_epoch": 0,
        "discount_end_epoch": 0
      }
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing Offering

#getListingOffering

GEThttps://eto.tools/api/v1/listings/{listing_id}/products/{product_id}/offerings/{offering_id}

General Release

This endpoint is ready for production use.

Get an Offering for a Listing

AuthorizationAPI keyoperation listing_offering

Path parameters

listing_id integer <int64> required ≥ 1

product_id integer <int64> required ≥ 1

product_offering_id integer <int64> required ≥ 1

Query parameters

legacy boolean

This parameter is needed to enable new parameters and response values related to processing profiles.

Responses

200

A single ListingInventoryProductOffering

Response schemaapplication/jsonListingInventoryProductOffering

A representation of an offering for a listing.

offering_id integer <int64> ≥ 1

The ID for the ProductOffering

quantity integer <int64> ≥ 0

The quantity the ProductOffering

is_enabled boolean

Whether or not the offering can be shown to buyers.

is_deleted boolean

Whether or not the offering has been deleted.

price object

Price data for this ProductOffering

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

readiness_state_id integer <int64> nullable≥ 1

Processing Profile for this ProductOffering

Example response

200 · application/json

{
  "offering_id": 1,
  "quantity": 0,
  "is_enabled": true,
  "is_deleted": true,
  "price": {
    "amount": 0,
    "divisor": 0,
    "currency_code": "string"
  },
  "readiness_state_id": 1
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing Product

#getListingProduct

GEThttps://eto.tools/api/v1/listings/{listing_id}/inventory/products/{product_id}

General Release

This endpoint is ready for production use.

Open API V3 endpoint to retrieve a ListingProduct by ID.

AuthorizationAPI keyconnected storeoperation listing_product

Path parameters

listing_id integer <int64> required ≥ 1

The listing to return a ListingProduct for.

product_id integer <int64> required ≥ 1

The numeric ID for a specific product purchased from a listing.

Query parameters

legacy boolean

This parameter is needed to enable new parameters and response values related to processing profiles.

Responses

200

A single ListingInventoryProduct

Response schemaapplication/jsonListingInventoryProduct

A representation of a product for a listing.

product_id integer <int64> ≥ 1

The numeric ID for a specific product purchased from a listing.

sku string

The SKU string for the product

is_deleted boolean

When true, someone deleted this product.

offerings array of ListingInventoryProductOffering

A list of product offering entries for this product.

ListingInventoryProductOffering

A representation of an offering for a listing.

offering_id integer <int64> ≥ 1

The ID for the ProductOffering

quantity integer <int64> ≥ 0

The quantity the ProductOffering

is_enabled boolean

Whether or not the offering can be shown to buyers.

is_deleted boolean

Whether or not the offering has been deleted.

price object

Price data for this ProductOffering

Money

A representation of an amount of money.

amount integer <int64>

The amount of represented by this data.

divisor integer <int64> ≥ 0

The divisor to render the amount.

currency_code string

The ISO currency code for this data.

readiness_state_id integer <int64> nullable≥ 1

Processing Profile for this ProductOffering

property_values array of ListingPropertyValue

A list of property value entries for this product. Note: parenthesis characters (( and )) are not allowed.

ListingPropertyValue

A representation of structured data values.

property_id integer <int64> ≥ 1

The numeric ID of the Property.

property_name string nullable

The name of the Property.

scale_id integer <int64> nullable≥ 1

The numeric ID of the scale (if any).

scale_name string nullable

The label used to describe the chosen scale (if any).

value_ids array of integer <int64>

The numeric IDs of the Property values

values array of string

The Property values

Example response

200 · application/json

{
  "product_id": 1,
  "sku": "string",
  "is_deleted": true,
  "offerings": [
    {
      "offering_id": 1,
      "quantity": 0,
      "is_enabled": true,
      "is_deleted": true,
      "price": {
        "amount": 0,
        "divisor": 0,
        "currency_code": "string"
      },
      "readiness_state_id": 1
    }
  ],
  "property_values": [
    {
      "property_id": 1,
      "property_name": "string",
      "scale_id": 1,
      "scale_name": "string",
      "value_ids": [
        1
      ],
      "values": [
        "string"
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing Image

#deleteListingImage

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/images/{image_id}

General Release

This endpoint is ready for production use.

Open API V3 endpoint to delete a listing image. A copy of the file remains on our servers, and so a deleted image may be re-associated with the listing without re-uploading the original image; see uploadListingImage.

AuthorizationAPI keyconnected storeoperation listing_image_delete

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> required ≥ 1

The numeric ID of the primary listing image for this transaction.

Responses

204

The ListingImage resource was correctly deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingImage

GEThttps://eto.tools/api/v1/listings/{listing_id}/images/{image_id}

General Release

This endpoint is ready for production use.

Retrieves the references and metadata for a listing image with a specific image ID.

AuthorizationAPI keyoperation listing_image_detail

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> required ≥ 1

The numeric ID of the primary listing image for this transaction.

Responses

200

A single ListingImage

Response schemaapplication/jsonListingImage

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> ≥ 1

The numeric ID of the primary listing image for this transaction.

hex_code string nullable

The webhex string for the image's average color, in webhex notation.

red integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

green integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

blue integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

hue integer <int64> nullable≥ 0

The numeric hue equal to the image's average hue, from 0-360 (HSV color).

saturation integer <int64> nullable≥ 0

The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).

brightness integer <int64> nullable≥ 0

The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).

is_black_and_white boolean nullable

When true, the image is in black & white.

creation_tsz integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

url_75x75 string

The url string for a 75x75 pixel thumbnail of the image.

url_170x135 string

The url string for a 170x135 pixel thumbnail of the image.

url_570xN string

The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.

url_fullxfull string

The url string for the full-size image, up to 3000 pixels in each dimension.

full_height integer <int64> nullable≥ 0

The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.

full_width integer <int64> nullable≥ 0

The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.

alt_text string nullable

Alt text for the listing image. Max length 500 characters.

Example response

200 · application/json

{
  "listing_id": 1,
  "listing_image_id": 1,
  "hex_code": "string",
  "red": 0,
  "green": 0,
  "blue": 0,
  "hue": 0,
  "saturation": 0,
  "brightness": 0,
  "is_black_and_white": true,
  "creation_tsz": 0,
  "created_timestamp": 0,
  "rank": 0,
  "url_75x75": "string",
  "url_170x135": "string",
  "url_570xN": "string",
  "url_fullxfull": "string",
  "full_height": 0,
  "full_width": 0,
  "alt_text": "string"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getListingImages

GEThttps://eto.tools/api/v1/listings/{listing_id}/images

General Release

This endpoint is ready for production use.

Retrieves all listing image resources for a listing with a specific listing ID.

AuthorizationAPI keyoperation listing_images

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Responses

200

An array of ListingImage

Response schemaapplication/jsonListingImages

Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image.

count integer <int64> ≥ 0

The number of results.

results array of ListingImage

The list of requested resources.

ListingImage

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> ≥ 1

The numeric ID of the primary listing image for this transaction.

hex_code string nullable

The webhex string for the image's average color, in webhex notation.

red integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

green integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

blue integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

hue integer <int64> nullable≥ 0

The numeric hue equal to the image's average hue, from 0-360 (HSV color).

saturation integer <int64> nullable≥ 0

The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).

brightness integer <int64> nullable≥ 0

The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).

is_black_and_white boolean nullable

When true, the image is in black & white.

creation_tsz integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

url_75x75 string

The url string for a 75x75 pixel thumbnail of the image.

url_170x135 string

The url string for a 170x135 pixel thumbnail of the image.

url_570xN string

The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.

url_fullxfull string

The url string for the full-size image, up to 3000 pixels in each dimension.

full_height integer <int64> nullable≥ 0

The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.

full_width integer <int64> nullable≥ 0

The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.

alt_text string nullable

Alt text for the listing image. Max length 500 characters.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_id": 1,
      "listing_image_id": 1,
      "hex_code": "string",
      "red": 0,
      "green": 0,
      "blue": 0,
      "hue": 0,
      "saturation": 0,
      "brightness": 0,
      "is_black_and_white": true,
      "creation_tsz": 0,
      "created_timestamp": 0,
      "rank": 0,
      "url_75x75": "string",
      "url_170x135": "string",
      "url_570xN": "string",
      "url_fullxfull": "string",
      "full_height": 0,
      "full_width": 0,
      "alt_text": "string"
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#uploadListingImage

POSThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/images

General Release

This endpoint is ready for production use.

Uploads or assigns an image to a listing identified by a shop ID with a listing ID. To upload a new image, set the image file as the value for the image parameter. You can assign a previously deleted image to a listing using the deleted image's image ID in the listing_image_id parameter. When a request contains both image and listing_image_id parameter values, the endpoint uploads the image in the image parameter only. Note: When uploading a new image, data such as colors and size may return as null values due to asynchronous processing of the image. Use getListingImage endpoint to fetch these values.

AuthorizationAPI keyconnected storeoperation listing_image_upload

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Request bodymultipart/form-data

image string <binary> nullable

The file name string of a file to upload

listing_image_id integer <int64> ≥ 1

The numeric ID of the primary listing image for this transaction.

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

Default1

overwrite boolean

When true, this request replaces the existing image at a given rank.

Defaultfalse

is_watermarked boolean

When true, indicates that the uploaded image has a watermark.

Defaultfalse

alt_text string

Alt text for the listing image. Max length 500 characters.

Default""

Responses

201

A single ListingImage

Response schemaapplication/jsonListingImage

Reference urls and metadata for an image associated with a specific listing. The url_fullxfull parameter contains the URL for full-sized binary image file.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

listing_image_id integer <int64> ≥ 1

The numeric ID of the primary listing image for this transaction.

hex_code string nullable

The webhex string for the image's average color, in webhex notation.

red integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

green integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

blue integer <int64> nullable≥ 0

The numeric red value equal to the image's average red value, from 0-255 (RGB color).

hue integer <int64> nullable≥ 0

The numeric hue equal to the image's average hue, from 0-360 (HSV color).

saturation integer <int64> nullable≥ 0

The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).

brightness integer <int64> nullable≥ 0

The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).

is_black_and_white boolean nullable

When true, the image is in black & white.

creation_tsz integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

created_timestamp integer <int64> ≥ 0

The listing image's creation time, in epoch seconds.

rank integer <int64> ≥ 0

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

url_75x75 string

The url string for a 75x75 pixel thumbnail of the image.

url_170x135 string

The url string for a 170x135 pixel thumbnail of the image.

url_570xN string

The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.

url_fullxfull string

The url string for the full-size image, up to 3000 pixels in each dimension.

full_height integer <int64> nullable≥ 0

The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.

full_width integer <int64> nullable≥ 0

The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.

alt_text string nullable

Alt text for the listing image. Max length 500 characters.

Example response

201 · application/json

{
  "listing_id": 1,
  "listing_image_id": 1,
  "hex_code": "string",
  "red": 0,
  "green": 0,
  "blue": 0,
  "hue": 0,
  "saturation": 0,
  "brightness": 0,
  "is_black_and_white": true,
  "creation_tsz": 0,
  "created_timestamp": 0,
  "rank": 0,
  "url_75x75": "string",
  "url_170x135": "string",
  "url_570xN": "string",
  "url_fullxfull": "string",
  "full_height": 0,
  "full_width": 0,
  "alt_text": "string"
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#ShopListing File

#getListingFile

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/files/{file_id}

General Release

This endpoint is ready for production use.

Retrieves a single file associated with the given digital listing. Requesting a file from a physical listing returns an empty result.

AuthorizationAPI keyconnected storeoperation listing_file_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

listing_file_id integer <int64> required ≥ 1

The unique numeric ID of a file associated with a digital listing.

Responses

200

The metadata for a file associated with a digital listing.

Response schemaapplication/jsonShopListingFile

A file associated with a digital listing.

listing_file_id integer <int64> ≥ 1

The unique numeric ID of a file associated with a digital listing.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

rank integer <int64> ≥ 0

The numeric index of the display order position of this file in the listing, starting at 1.

filename string

The file name string for a file associated with a digital listing.

filesize string

A human-readable format size string for the size of a file.

size_bytes integer <int64> ≥ 0

A number indicating the size of a file, measured in bytes.

filetype string

A type string indicating a file's MIME type.

create_timestamp integer <int64> ≥ 946684800

The unique numeric ID of a file associated with a digital listing.

created_timestamp integer <int64> ≥ 946684800

The unique numeric ID of a file associated with a digital listing.

Example response

200 · application/json

{
  "listing_file_id": 1,
  "listing_id": 1,
  "rank": 0,
  "filename": "string",
  "filesize": "string",
  "size_bytes": 0,
  "filetype": "string",
  "create_timestamp": 946684800,
  "created_timestamp": 946684800
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#deleteListingFile

DELETEhttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/files/{file_id}

General Release

This endpoint is ready for production use.

Deletes a file from a specific listing. When you delete the final file for a digital listing, the listing converts into a physical listing. The response to a delete request returns a list of the remaining file records associated with the given listing.

AuthorizationAPI keyconnected storeoperation listing_file_detail

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

listing_file_id integer <int64> required ≥ 1

The unique numeric ID of a file associated with a digital listing.

Responses

204

The ShopListingFile resource was correctly deleted

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

409

There was a request conflict with the current state of the target resource. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getAllListingFiles

GEThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/files

General Release

This endpoint is ready for production use.

Retrieves all the files associated with the given digital listing. Requesting files from a physical listing returns an empty result.

AuthorizationAPI keyconnected storeoperation listing_file_upload

Path parameters

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

Responses

200

A list of metadata objects for the file resources associated with a listing.

Response schemaapplication/jsonShopListingFiles

Represents several ShopListingFiles.

count integer <int64> ≥ 0

The number of ShopListingFiles being returned..

results array of ShopListingFile

An array of ShopListingFile resources.

ShopListingFile

A file associated with a digital listing.

listing_file_id integer <int64> ≥ 1

The unique numeric ID of a file associated with a digital listing.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

rank integer <int64> ≥ 0

The numeric index of the display order position of this file in the listing, starting at 1.

filename string

The file name string for a file associated with a digital listing.

filesize string

A human-readable format size string for the size of a file.

size_bytes integer <int64> ≥ 0

A number indicating the size of a file, measured in bytes.

filetype string

A type string indicating a file's MIME type.

create_timestamp integer <int64> ≥ 946684800

The unique numeric ID of a file associated with a digital listing.

created_timestamp integer <int64> ≥ 946684800

The unique numeric ID of a file associated with a digital listing.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "listing_file_id": 1,
      "listing_id": 1,
      "rank": 0,
      "filename": "string",
      "filesize": "string",
      "size_bytes": 0,
      "filetype": "string",
      "create_timestamp": 946684800,
      "created_timestamp": 946684800
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#uploadListingFile

POSThttps://eto.tools/api/v1/shops/{shop_id}/listings/{listing_id}/files

General Release

This endpoint is ready for production use.

Uploads a new file for a digital listing, or associates an existing file with a specific listing. You must either provide the listing_file_id of an existing file, or the name and binary file data for a file to upload. Associating an existing file to a physical listing converts the physical listing into a digital listing, which removes all shipping costs and any product and inventory variations.

AuthorizationAPI keyconnected storeoperation listing_file_upload

Path parameters

shop_id integer <int64> required ≥ 1

The unique positive non-zero numeric ID for an Etsy Shop.

listing_id integer <int64> required ≥ 1

The numeric ID for the listing associated to this transaction.

Request bodymultipart/form-data

listing_file_id integer <int64> ≥ 1

The unique numeric ID of a file associated with a digital listing.

file string <binary> nullable

A binary file to upload.

name string

The file name string of a file to upload

rank integer <int64> ≥ 1

The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.

Default1

Responses

201

The metadata for a file associated with a digital listing.

Response schemaapplication/jsonShopListingFile

A file associated with a digital listing.

listing_file_id integer <int64> ≥ 1

The unique numeric ID of a file associated with a digital listing.

listing_id integer <int64> ≥ 1

The numeric ID for the listing associated to this transaction.

rank integer <int64> ≥ 0

The numeric index of the display order position of this file in the listing, starting at 1.

filename string

The file name string for a file associated with a digital listing.

filesize string

A human-readable format size string for the size of a file.

size_bytes integer <int64> ≥ 0

A number indicating the size of a file, measured in bytes.

filetype string

A type string indicating a file's MIME type.

create_timestamp integer <int64> ≥ 946684800

The unique numeric ID of a file associated with a digital listing.

created_timestamp integer <int64> ≥ 946684800

The unique numeric ID of a file associated with a digital listing.

Example response

201 · application/json

{
  "listing_file_id": 1,
  "listing_id": 1,
  "rank": 0,
  "filename": "string",
  "filesize": "string",
  "size_bytes": 0,
  "filetype": "string",
  "create_timestamp": 946684800,
  "created_timestamp": 946684800
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

401

The request lacks valid authentication credentials. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

403

The request attempted to perform an operation it is not allowed to. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#BuyerTaxonomy

#getBuyerTaxonomyNodes

GEThttps://eto.tools/api/v1/buyer-categories

General Release

This endpoint is ready for production use.

Retrieves the full hierarchy tree of buyer taxonomy nodes.

AuthorizationAPI keyoperation buyer_categories

Responses

200

List the full hierarchy tree of buyer taxonomy nodes.

Response schemaapplication/jsonBuyerTaxonomyNodes

A list of taxonomy nodes from the buyer taxonomy tree.

count integer <int64> ≥ 0

The number of results.

results array of BuyerTaxonomyNode

The list of requested resources.

BuyerTaxonomyNode

A taxonomy node in the buyer taxonomy tree.

id integer <int64> ≥ 1

level integer <int64> ≥ 0

The integer depth of this taxonomy node in the seller taxonomy tree, with roots at level 0.

name string

The name string for this taxonomy node.

parent_id integer <int64> nullable≥ 1

The numeric taxonomy ID of the parent of this node.

Defaultnull

children array of BuyerTaxonomyNode

An array of taxonomy nodes for all the direct children of this taxonomy node in the seller taxonomy tree.

recursive: same shape as BuyerTaxonomyNode above

full_path_taxonomy_ids array of integer <int64>

An array of taxonomy_ids including this node and all of its direct parents in the seller taxonomy tree up to a root node. They are listed in order from root to leaf.

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "id": 1,
      "level": 0,
      "name": "string",
      "parent_id": 1,
      "children": [
        {}
      ],
      "full_path_taxonomy_ids": [
        1
      ]
    }
  ]
}

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

#getPropertiesByBuyerTaxonomyId

GEThttps://eto.tools/api/v1/buyer-categories/{category_id}/properties

General Release

This endpoint is ready for production use.

Retrieves a list of product properties, with applicable scales and values, supported for a specific buyer taxonomy ID.

AuthorizationAPI keyoperation buyer_category_properties

Path parameters

taxonomy_id integer <int64> required ≥ 1

Responses

200

A list of product properties, with applicable scales and values.

Response schemaapplication/jsonBuyerTaxonomyNodeProperties

A list of product property definitions.

count integer <int64> ≥ 0

The number of results.

results array of BuyerTaxonomyNodeProperty

The list of requested resources.

BuyerTaxonomyNodeProperty

A product property definition.

property_id integer <int64> ≥ 1

The unique numeric ID of this product property.

name string

The name string for this taxonomy node.

display_name string

The human-readable product property name string.

scales array of BuyerTaxonomyPropertyScale

A list of available scales.

BuyerTaxonomyPropertyScale

A scale defining the assignable increments for the property values available to specific product properties.

scale_id integer <int64> ≥ 1

The unique numeric ID of a scale.

display_name string

The name string for a scale.

description string

The description string for a scale.

is_required boolean

When true, listings assigned eligible taxonomy IDs require this property.

supports_attributes boolean

When true, you can use this property in listing properties.

supports_variations boolean

When true, you can use this property in listing inventory.

is_multivalued boolean

When true, you can assign multiple property values to this property

max_values_allowed integer <int64> nullable

When true, you can assign multiple property values to this property

possible_values array of BuyerTaxonomyPropertyValue

A list of supported property value strings for this property.

BuyerTaxonomyPropertyValue

A property value for a specific product property, which may also employ a specific scale.

value_id integer <int64> nullable≥ 1

The numeric ID of this property value.

name string

The name string of this property value.

scale_id integer <int64> nullable≥ 1

The numeric scale ID of the scale to which this property value belongs.

equal_to array of integer <int64>

A list of numeric property value IDs this property value is equal to (if any).

selected_values array of BuyerTaxonomyPropertyValue

A list of property value strings automatically and always selected for the given property.

BuyerTaxonomyPropertyValue

A property value for a specific product property, which may also employ a specific scale.

value_id integer <int64> nullable≥ 1

The numeric ID of this property value.

name string

The name string of this property value.

scale_id integer <int64> nullable≥ 1

The numeric scale ID of the scale to which this property value belongs.

equal_to array of integer <int64>

A list of numeric property value IDs this property value is equal to (if any).

Example response

200 · application/json

{
  "count": 0,
  "results": [
    {
      "property_id": 1,
      "name": "string",
      "display_name": "string",
      "scales": [
        {
          "scale_id": 1,
          "display_name": "string",
          "description": "string"
        }
      ],
      "is_required": true,
      "supports_attributes": true,
      "supports_variations": true,
      "is_multivalued": true,
      "max_values_allowed": 0,
      "possible_values": [
        {
          "value_id": 1,
          "name": "string",
          "scale_id": 1,
          "equal_to": [
            0
          ]
        }
      ],
      "selected_values": [
        {
          "value_id": 1,
          "name": "string",
          "scale_id": 1,
          "equal_to": [
            0
          ]
        }
      ]
    }
  ]
}

400

There was a problem with the request data. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

404

A resource could not be found. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required

500

The server encountered an internal error. See the error message for details.

Response schemaapplication/jsonErrorSchema

error string required