Etsy API

Navigate to developers.etsy.com and sign in with your Etsy account. Click Create a New App. Fill in the application name, website, and a brief description of what your FlutterFlow app will do. Under the redirect URI, enter a URI that your Cloud Function can accept — for the PKCE server-side exchange flow, you can use a Cloud Function URL that will receive the authorization code after the user consents. A common approach is to use https://us-central1-YOUR_PROJECT.cloudfunctions.net/etsyOauthCallback as the redirect URI. After creating the app, Etsy provides two values: a Keystring (also called the API key) and a Shared Secret. In Etsy Open API v3, the keystring serves double duty: it is both the x-api-key header value on every API call AND the OAuth client_id in the PKCE flow. The Shared Secret is less commonly needed for PKCE guest flows but store it securely in Firebase Functions environment variables alongside the keystring. Select the OAuth scopes your app needs. For a listing and order dashboard, you'll need at minimum: listings_r (read listings), transactions_r (read orders/receipts), shops_r (read shop info). Grant only the scopes your app actually uses — requesting unnecessary scopes reduces the chance Etsy approves your app for commercial use. Note: new Etsy developer apps start with standard rate limits (typically 10 QPS / 10,000 requests per day — verify in the current developer docs). If you plan to build a multi-seller platform or a high-volume app, apply for commercial API access through Etsy's developer program.

The Etsy OAuth 2.0 PKCE flow requires generating a cryptographically random code_verifier, hashing it to a code_challenge, constructing the authorization URL with both values, redirecting the user to Etsy's consent screen, and then exchanging the returned authorization code for access and refresh tokens. This cannot be done safely in raw Dart client code — the code_verifier would be accessible in the app binary, and storing the refresh token in App State would lose it every time the app restarts. Deploy two Firebase Cloud Functions: one that generates a PKCE authorization URL and temporary state (/etsyAuthUrl), and one that receives the Etsy OAuth callback, performs the token exchange, and stores the refresh token securely in Firestore per user (/etsyOauthCallback). Store your Etsy keystring in Firebase Functions environment variables as ETSY_KEYSTRING and your registered redirect URI as ETSY_REDIRECT_URI. The token exchange function stores the refresh token in Firestore at users/{userId}/etsyTokens/{shopId} — this means each user of your FlutterFlow app can authorize multiple Etsy shops independently. The function returns only the short-lived access token and the token's expiry time back to FlutterFlow. FlutterFlow never sees the refresh token — only the Cloud Function reads and stores it. For the authorization URL endpoint, FlutterFlow calls /etsyAuthUrl with the user's Firebase UID, and the function generates a PKCE pair, stores the code_verifier temporarily in Firestore (for the callback to retrieve), and returns the full Etsy authorization URL including the code_challenge. FlutterFlow then launches this URL in an in-app browser or WebView.

1const functions = require('firebase-functions');
2const axios = require('axios');
3const crypto = require('crypto');
4const admin = require('firebase-admin');
5
6if (!admin.apps.length) admin.initializeApp();
7const db = admin.firestore();
8
9const KEYSTRING    = process.env.ETSY_KEYSTRING;
10const REDIRECT_URI = process.env.ETSY_REDIRECT_URI;
11const TOKEN_URL    = 'https://api.etsy.com/v3/public/oauth/token';
12
13function generatePKCE() {
14  const verifier = crypto.randomBytes(32).toString('base64url');
15  const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
16  return { verifier, challenge };
17}
18
19// Step 1: Generate the Etsy authorization URL
20exports.etsyAuthUrl = functions.https.onRequest(async (req, res) => {
21  res.set('Access-Control-Allow-Origin', '*');
22  if (req.method === 'OPTIONS') { res.status(204).send(''); return; }
23
24  const userId = req.query.userId;
25  if (!userId) { res.status(400).json({ error: 'userId required' }); return; }
26
27  const { verifier, challenge } = generatePKCE();
28  const state = crypto.randomBytes(16).toString('hex');
29
30  // Store verifier and state temporarily (expires in 10 min)
31  await db.collection('etsyPkceState').doc(state).set({
32    verifier, userId,
33    createdAt: admin.firestore.FieldValue.serverTimestamp(),
34  });
35
36  const scopes = 'listings_r transactions_r shops_r';
37  const authUrl = `https://www.etsy.com/oauth/connect?response_type=code` +
38    `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
39    `&scope=${encodeURIComponent(scopes)}` +
40    `&client_id=${KEYSTRING}` +
41    `&state=${state}` +
42    `&code_challenge=${challenge}` +
43    `&code_challenge_method=S256`;
44
45  res.status(200).json({ authUrl });
46});
47
48// Step 2: Handle the OAuth callback and exchange code for tokens
49exports.etsyOauthCallback = functions.https.onRequest(async (req, res) => {
50  const { code, state } = req.query;
51  if (!code || !state) {
52    res.status(400).send('Missing code or state');
53    return;
54  }
55
56  const stateDoc = await db.collection('etsyPkceState').doc(state).get();
57  if (!stateDoc.exists) { res.status(400).send('Invalid or expired state'); return; }
58
59  const { verifier, userId } = stateDoc.data();
60  await stateDoc.ref.delete(); // Single use
61
62  try {
63    const tokenResp = await axios.post(TOKEN_URL, new URLSearchParams({
64      grant_type: 'authorization_code',
65      client_id: KEYSTRING,
66      redirect_uri: REDIRECT_URI,
67      code,
68      code_verifier: verifier,
69    }), { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
70
71    const { access_token, refresh_token, expires_in } = tokenResp.data;
72
73    // Persist refresh token per user in Firestore
74    await db.collection('users').doc(userId).collection('etsyTokens').doc('primary').set({
75      refresh_token,
76      updatedAt: admin.firestore.FieldValue.serverTimestamp(),
77    });
78
79    // Return access token + expiry to FlutterFlow via deep link or redirect
80    res.redirect(
81      `your-app-scheme://etsy-callback?access_token=${access_token}&expires_in=${expires_in}`
82    );
83  } catch (error) {
84    res.status(500).send(`Token exchange failed: ${error.message}`);
85  }
86});
87
88// Step 3: Refresh the access token (called from FlutterFlow before it expires)
89exports.etsyRefreshToken = functions.https.onRequest(async (req, res) => {
90  res.set('Access-Control-Allow-Origin', '*');
91  if (req.method === 'OPTIONS') { res.status(204).send(''); return; }
92
93  const { userId } = req.body;
94  if (!userId) { res.status(400).json({ error: 'userId required' }); return; }
95
96  const tokenDoc = await db.collection('users').doc(userId).collection('etsyTokens').doc('primary').get();
97  if (!tokenDoc.exists) { res.status(404).json({ error: 'No token found for user' }); return; }
98
99  const { refresh_token } = tokenDoc.data();
100  try {
101    const tokenResp = await axios.post(TOKEN_URL, new URLSearchParams({
102      grant_type: 'refresh_token',
103      client_id: KEYSTRING,
104      refresh_token,
105    }), { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } });
106    res.status(200).json({
107      access_token: tokenResp.data.access_token,
108      expires_in: tokenResp.data.expires_in,
109    });
110  } catch (error) {
111    res.status(401).json({ error: 'Refresh failed — user must re-authorize' });
112  }
113});
114

With the Cloud Functions deployed, wire up the Etsy login flow in FlutterFlow. Create a ConnectEtsy page with a Connect My Etsy Shop button. In the button's Action Flow, add a Backend/API Call action that calls your EtsyAuth API Group → GetAuthUrl (set up in the next step) with the logged-in user's Firebase UID. Store the returned authUrl in a page state variable. Then add a Launch URL action pointing to the authUrl variable. This opens the Etsy consent screen in the device's browser. On the consent screen, the seller approves access, Etsy redirects to your etsyOauthCallback function which exchanges the code and stores the refresh token in Firestore, then redirects the user back to your app via the deep link URI with the access token in the URL parameters. In FlutterFlow, configure deep link handling: go to Settings → App Details → Deep Links. Add your custom scheme (e.g. etsyapp://etsy-callback). On the page that receives this deep link — typically your home page or the ConnectEtsy page — add an On Deep Link action that reads the access_token and expires_in parameters from the deep link URL. Store the access_token in App State (String variable: etsyAccessToken) and calculate the expiry timestamp (current time + expires_in seconds) and store it in another App State variable (etsyTokenExpiry as an integer Unix timestamp). Also store the Firebase user ID in App State — you'll need it to call the RefreshToken function. Once the access token is stored in App State, navigate automatically to the seller dashboard. You don't need to display the token anywhere in the UI.

In FlutterFlow, click API Calls in the left nav → + Add → Create API Group. Name it EtsyOpenAPI. Set the Base URL to https://openapi.etsy.com/v3. This is where the critical dual-header setup happens. In the Group Headers section, add BOTH of the following headers — both are mandatory on every Etsy v3 API call: 1. Header name: x-api-key, value: your actual Etsy keystring (the alphanumeric API key from developers.etsy.com). Unlike the Bearer token, the keystring doesn't change per user or per session — it's your app's static credential. You can store it in App Values for cleanliness. 2. Header name: Authorization, value: Bearer {{accessToken}} — make accessToken a Group-level variable so you can pass the current App State value to all calls. Add your first API Call inside the group: name it GetShopListings. Method: GET. Endpoint: /application/shops/{{shopId}}/listings/active. Variables: shopId (String), limit (Integer, default 25), offset (Integer, default 0). The shopId comes from a separate Etsy API call to get the authenticated user's shop — add a second API Call named GetMe: GET /application/users/me — this returns the seller's shop_id that you'll store in App State after the OAuth flow completes. Add a third API Call named GetShopReceipts (orders): GET /application/shops/{{shopId}}/receipts. Variables: shopId, was_paid (Boolean filter), limit (25), offset (0). Open Response & Test for each call, fill in a test shopId and your access token in the accessToken variable field, and click Test API Call. If you get 401, verify BOTH headers are present — x-api-key AND Authorization.

1{
2  "API Group": "EtsyOpenAPI",
3  "Base URL": "https://openapi.etsy.com/v3",
4  "Group Headers": {
5    "x-api-key":     "YOUR_ETSY_KEYSTRING",
6    "Authorization": "Bearer {{accessToken}}"
7  },
8  "Group Variables": [
9    { "name": "accessToken", "type": "String" }
10  ],
11  "API Calls": [
12    {
13      "Name": "GetMe",
14      "Method": "GET",
15      "Endpoint": "/application/users/me"
16    },
17    {
18      "Name": "GetShopListings",
19      "Method": "GET",
20      "Endpoint": "/application/shops/{{shopId}}/listings/active",
21      "Variables": [
22        { "name": "shopId", "type": "String" },
23        { "name": "limit",  "default": "25" },
24        { "name": "offset", "default": "0" }
25      ]
26    },
27    {
28      "Name": "GetShopReceipts",
29      "Method": "GET",
30      "Endpoint": "/application/shops/{{shopId}}/receipts",
31      "Variables": [
32        { "name": "shopId",   "type": "String" },
33        { "name": "was_paid", "type": "Boolean", "default": "true" },
34        { "name": "limit",    "default": "25" },
35        { "name": "offset",   "default": "0" }
36      ]
37    }
38  ]
39}
40

Create a SellerDashboard page as the home page after OAuth login. Add a bottom navigation bar with two tabs: Listings and Orders. On the Listings tab: add a ListView bound via Backend Query to EtsyOpenAPI → GetShopListings, passing the shopId from App State and the etsyAccessToken from App State as the accessToken variable. Inside the ListView, add a Card with: a 100x100 Image widget (bind to $.results[0].images[0].url_75x75 from the listing JSON), a Text widget for listing title ($.results[0].title), and a Text widget for price ($.results[0].price.amount formatted as currency). Map these JSON Paths in the Response & Test panel of GetShopListings using a real API response. On the Orders/Receipts tab: add a ListView bound to EtsyOpenAPI → GetShopReceipts. Create a Shift4Order-style Data Type for Etsy receipts: receiptId (Integer), buyerEmail (String), grandtotal (Double), status (String), createTimestamp (Integer). Inside the Card show receipt ID, buyer name, total, and a formatted date. Token refresh logic: Add a proactive check before firing any EtsyOpenAPI call. Create an App State variable etsyTokenExpiry (Integer). In the Action Flow before any listing or receipt query, add a condition: if current timestamp > etsyTokenExpiry - 300 (5 minutes before expiry), first call your Cloud Function's /etsyRefreshToken endpoint (via a separate API Group pointing at your Cloud Function), update etsyAccessToken and etsyTokenExpiry in App State, then proceed with the Etsy API call. Etsy's daily request limit (verify current limit at developers.etsy.com) means you should avoid polling or auto-refreshing listing data more than needed. Cache the listing array in App State between sessions using Firestore persistence, and only reload on explicit user pull-to-refresh gesture.