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.
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.
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.
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.
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/jsonOAuth 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.
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)".
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).
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.
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.
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>
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.
| Scope | Method & Endpoint | Operation ID | Operational Purpose |
|---|---|---|---|
shops_r | GET /v3/application/users/{user_id}/shops | getShopByOwnerUserId | Resolves 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} | getShop | Refreshes 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 | getListingsByShop | Synchronizes 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 | getListingInventory | Reads authoritative variant matrices, SKU identifiers, pricing offerings, and live on-hand quantities from Etsy. |
listings_w | PUT /v3/application/listings/{listing_id}/inventory | updateListingInventory | Pushes 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 | getShopReceipts | Fetches 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} | updateShopReceipt | Updates 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 | createReceiptShipment | Submits 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. |
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.
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.
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 HTTP429 Too Many Requestsor503 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:
createReceiptShipmentandupdateListingInventorycarry internal idempotency keys so transient network retries never send duplicate tracking emails. - Non-Retryable 4xx Isolation:
401triggers a single token refresh;403or400halts immediately and surfaces actionable guidance to the shop owner.
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.