Reference · built on requestConnectorCommerce & orders

Etsy

Shop receipts, transactions, listing inventory, and order webhooks from Etsy through the Open API v3.

Request EtsyAsk about this listing

About

Etsy is a marketplace for handmade, vintage, and craft-supply goods. A seller's shop holds listings with inventory, shipping profiles, and receipts: each receipt is one order, with its transactions, payment status, shipping status, and refunds. Etsy's Open API v3 exposes these under /v3/application/shops/{shop_id} and pushes order events to a webhook endpoint.

Through Fibric, an operator watches receipts as they are paid, shipped, and canceled, then proposes the next step: submit tracking for a receipt, mark it shipped, or lower a listing's quantity. You approve. The connector makes one call and leaves a record: what changed, why, and how to undo it.

This is a reference listing. It documents what Fibric would read from Etsy and what it could propose, based on the vendor's published interfaces. Fibric builds it under a managed deployment when you request it; selecting it here installs nothing.

What it reads

  • Shop receipts through getShopReceipts, filtered by was_paid, was_shipped, was_delivered, was_canceled, and min_last_modified
  • Transactions on a receipt through getShopReceiptTransactionsByReceipt: listing, product, sku, quantity, price, and expected_ship_date
  • order.paid, order.canceled, order.shipped, and order.delivered webhook events, each carrying a resource_url and shop_id
  • Listing inventory through getListingInventory and getListingsInventoryByListingIds: products, offerings, quantity, and sku
  • Shipping profiles and their destinations through getShopShippingProfiles
  • Payment account ledger entries and payments through getShopPaymentAccountLedgerEntries and getPayments

Proposed actions

  • Target capability: propose submitting tracking for a receipt through createReceiptShipment, with tracking_code, carrier_name, and an optional note_to_buyer
  • Target capability: propose marking a receipt shipped or paid through updateShopReceipt (was_shipped, was_paid)
  • Target capability: propose a listing quantity change through updateListingInventory, which takes the listing's products array with quantity and sku per offering

Proposed actions are target capabilities. Every action runs propose-first and needs a validated deployment and the appropriate permissions.

What you can build

  • Tracking on every receipt

    When your warehouse ships an Etsy order, the operator matches the receipt and proposes createReceiptShipment with the carrier and tracking code. You approve. Etsy notifies the buyer.

    With Tracking Sync

  • Check before it reaches the pick list

    order.paid arrives. The operator reads the receipt's message_from_buyer, address, and quantities against your rules and flags the receipts that look off before they reach your pick list.

    With Order Risk

  • Answer where is my order

    A buyer asks about a late package. The operator reads the receipt's shipments and expected_ship_date and drafts a reply from that record for you to send.

    With WISMO Deflection

  • Keep listing quantities honest

    When stock in your other channel drops, the operator proposes an updateListingInventory call for the affected sku so the Etsy listing does not oversell.

    With Oversell Watch

What it needs

  • An Etsy app registered in the Developer Portal, on the Seller App, Personal App, or Commercial Access path as approved by Etsy
  • OAuth scopes transactions_r for receipts, transactions_w for shipments and receipt updates, listings_r and listings_w for inventory
  • A webhook endpoint added in the Webhooks Portal, with the whsec_ signing secret stored for signature checks
  • Refresh handling: access tokens expire after 3600 seconds and refresh tokens after 90 days
Authentication
An Etsy app keystring sent as x-api-key plus an OAuth 2.0 authorization-code token with PKCE, carrying scopes such as transactions_r, transactions_w, and listings_w.

Limits

  • The Open API has no refund or cancellation endpoint. Refunds appear on the receipt as read-only data; cancellations arrive as order.canceled events.
  • Rate limits are per application, as queries per second and per day, shown in the Developer Portal; a 429 carries retry-after.
  • Buyer address fields on a receipt (first_line, city, zip, formatted_address) are restricted in some regions and may be absent.
  • Four webhook events exist today. Other receipt changes are found by polling getShopReceipts with min_last_modified.

Access and pricing

Reference listing. Fibric builds the connector under a managed deployment when you request it. Your quote covers the build, capabilities, usage, and support.

Request Etsy

Questions and answers

Does Etsy send webhooks when an order changes?
Yes, for four events: order.paid, order.canceled, order.shipped, and order.delivered. Each POST carries event_type, resource_url, and shop_id, and is signed with webhook-id, webhook-timestamp, and webhook-signature headers. Etsy retries on a backoff schedule from 5 seconds up to 10-hour intervals.
Can the connector refund or cancel an Etsy order?
No. The Open API v3 documents no refund or cancel endpoint. It can read refunds on a receipt and receive order.canceled events; the money movement itself stays in Etsy.
What does the OAuth flow require?
Authorization Code Grant with PKCE on every authorization request, a code verifier of 43 to 128 characters, and an x-api-key header on every call. Access tokens last one hour; refresh tokens last 90 days.
Ask about Etsy

Ask about the capabilities and requirements in this listing.

For project-specific requirements, contact Fibric.

This connector listing is developed, published, and supported by Fibric. It describes integration with Etsy through published interfaces. Third-party names and logos identify the systems an integration connects to; they are the property of their respective owners, who are not affiliated with Fibric and do not sponsor or endorse this listing. Trademark policy