Reference

API reference

Shop Bridge is the proxy that the Home Assistant Etsy Shop integration uses to reach Etsy. This page documents the protocol so you can understand what the integration does — it's not a guide for building third-party clients.

Use the Home Assistant integration.

This API exists to serve the official integration. If you need direct access to the Etsy API for your own application, register as an Etsy API developer at developers.etsy.com.

Authentication

Signed requests

Every proxy endpoint requires three headers: a Bearer API key, a timestamp, and an HMAC-SHA256 signature.

Header	Value
`Authorization`	`Bearer <api_key>`
`X-HA-Timestamp`	Unix timestamp (seconds). Must be within 5 minutes of server time.
`X-HA-Signature`	Base64-encoded HMAC-SHA256 of the canonical message (below), signed with your HMAC secret.

Canonical message

The signed message format used by the integration:

METHOD|PATH|TIMESTAMP|API_KEY|

Reference

Endpoints

Public

No authentication required.

Method	Path	Returns
GET	`/api/v1/health`	Service health status. Use this to verify the bridge is reachable.

Bearer-only

Requires only the Authorization header (no signature).

Method	Path	Returns
GET	`/api/v1/rate-limit`	Current rate-limit status (`limit`, `remaining`, `reset`).

Signed (proxy)

Requires all three headers. Calls are proxied to Etsy's API; responses are cached briefly to share the daily quota.

Method	Path	Returns
GET	`/api/v1/shops`	The shops linked to your account.
GET	`/api/v1/shops/{shop_id}`	Shop metadata (name, URL, currency, etc.).
GET	`/api/v1/shops/{shop_id}/listings/active`	Active listings for the shop.
GET	`/api/v1/shops/{shop_id}/transactions`	Recent transactions (orders) for the shop.

Reference

Errors

Errors are returned as JSON:

{
  "error": "Error message",
  "status": 400
}

Common codes

Code	Meaning
400	Bad request — invalid parameters.
401	Missing or invalid API key.
403	HMAC signature missing, invalid, or timestamp out of tolerance.
404	Resource not found.
429	Rate limited. Check `X-RateLimit-Reset`.
500	Internal server error.

Permitted use

Shop Bridge issues credentials for use with the official Home Assistant Etsy Shop integration. By using the API you agree to the following:

Credentials are bound to your account and may not be shared, redistributed, or sold.
The API may not be used to build third-party clients, alternative integrations, or competing services.
Automated access for purposes other than the official integration is not permitted.
If you need direct Etsy API access for your own application, register at developers.etsy.com.

Misuse may result in revocation of access. "Etsy" is a trademark of Etsy, Inc. Shop Bridge uses the Etsy API but is not endorsed or certified by Etsy, Inc.