Connect a shop
You connect shops in Alura, not through the API. In platform.alura.io, open Settings, then Etsy shops, and connect the shop with Etsy. The shop then belongs to that workspace. API keys and AI clients of the workspace that have theworkspace:read scope can read it.
A shop belongs to one workspace at a time. To list the shops a key can read, call GET /v1/workspace/shops, or list_my_shops in an AI assistant:
Response (abridged)
sync block says how its latest full sync went, when the last successful one finished, and next_allowed_at, the earliest time your plan allows another. A time in the past means now.
What a sync is
A sync is one run that copies a connected shop’s data from Etsy into Alura. It runs in steps: shop settings, listings, orders, reviews, finances and customers. Alura starts syncs on its own schedule, the Alura app starts them, Etsy’s order webhooks start smaller ones, and you can start one through the API. Reads never call Etsy. They return what the last sync stored, withas_of saying when that was. A stale_shops notice names any shop whose data is more than 7 days old. See Freshness.
Start a sync
CallPOST /v1/workspace/syncs, or start_my_sync in an AI assistant. Send {"shop_id": "22841907"} for one shop, or no body for every connected shop. The call returns at once with one outcome per shop:
The answer is
202 when at least one shop is queued or already_running. When every shop is refused, the call fails and costs nothing:
503 service_unavailablewhen any shop isunavailable;- otherwise
409 reconnect_requiredwhen every shop needs reconnecting; - otherwise
429 sync_cooldown, withRetry-Afterset to the shortest wait.
shops. A workspace with no connected shop gets 404 not_found. For what an accepted call costs, see API credits.
A sync takes minutes. Starting one doesn’t wait for it. To follow it, read the shop’s sync block again, or call GET /v1/workspace/syncs for the latest sync of each shop and GET /v1/workspace/syncs/{id} for one sync. A sync’s status is queued, running, succeeded, failed or skipped, and steps shows each step. estimated_ready_at is null when Alura can’t estimate it, which for now is always. AI assistants check progress with get_my_shop.
How often you can sync
Per shop, your plan sets the least time between two syncs:
The time counts from the end of the shop’s last completed full sync, whoever started it: Alura’s schedule, the app, a webhook or the API. A sync that ended in
failed counts too, so a failing sync can’t be retried in a loop. A skipped sync doesn’t count.
Per workspace, the API starts at most 4 syncs per connected shop per UTC day. A workspace with 3 shops can start 12 API syncs a day, spread over its shops as you like. Only syncs started through the API count. When the workspace reaches the cap, each refused shop gets cooldown with next_allowed_at at the next UTC midnight, and the response adds a sync_daily_cap_reached notice.
When a shop needs reconnecting
reconnect_required means Alura has no working Etsy authorization for the shop. Either Alura holds no token for it, or Etsy refused the token, for example after the seller removed Alura’s access on Etsy. Alura can’t call Etsy for that shop until it’s reconnected.
- Reads still work. The shop stays in every list, with
connection.status: reconnect_requiredand the data from its last successful sync. Itsas_ofstops moving. - Syncs are refused with the
reconnect_requiredoutcome, and nothing is queued. - To fix it, open
reconnect_url(Alura settings, Etsy shops) and connect the shop with Etsy again. Then start a sync.
Next steps
Coverage
Why a sales number can be null, and when it fills in.
Several shops
How reads cover every shop, and when to pass
shop_id.Limits
What Etsy’s API doesn’t allow.