Etsy API

Go to developers.etsy.com and sign in with your Etsy account. Navigate to 'Your apps' and click 'Create a new app'. Give your app a name and description. Under the Callback URLs section, add the URL where Etsy will redirect users after authorization — in Bubble, this is your app's URL followed by a page route, for example: https://yourapp.bubbleapps.io/etsy-callback. After creating the app, Etsy displays your keystring on the app detail page. Copy the keystring immediately — this value serves double duty: it is your OAuth client_id (used in the authorization URL) and your x-api-key header value (sent on every API request). Note which OAuth scopes you need: for a seller dashboard with listings and orders, you need at minimum listings_r (read listings), transactions_r (read transactions), and shops_r (read shop info). Etsy does not allow requesting scopes you did not declare at app creation — declare all scopes you may need upfront. If your Etsy app will be used commercially by other sellers (not just your own shop), you must apply for elevated API access through Etsy's developer program — the default registration allows access for testing and personal use.

1// Etsy OAuth scopes needed for a seller dashboard
2// Add these as space-separated values in the authorization URL scope parameter
3// listings_r  — read listing data
4// transactions_r — read transaction / receipt data
5// shops_r    — read shop information
6// listings_w  — write (create/update/delete) listings (if needed)
7// transactions_w — update transaction data (mark as shipped, etc.)
8
9// Declare all needed scopes when creating your Etsy app — you cannot add scopes later
10// without going through Etsy's app review process

Open your Bubble app editor and go to Plugins tab → Add plugins. Search for 'API Connector' (published by Bubble) and install it. Open the API Connector configuration and click 'Add another API'. Name the group 'Etsy API' and set the root URL to https://openapi.etsy.com/v3. Now add the two headers that Etsy requires on every call. First header: name it x-api-key, value is your Etsy keystring, and check the 'Private' checkbox — this marks it as a server-side header that Bubble will never send to the browser. Second header: name it Authorization, value is 'Bearer [access_token]' where access_token is a parameter you define (use Bubble's parameter bracket notation). Set access_token as a parameter at the API group level so it can be passed from any call that uses this group. This means the access_token will be dynamically injected per-call from your Bubble database — each user's stored token gets passed as this parameter when you trigger an API call. The authorization header must read exactly: Bearer followed by a space and then the token value. Many 401 errors come from missing the space between 'Bearer' and the token, or from sending the token without the 'Bearer ' prefix.

1// Etsy API Connector Group Configuration
2{
3  "groupName": "Etsy API",
4  "rootURL": "https://openapi.etsy.com/v3",
5  "sharedHeaders": [
6    {
7      "name": "x-api-key",
8      "value": "YOUR_ETSY_KEYSTRING",
9      "private": true
10    },
11    {
12      "name": "Authorization",
13      "value": "Bearer <access_token dynamic>",
14      "private": false
15    },
16    {
17      "name": "Accept",
18      "value": "application/json",
19      "private": false
20    }
21  ],
22  "groupParameters": [
23    {
24      "name": "access_token",
25      "description": "Per-user Etsy access token from Bubble DB"
26    }
27  ]
28}

Etsy v3 requires PKCE OAuth, and Bubble's built-in OAuth connector does not support PKCE. You must build the entire authorization flow manually. PKCE adds a code_verifier (a random string) and code_challenge (SHA-256 hash of the code_verifier, base64url encoded) to the standard OAuth code flow. Since Bubble cannot generate SHA-256 hashes natively, use the Toolbox plugin's 'Run javascript' action in a Backend Workflow to generate the PKCE values. Install the Toolbox plugin from Plugins → Add plugins → search 'Toolbox'. Step 1 — Generate state and PKCE: Create a Backend Workflow named 'Etsy_GeneratePKCE'. Inside it, add a 'Run javascript' action (from Toolbox) that generates a random 43-128 character code_verifier string. Store the code_verifier in a Bubble data type named 'EtsyOAuthSession' with fields: code_verifier (text), state (text), user (User), created_date (date). Step 2 — Build authorization URL: Construct the Etsy authorization URL as a text value in a workflow. The URL format is: https://www.etsy.com/oauth/connect?response_type=code&redirect_uri={YOUR_CALLBACK_URL}&scope={SCOPES}&client_id={KEYSTRING}&state={state}&code_challenge={code_challenge}&code_challenge_method=S256. Step 3 — Redirect user: Use Bubble's 'Go to URL' action to send the user to this authorization URL. They will see Etsy's permission screen and authorize your app. Step 4 — Handle callback: On your Etsy callback page (/etsy-callback), the URL will contain 'code' and 'state' query parameters. Extract them from the page URL. Verify the state matches the stored EtsyOAuthSession. Trigger a Backend Workflow that exchanges the code for tokens.

1// JavaScript for Toolbox 'Run javascript' action — generates PKCE code_verifier and code_challenge
2// Add this in the Toolbox Run javascript action body
3// Output properties: code_verifier (text), code_challenge (text), state (text)
4
5function generateRandomString(length) {
6  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
7  let result = '';
8  const array = new Uint8Array(length);
9  window.crypto.getRandomValues(array);
10  array.forEach(byte => result += chars[byte % chars.length]);
11  return result;
12}
13
14async function generatePKCE() {
15  const code_verifier = generateRandomString(64);
16  const state = generateRandomString(32);
17  const encoder = new TextEncoder();
18  const data = encoder.encode(code_verifier);
19  const digest = await window.crypto.subtle.digest('SHA-256', data);
20  const code_challenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
21    .replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
22  bubble_fn_result({ code_verifier, code_challenge, state });
23}
24
25generatePKCE();

After the user authorizes your Etsy app, Etsy redirects them to your callback URL with a 'code' parameter and the 'state' value. Create a Backend Workflow named 'Etsy_ExchangeCode' that takes the authorization code as an input parameter. This workflow makes a POST call to Etsy's token endpoint: https://api.etsy.com/v3/public/oauth/token. The POST body must include: grant_type=authorization_code, client_id={KEYSTRING}, redirect_uri={YOUR_CALLBACK_URL}, code={authorization_code}, and code_verifier={the stored code_verifier from EtsyOAuthSession}. Set this up as a separate API call in your API Connector — name the group 'Etsy OAuth' with root URL https://api.etsy.com (note: different from the API root https://openapi.etsy.com). The token exchange call does NOT need the x-api-key header — only the form-encoded body parameters. Set the call body as application/x-www-form-urlencoded (not JSON). Etsy returns: access_token (use this for all API calls), refresh_token (save this for renewal), expires_in (seconds — typically 3600). Create a Bubble data type 'EtsyToken' with fields: access_token (text), refresh_token (text), expires_at (date), shop_id (number), user (User). Store all token fields immediately after the exchange. Delete the EtsyOAuthSession record once the exchange succeeds to remove the short-lived code_verifier from your database.

1// Etsy token exchange POST body (application/x-www-form-urlencoded)
2grant_type=authorization_code
3&client_id=YOUR_ETSY_KEYSTRING
4&redirect_uri=https://yourapp.bubbleapps.io/etsy-callback
5&code=AUTHORIZATION_CODE_FROM_REDIRECT
6&code_verifier=THE_STORED_CODE_VERIFIER
7
8// Etsy token exchange response
9{
10  "access_token": "etsy-v3-access-token-value",
11  "token_type": "Bearer",
12  "expires_in": 3600,
13  "refresh_token": "etsy-v3-refresh-token-value"
14}
15
16// Store in Bubble EtsyToken data type:
17// access_token: response.access_token
18// refresh_token: response.refresh_token
19// expires_at: Current date/time + 3600 seconds (add 3600 seconds to now)
20// user: Current User

With authentication working, add API calls to your Etsy API group. Start with the user profile call to confirm both headers work: GET /application/users/me. When initializing this call, use a real access_token value from the EtsyToken record you created in Step 4 — paste it as the access_token parameter during initialization. If initialization succeeds, Bubble detects the user fields. Next, add the active listings call: GET /application/shops/{shopId}/listings/active. The shopId is available from the GET /users/me response (shops array, first item's shop_id field — store it in EtsyToken when you run the initial user lookup). Add parameters: limit (default 25, max 100), offset (for pagination). Initialize with real values. Etsy list responses wrap data in {count, results: [...]} — use results as the data path in Bubble's API Call definition. Add one more call: GET /application/shops/{shopId}/receipts for order management. Use parameters: min_created, max_created (Unix timestamps), status. Now build the seller dashboard page: add a Repeating Group bound to the listings call, passing the current user's shopId and access_token from EtsyToken. Display listing title, price, quantity, and thumbnail image. Add a second section for recent orders bound to the receipts call. Important: Etsy's daily limit is 10,000 requests per app across all your users. A Repeating Group that auto-refreshes on every page load can exhaust this quickly for a popular app — cache listing data in a Bubble data type and refresh it on a schedule or on-demand rather than fetching live for every visitor.

1// Etsy GET /application/users/me response structure (partial)
2{
3  "user_id": 12345678,
4  "primary_email": "seller@example.com",
5  "shops": [
6    {
7      "shop_id": 87654321,
8      "shop_name": "MyEtsyShop"
9    }
10  ]
11}
12
13// Etsy GET /application/shops/{shopId}/listings/active response structure
14{
15  "count": 48,
16  "results": [
17    {
18      "listing_id": 1234567890,
19      "title": "Handmade Ceramic Mug - Ocean Blue",
20      "price": { "amount": 2500, "divisor": 100, "currency_code": "USD" },
21      "quantity": 5,
22      "state": "active",
23      "url": "https://www.etsy.com/listing/1234567890/handmade-ceramic-mug",
24      "images": [
25        { "listing_image_id": 1111, "url_170x135": "https://...", "url_570xN": "https://..." }
26      ]
27    }
28  ]
29}

Etsy access tokens expire after exactly one hour. Any API call made with an expired token returns a 401 error, breaking your app for logged-in users. The solution is a Recurring Backend Workflow that proactively refreshes the token before it expires. Add a new API call to your 'Etsy OAuth' group: POST to https://api.etsy.com/v3/public/oauth/token with grant_type=refresh_token, client_id={KEYSTRING}, refresh_token={stored_refresh_token}. Etsy returns a new access_token and refresh_token pair. Create a Backend Workflow named 'Etsy_RefreshToken' that takes a user as input. It calls the refresh token endpoint with that user's stored refresh_token, then updates the EtsyToken record: set access_token to the new value, set refresh_token to the new value (Etsy rotates refresh tokens), and set expires_at to current time + 3600 seconds. Create a Recurring Backend Workflow (Settings → Backend Workflows → Recurring events in Bubble) that runs every 50 minutes. This workflow searches for all EtsyToken records where expires_at is within the next 10 minutes and calls 'Etsy_RefreshToken' for each one. Alternatively, you can add a token freshness check at the beginning of any workflow that makes an Etsy API call: if the current user's EtsyToken expires_at is within 5 minutes of now, run the refresh before making the API call. Both approaches are valid; the Recurring Backend Workflow is more reliable for apps with many concurrent users. Note: Recurring Backend Workflows require a paid Bubble plan and consume Workload Units — budget for this when planning your Bubble subscription tier. If you have complex questions about building this auth infrastructure for a production Etsy integration, RapidDev's team can help plan the architecture — free scoping call at rapidevelopers.com/contact.

1// Etsy token refresh POST body (application/x-www-form-urlencoded)
2grant_type=refresh_token
3&client_id=YOUR_ETSY_KEYSTRING
4&refresh_token=THE_STORED_REFRESH_TOKEN
5
6// Etsy refresh token response
7{
8  "access_token": "new-etsy-access-token",
9  "token_type": "Bearer",
10  "expires_in": 3600,
11  "refresh_token": "new-etsy-refresh-token"
12}
13
14// IMPORTANT: Etsy rotates refresh tokens on each use.
15// Always save the NEW refresh_token from the response — the old one is invalidated.
16// Update EtsyToken record:
17// access_token = response.access_token
18// refresh_token = response.refresh_token  (NEW value)
19// expires_at = now + 3600 seconds