LoomSync Studio
Technical Reference • Etsy Open API v3

LoomSync Studio Integration Architecture & API Compliance

Complete technical documentation covering LoomSync Studio's server-side Etsy Open API v3 integration, OAuth 2.0 + PKCE (S256) handshake, explicit scope-to-endpoint mapping, rate-limit backoff strategy, and Etsy API Terms cache freshness enforcement.

Section 01

Etsy Open API v3 Integration Architecture

LoomSync Studio is architected as a multi-tenant B2B SaaS workspace operated by LoomSync Systems LLC and designed exclusively around official server-to-server requests to https://api.etsy.com/v3. The platform performs zero screen-scraping, zero headless browser automation, and zero credential collection.

Server-Only API Gateway

All Etsy API v3 calls execute exclusively from authenticated server workers attaching x-api-key and Bearer OAuth headers over TLS 1.3. API credentials never reach the client bundle.

Encrypted Token Vault

Each connected shop's access_token and refresh_token are encrypted at rest using AES-256-GCM with per-record initialization vectors and KMS-managed envelope keys.

Strict Tenant Isolation

Every catalog SKU, inventory lock, and fulfillment queue record is scoped by workspace ID and Etsy shop_id with role-based access controls and zero cross-tenant visibility.

Outbound Request Topology (Server-Side Worker)

[Next.js App Server / Sync Worker]
   ├── Decrypt OAuth access_token (AES-256-GCM Vault)
   ├── Enforce Per-Shop Token Bucket & Cache Freshness Guard
   └── HTTPS / TLS 1.3 ──▶ https://api.etsy.com/v3/application/...
         Headers:
           x-api-key: <ETSY_KEYSTRING>:<ETSY_SHARED_SECRET>
           Authorization: Bearer <user_id>.<access_token>
           Accept: application/json
Section 02

OAuth 2.0 + PKCE (S256) Handshake Sequence

Seller shop authorization follows Etsy's OAuth 2.0 Authorization Code flow with Proof Key for Code Exchange (RFC 7636) using SHA-256 challenge verification.

01

Seller Initiates Connection

Inside LoomSync Studio, the shop owner reviews the Terms of Service and Privacy Policy, checks the explicit authorization agreement, and clicks "Connect Etsy Shop (OAuth 2.0)".

02

Server Generates PKCE Pair & CSRF State

The Next.js backend generates a 256-bit cryptographically random code_verifier, derives code_challenge = BASE64URL(SHA256(code_verifier)) with code_challenge_method=S256, and binds a single-use state nonce to an HttpOnly, Secure, SameSite=Lax session cookie (lms_sid).

03

Redirect to Etsy Official Consent Screen

The browser redirects directly to https://www.etsy.com/oauth/connect with client_id, redirect_uri, response_type=code, requested scopes, state, and code_challenge. LoomSync Studio never sees or prompts for Etsy credentials.

04

Callback Validation & Code Exchange

Etsy returns code and state to the registered HTTPS callback. Our server verifies state in constant time and executes a back-channel POST to https://api.etsy.com/v3/public/oauth/token with grant_type=authorization_code and the stored code_verifier.

05

AES-256-GCM Vault Storage & Refresh Lifecycle

Etsy returns an access_token (prefixed with numeric user_id, 3,600s TTL) and refresh_token (90-day TTL). Both tokens are encrypted server-side with AES-256-GCM before storage in isolated PostgreSQL and are never serialized to browser storage.

Authorization Redirect Parameters

GET https://www.etsy.com/oauth/connect
  ?response_type=code
  &redirect_uri=https://loomsyncstudio.site/api/auth/etsy/callback
  &scope=shops_r%20listings_r%20listings_w%20transactions_r%20transactions_w
  &client_id=<ETSY_KEYSTRING>
  &state=<256-bit-csrf-nonce>
  &code_challenge=<BASE64URL(SHA256(code_verifier))>
  &code_challenge_method=S256

Server-Side Token Exchange & Refresh

POST https://api.etsy.com/v3/public/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=<ETSY_KEYSTRING>
&redirect_uri=https://loomsyncstudio.site/api/auth/etsy/callback
&code=<authorization_code>
&code_verifier=<stored_pkce_verifier>
Section 03

Principle of Least Privilege: Scope-to-Endpoint Mapping

LoomSync Studio requests only the five operational Etsy OAuth 2.0 scopes strictly required for catalog synchronization, real-time SKU inventory protection, and verified order shipment updates. We do not request email_r or harvest buyer email addresses for marketing.

ScopeMethod & EndpointOperation IDOperational Purpose
shops_r
GET/v3/application/users/{user_id}/shops
getShopByOwnerUserIdResolves the authenticated seller's Etsy shop_id, shop name, currency code, and active shop configuration immediately after OAuth consent.
shops_r
GET/v3/application/shops/{shop_id}
getShopRefreshes shop-level metadata, fulfillment SLA benchmarks, and SKU analytics summaries within the 24-hour maximum freshness ceiling.
listings_r
GET/v3/application/shops/{shop_id}/listings
getListingsByShopSynchronizes active, draft, and inactive catalog items into the workspace catalog grid without storing stale snapshots beyond 6 hours.
listings_r
GET/v3/application/listings/{listing_id}/inventory
getListingInventoryReads authoritative variant matrices, SKU identifiers, pricing offerings, and live on-hand quantities from Etsy.
listings_w
PUT/v3/application/listings/{listing_id}/inventory
updateListingInventoryPushes reconciled warehouse stock quantities back to existing Etsy listings to prevent overselling. Never used to create duplicate listings or duplicate shops.
transactions_r
GET/v3/application/shops/{shop_id}/receipts
getShopReceiptsFetches newly paid receipts, ordered SKUs, quantities, and buyer personalization notes for workshop production and fulfillment routing.
transactions_w
PUT/v3/application/shops/{shop_id}/receipts/{receipt_id}
updateShopReceiptUpdates order receipt fulfillment state (was_shipped / was_paid) strictly after verified seller confirmation inside the fulfillment console.
transactions_w
POST/v3/application/shops/{shop_id}/receipts/{receipt_id}/tracking
createReceiptShipmentSubmits verified carrier_name and tracking_code for dispatched orders and relies on Etsy's native buyer shipping notification pipeline. Subject to Etsy Fulfillment endpoint approval.
Duplicate Listing Prohibition Enforcement

listings_w is strictly constrained to inventory quantity and SKU reconciliation on existing seller listings. LoomSync Studio blocks bulk cloning or cross-shop duplicate listing creation in accordance with Etsy Seller Policy.

Fulfillment Endpoint Governance

Both updateShopReceipt and createReceiptShipment require explicit seller action (verified carrier + tracking number) and honor Etsy's separate Commercial Access fulfillment approval for shipment tracking submission.

Section 04

Rate-Limit Pacing & Exponential Backoff Handling

To remain a well-behaved API citizen and stay strictly within Etsy Open API v3 QPS and daily quota envelopes, our sync engine inspects Etsy rate-limit response headers on every request and coordinates outbound calls through a distributed token-bucket queue.

Inspected Etsy Rate-Limit Headers

  • X-Limit-Per-Second & X-Remaining-This-Second: Dynamically throttles burst sync jobs when remaining per-second budget falls below 20%.
  • X-Limit-Per-Day & X-Remaining-Today: Defers non-urgent background analytics polling when daily quota consumption approaches 85%.
  • Retry-After: Respected verbatim whenever Etsy returns HTTP 429 Too Many Requests or 503 Service Unavailable.

Jittered Retry & Idempotency Policy

  • Exponential Backoff with Full Jitter: Delay calculated as random(0, min(32000ms, 500ms * 2^attempt)) up to 5 attempts, preventing thundering-herd retries.
  • Write-Mutation Idempotency: createReceiptShipment and updateListingInventory carry internal idempotency keys so transient network retries never send duplicate tracking emails.
  • Non-Retryable 4xx Isolation: 401 triggers a single token refresh; 403 or 400 halts immediately and surfaces actionable guidance to the shop owner.
Section 05

Cache Freshness & Buyer PII Retention Compliance

Per the Etsy API Terms of Use, cached Etsy content must never grow stale, and buyer personal data must only be retained for the duration strictly necessary to fulfill orders and satisfy statutory accounting obligations.

Listing Content TTL

< 6 Hours

Active and inactive listing attributes, prices, and inventory counts refresh automatically every 15–45 minutes and hard-expire at 5 hours 45 minutes, strictly under Etsy's 6-hour maximum ceiling.

Shop Metadata TTL

< 24 Hours

Shop profile fields, shipping profiles, and non-listing Etsy content hard-expire at 23 hours 30 minutes, guaranteeing compliance with Etsy's 24-hour staleness limit.

Buyer PII Purge SLA

24h / 30–90d

Completed order PII auto-purges within 30–90 days post-fulfillment, or within 24 hours immediately following OAuth disconnect or erasure request via compliance@loomsyncstudio.site or support@loomsyncstudio.site.

Ready to verify these workflows interactively?

Launch the Reviewer Sandbox to inspect PKCE OAuth consent, live stock delta syncing, and tracking submission payloads with synthetic shop data.