Etsy Merchant Feeds

This is a very simple Laravel app to generate Google Merchant Data Feeds from an Etsy Shop.

Features

• Build simple XML feeds from your Etsy store listings in a format that's compatible with Google Merchant Feeds, for use in Google Shopping Ads, Facebook, Instagram product tagging, etc.
• The product URLs will use your own domain and redirect from there to Etsy. This will allow you to verify your own domain within Instagram, rather than using Etsy's, which is required in order to be able to use product tagging withing Instagram.
• Optionally, supply custom UTM tags for your product URLs, in order to enable tracking in Google Analytics.
• Optionally, supply a custom Google Product Category for your feed.
• You may connect multiple Etsy stores, or the same store multiple times, with different UTM tags.
• You can choose to update feeds on various configurable schedules, or manually.
• You may redirect the homepage to your Etsy store, if desired.

Limitations

• You can only supply one Google Product Category for the entirety of your feed. You cannot (yet) select categories per product.
• Multi-store support is experimental.
• You need to be comfortable hosting a simple PHP app.
• The name is boring, and the logo is ugly 😬

Get your Etsy API key

In order to use this tool, you need an Etsy API key. Etsy can take some time (several days) to approve applications for such a key, so it's recommended to start this right away:

1. Go to etsy.com/developers/register
2. Fill in the required details. As part of this, you'll need to provide a callback URL. This is https://example.com/etsy/callback (Replace example.com with your own domain).
3. Take a note of your KEYSTRING and SHARED SECRET.

Installation

Etsy Merchant Feeds can be run two ways: natively on a server with PHP, or as a container using the prebuilt image and the provided docker-compose.yml. Either way you'll need the Etsy API key above and a domain (or subdomain) pointing at your server.

Running with Docker

A prebuilt image is published to code.thms.uk/michael/etsy-merchant-feed and run via the provided docker-compose.yml. This is the simplest way to host the app: you don't need PHP, a web server, or a copy of the source on the host - only Docker and the compose file. The scheduler runs as its own container, so no cron entry is required.

1. Put docker-compose.yml in a directory on your server and create a .env beside it (copy from .env.example). Set at least:
   • APP_URL=https://example.com
   • ETSY_KEYSTRING={YOUR_KEYSTRING}
   • ETSY_SHARED_SECRET={YOUR_SHARED_SECRET}
   • APP_KEY — generate one and paste it in:

     docker compose run --rm app php artisan key:generate --show
     

2. Start the stack (the init service applies database migrations automatically):

   docker compose pull
   docker compose up -d
   

3. Register a user:

   docker compose exec app php artisan user:register
   

4. The app serves plain HTTP on port 8080. Put it behind a TLS-terminating reverse proxy (nginx, Caddy, a Cloudflare Tunnel, etc.) pointing at the container, then open https://example.com/dashboard, log in, and connect your Etsy store.

The SQLite database and application data persist in the ./data and ./storage directories beside the compose file.

Updating

docker compose pull
docker compose up -d

Running natively

If you prefer to run etsy-merchant-feed natively, you can also do so:

Pre-requisites

• A server running PHP 8.5 with the following extensions installed:
  • php8.5-cli
  • php8.5-common
  • php8.5-fpm
  • php8.5-opcache
  • php8.5-readline
  • php8.5-sqlite3
  • php8.5-xml
• A webserver (e.g. nginx).
• Recommended: Set up HTTPS using Let's Encrypt or similar.
• Some willingness to dive into code.

Steps

1. Clone this repo. The rest of this guide will assume you have cloned this into /var/www/example.com.
2. Change into your directory and copy the .env.example file:

cd /var/www/example.com
cp .env.example .env

3. Open the .env file and adjust these values for your environment. You will need to provide at least the following configuration options (replace https://example.com with your own URL and {YOUR_KEYSTRING} with the KEYSTRING you received from Etsy)
   • APP_URL=https://example.com
   • ETSY_KEYSTRING={YOUR_KEYSTRING}
   • ETSY_SHARED_SECRET={YOUR_SHARED_SECRET}
4. Run the following commands to install all requirements:

composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader
php artisan key:generate --force
php artisan migrate --force
php artisan optimize
npm install
npm run build

5. Run php artisan user:register to register a user.
6. Open your application in the browser at https://example.com/dashboard. Log in and follow the prompts to connect to your Etsy store.
7. Set up your cronjobs by runing crontab -e and adding the following line:

* * * * * cd /var/www/example.com && php artisan schedule:run >> /dev/null 2>&1

Web server configuration

You might want to refer to the Laravel documentation for more information on how to configure your web server.

Updating

Any time you wish to update Etsy Merchant Feeds follow these steps:

1. git pull your clone of the repo.
2. Run the following commands to update everything:

composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader
php artisan migrate --force
php artisan optimize
npm install
npm run build

Building and deploying the image

Pushes to main trigger a Forgejo Actions workflow (.forgejo/workflows/build.yml) that builds the image and pushes it to the registry.