Etsy

aid: etsy
url: https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/apis.yml
name: Etsy
type: Index
image: https://kinlane-images.s3.amazonaws.com/shared/apis-json/apis-json-logo.jpg
description: >-
  Etsy is a global marketplace for unique and creative handmade, vintage, and
  craft-supply goods. The Etsy Open API v3 is a REST + OAuth 2.0 surface that
  third-party developers, sellers, and integration partners use to manage
  shops, listings, inventory, receipts, transactions, payments, ledger entries,
  reviews, shipping profiles, processing profiles, production partners, return
  policies, and seller/buyer taxonomy. Webhooks deliver order lifecycle events
  (order.paid, order.canceled, order.shipped, order.delivered) to subscriber
  endpoints. This profile catalogs the public API surface, machine-readable
  artifacts, plans, rate limits, FinOps alignment, and Naftiko capabilities.
created: '2026-05-05'
modified: '2026-05-30'
specificationVersion: '0.19'
tags:
  - Marketplace
  - Ecommerce
  - Handmade
  - Listings
  - Orders
  - Payments
  - Reviews
  - Shipping
  - Taxonomy
  - OAuth2
common:
  - type: PostmanWorkspace
    url: https://www.postman.com/kinlaneapi/etsy/overview
  - type: ArazzoWorkflows
    url: arazzo/
    workflows:
    - url: arazzo/etsy-clone-image-to-new-listing-workflow.yml
      name: Etsy Clone an Image to a New Listing
      summary: Read a source listing's images, create a new draft listing, and assign the source image.
    - url: arazzo/etsy-create-return-policy-and-listing-workflow.yml
      name: Etsy Create Return Policy and Listing
      summary: Create a shop return policy, then create a draft listing that references it.
    - url: arazzo/etsy-create-shipping-profile-and-listing-workflow.yml
      name: Etsy Create Shipping Profile and Listing
      summary: Create a shop shipping profile, then create a draft listing that uses it.
    - url: arazzo/etsy-fulfill-receipt-workflow.yml
      name: Etsy Fulfill a Receipt
      summary: Fetch a receipt, submit tracking to create a shipment, then mark it shipped.
    - url: arazzo/etsy-get-my-shop-listings-workflow.yml
      name: Etsy Get My Shop Listings
      summary: Resolve the authenticated seller's shop and list its listings filtered by state.
    - url: arazzo/etsy-listing-reviews-workflow.yml
      name: Etsy Listing Reviews
      summary: Fetch a single listing, then retrieve the reviews left on that listing.
    - url: arazzo/etsy-listing-with-inventory-workflow.yml
      name: Etsy Listing with Inventory
      summary: Fetch a listing, then retrieve its full inventory record.
    - url: arazzo/etsy-organize-listing-into-section-workflow.yml
      name: Etsy Organize a Listing into a Section
      summary: Create a shop section, then create a draft listing assigned to that section.
    - url: arazzo/etsy-process-unshipped-orders-workflow.yml
      name: Etsy Process Unshipped Orders
      summary: Resolve the seller's shop, list paid-but-unshipped receipts, and ship the first one.
    - url: arazzo/etsy-publish-physical-listing-workflow.yml
      name: Etsy Publish a Physical Listing
      summary: Create a draft physical listing, upload its image, set inventory, then publish it live.
    - url: arazzo/etsy-receipt-listings-detail-workflow.yml
      name: Etsy Receipt Listings Detail
      summary: Fetch a receipt, then list the listings purchased on that receipt.
    - url: arazzo/etsy-receipt-with-transactions-workflow.yml
      name: Etsy Receipt with Transactions
      summary: Fetch a receipt, then retrieve the line-item transactions on that receipt.
    - url: arazzo/etsy-reprice-listing-inventory-workflow.yml
      name: Etsy Reprice Listing Inventory
      summary: Read a listing's inventory, then rewrite its product offerings with new price and quantity.
    - url: arazzo/etsy-shop-reviews-overview-workflow.yml
      name: Etsy Shop Reviews Overview
      summary: Resolve the authenticated seller's shop and pull its reviews.
    - url: arazzo/etsy-shop-shipping-profiles-workflow.yml
      name: Etsy Shop Shipping Profiles
      summary: Resolve the seller's shop and list its shipping profiles.
    - url: arazzo/etsy-shop-transactions-report-workflow.yml
      name: Etsy Shop Transactions Report
      summary: Resolve the seller's shop and pull all of its transactions.
    - url: arazzo/etsy-update-shop-storefront-workflow.yml
      name: Etsy Update Shop Storefront
      summary: Read a shop, then update its storefront messaging fields.
    - url: arazzo/etsy-user-shop-profile-workflow.yml
      name: Etsy User Shop Profile
      summary: Fetch a user profile, then resolve the shop that user owns.
  - type: Website
    url: https://www.etsy.com
  - type: DeveloperPortal
    url: https://developers.etsy.com/
  - type: Documentation
    url: https://developers.etsy.com/documentation
  - type: Reference
    url: https://developers.etsy.com/documentation/reference
  - type: GitHubOrganization
    url: https://github.com/etsy
  - type: LinkedIn
    url: https://www.linkedin.com/company/etsy
  - type: TwitterAccount
    url: https://twitter.com/etsy
  - type: StatusPage
    url: https://www.etsystatus.com/
  - type: TermsOfService
    url: https://www.etsy.com/legal/api/terms
  - type: PrivacyPolicy
    url: https://www.etsy.com/legal/privacy
  - type: SecurityPolicy
    url: https://www.etsy.com/legal/api/terms
  - type: Pricing
    url: https://developers.etsy.com/documentation/essentials/rate-limits
  - type: Support
    url: mailto:developers@etsy.com
  - type: ChangeLog
    url: https://developers.etsy.com/changelog
  - type: CodeOfConduct
    url: https://etsy.github.io/codeofconduct.html
  - type: Plans
    url: plans/etsy-plans-pricing.yml
  - type: RateLimits
    url: rate-limits/etsy-rate-limits.yml
  - type: FinOps
    url: finops/etsy-finops.yml
  - type: Vocabulary
    url: vocabulary/etsy-vocabulary.yml
  - type: SpectralRules
    url: rules/etsy-rules.yml
  - type: Tools
    title: Pinot MCP Server (Etsy fork)
    url: https://github.com/etsy/mcp-pinot
  - type: Tools
    title: XCLogParser
    url: https://github.com/etsy/XCLogParser
  - type: Tools
    title: Cartography
    url: https://github.com/etsy/cartography
apis:
  - aid: etsy:open-api-v3
    name: Etsy Open API v3
    description: >-
      The Etsy Open API v3 is the official REST + OAuth 2.0 surface used to
      build applications against the Etsy marketplace. It focuses on three
      primary use cases: listing management (create, update, and inventory
      listings, plus images, files, videos, variations, translations,
      personalization, and offerings), post-purchase order management
      (receipts, transactions, payments, ledger entries, and reviews), and shop
      management (shop sections, shipping profiles, processing profiles,
      production partners, return policies, holiday preferences). The API also
      exposes the buyer taxonomy and seller taxonomy that power Etsy category
      navigation and listing classification. Authentication uses an x-api-key
      header (your keystring) on every request, with OAuth 2.0 authorization
      code + PKCE for user-scoped operations. The default base URL documented
      in the OpenAPI spec is https://openapi.etsy.com; live production calls
      also resolve at https://api.etsy.com/v3/application.
    humanURL: https://developers.etsy.com/documentation
    baseURL: https://openapi.etsy.com
    tags:
      - Open API v3
      - Marketplace
      - Listings
      - Receipts
      - Shop
      - Taxonomy
      - OAuth2
    properties:
      - type: Documentation
        url: https://developers.etsy.com/documentation
      - type: Reference
        url: https://developers.etsy.com/documentation/reference
      - type: Authentication
        url: https://developers.etsy.com/documentation/essentials/authentication
      - type: OAuth2
        url: https://developers.etsy.com/documentation/essentials/oauth2
      - type: RateLimits
        url: https://developers.etsy.com/documentation/essentials/rate-limits
      - type: Requests
        url: https://developers.etsy.com/documentation/essentials/requests
      - type: Migration
        url: https://developers.etsy.com/documentation/migration/index
      - type: OpenAPI
        url: openapi/etsy-openapi-original.yml
      - type: OpenAPI
        title: Upstream OpenAPI JSON
        url: https://www.etsy.com/openapi/generated/oas/3.0.0.json
      - type: SourceCode
        title: Open API repo
        url: https://github.com/etsy/open-api
      - type: NaftikoCapability
        url: capabilities/open-api-v3-user.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-user-address.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-section.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-shipping-profile.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-processing-profiles.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-production-partner.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-return-policy.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-holiday-preferences.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-receipt.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-receipt-transactions.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing-file.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing-image.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing-video.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing-inventory.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing-offering.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing-product.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing-translation.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing-personalization.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-shop-listing-variation-image.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-payment.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-ledger-entry.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-review.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-buyer-taxonomy.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-seller-taxonomy.yaml
      - type: NaftikoCapability
        url: capabilities/open-api-v3-other.yaml
  - aid: etsy:webhooks
    name: Etsy Open API v3 Webhooks
    description: >-
      AsyncAPI 2.6 description of Etsy's outbound webhook surface for the Open
      API v3. Covers the four documented event types (order.paid,
      order.canceled, order.shipped, order.delivered), the common webhook
      envelope (event_type, resource_url, shop_id), the signing headers
      (webhook-id, webhook-timestamp, webhook-signature), HMAC-SHA256 signature
      verification procedure, and Etsy's documented retry schedule.
    humanURL: https://developers.etsy.com/documentation/essentials/webhooks
    tags:
      - Webhooks
      - Events
      - AsyncAPI
      - Order Lifecycle
    properties:
      - type: Documentation
        url: https://developers.etsy.com/documentation/essentials/webhooks
      - type: AsyncAPI
        url: https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/asyncapi/etsy-webhooks-asyncapi.yml
features:
  - name: Listing Management
    description: >-
      Create, update, retrieve, deactivate, and delete shop listings;
      manage listing images, videos, files, translations, personalization,
      variation images, inventory, offerings, and products.
  - name: Order & Receipt Management
    description: >-
      Read shop receipts, transactions, payments, and ledger entries; mark
      receipts paid or shipped; create shipment tracking entries; manage
      post-purchase order workflows.
  - name: Shop Management
    description: >-
      Update shop properties, sections, shipping profiles, processing
      profiles, production partners, return policies, and holiday
      preferences.
  - name: Taxonomy
    description: >-
      Browse the buyer taxonomy used for navigation and the seller taxonomy
      used to classify listings and produce required and optional
      properties for each category.
  - name: Reviews
    description: >-
      Retrieve transaction-level and shop-level reviews left by buyers,
      including rating, review text, language, and image URLs.
  - name: Webhooks
    description: >-
      Subscribe an HTTPS endpoint to order.paid, order.canceled,
      order.shipped, and order.delivered events; verify deliveries with
      HMAC-SHA256 and the documented retry schedule.
  - name: OAuth 2.0 Authentication
    description: >-
      Authorization Code + PKCE flow with refresh tokens for user-scoped
      operations; per-request x-api-key header for every call.
useCases:
  - name: Inventory Sync
    description: >-
      Keep shop listings, prices, quantities, and product variations in
      sync between Etsy and a seller's inventory management system.
  - name: Multi-Channel Order Fulfillment
    description: >-
      Pull paid Etsy receipts into a fulfillment platform, generate
      shipping labels, write tracking back to Etsy, and trigger seller
      notifications.
  - name: Shop Analytics
    description: >-
      Aggregate ledger entries, payments, and receipts to produce seller
      revenue, fee, and payout reporting.
  - name: Listing Automation
    description: >-
      Programmatically create and update listings from a product catalog,
      including images, videos, variations, and personalization options.
  - name: Customer Service
    description: >-
      Surface reviews and message-related receipt context to seller-side
      customer service tooling.
  - name: Shipping Integration
    description: >-
      Manage shop shipping profiles, attach tracking codes to fulfilled
      receipts, and configure region- and weight-based shipping rules.
integrations:
  - name: QuickBooks
    description: Sync Etsy sales, fees, and payouts into QuickBooks accounting.
  - name: ShipStation
    description: Pull Etsy orders into ShipStation for label generation and tracking.
  - name: Printful / Printify
    description: Connect print-on-demand fulfillment for Etsy listings.
  - name: Zapier
    description: Trigger workflows from Etsy receipts, listings, and webhook events.
  - name: Make.com (Integromat)
    description: Visual automation around Etsy shop, listings, and order events.
solutions:
  - name: Inventory & Catalog Management
    description: >-
      Maintain Etsy listings, inventory levels, and variations from a
      central product information management system.
  - name: Order Operations
    description: >-
      Run paid-order processing, shipping, refunds, and post-purchase
      messaging against Etsy receipts and transactions.
  - name: Financial Reporting
    description: >-
      Reconcile Etsy ledger entries, payments, and refunds into
      bookkeeping, tax, and revenue recognition systems.
  - name: Marketplace Expansion
    description: >-
      Use Etsy alongside other marketplaces to expand reach for handmade,
      vintage, and craft-supply sellers.
maintainers:
  - FN: Kin Lane
    email: info@apievangelist.com