Skip to content
Pidgely Docs

API reference · Commerce (stores)

Connect a store

POSThttps://api.pidgely.com/commerce/stores
View as Markdown

Starts connecting a store. OAuth and store authorization return redirect_url: send the browser there in the same tab; the platform returns to Pidgely, which attaches the store (a flow finished in another browser, or started by an API key, waits to be claimed in the dashboard). Credentials (VTEX) are checked and return the connected store (201). Admins only on the dashboard.

Authorization: Bearer pdg_…. An API key with full_access. A sending_access key gets 401 restricted_api_key.

Body parameters

JSON object.

Name Type Required Description
platform string Yes One of nuvemshop, shopify, woocommerce, vtex.
fields object (map of string) No Fields the platform asks for (shop, store_url, account, app_key, app_token).

Request

This endpoint is not in the SDKs yet; call it over HTTP.

cURL
curl -X POST 'https://api.pidgely.com/commerce/stores' \
  -H "Authorization: Bearer $PIDGELY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "platform": "nuvemshop"
}'

Response

200 OK

JSON
{
  "redirect_url": "redirect_url",
  "store": {
    "object": "commerce",
    "id": "0199d8a2-6f3c-7c51-9e2a-3b1f0c6d4e21",
    "platform": "nuvemshop",
    "name": "Example",
    "domain": "domain",
    "url": "https://acme.com/webhooks/pidgely",
    "currency": "currency",
    "locale": "locale",
    "status": "pending",
    "status_reason": "status_reason",
    "checkouts_supported": false,
    "sync": {
      "status": "idle",
      "mode": "backfill",
      "resource": "customers",
      "imported": {},
      "error": "error",
      "started_at": "2026-10-12 16:44:41.000000+00",
      "last_synced_at": "2026-10-12 16:44:41.000000+00",
      "next_sync_at": "2026-10-12 16:44:41.000000+00"
    },
    "counts": {
      "customers": 1,
      "products": 1,
      "orders": 1,
      "checkouts": 1
    },
    "email": {
      "from": "Acme <onboarding@acme.com>",
      "reply_to": "reply_to",
      "locale": "locale",
      "effective_locale": "effective_locale"
    },
    "connected_at": "2026-10-12 16:44:41.000000+00",
    "created_at": "2026-10-12 16:44:41.000000+00"
  }
}

Response fields

Name Type Required Description
redirect_url string No Send the browser here (same tab).
store object No —
store.object string Yes Object type. One of store.
store.id string Yes Unique id (UUID). UUID.
store.platform string Yes One of nuvemshop, shopify, woocommerce, vtex.
store.name string Yes Display name.
store.domain string Yes —
store.url string Yes Public https URL that receives the events.
store.currency string Yes —
store.locale string Yes —
store.status string Yes Current status. One of pending, connected, error, disconnected.
store.status_reason string No —
store.checkouts_supported boolean Yes —
store.sync object Yes —
store.sync.status string Yes Current status. One of idle, queued, running, failed.
store.sync.mode string No One of backfill, reconcile, purge.
store.sync.resource string No One of customers, products, orders, checkouts.
store.sync.imported object (map of integer) Yes Records read so far by the current or last sync, per resource.
store.sync.error string No —
store.sync.started_at string | null Yes Format: date-time.
store.sync.last_synced_at string | null Yes Format: date-time.
store.sync.next_sync_at string | null Yes Format: date-time.
store.counts object Yes —
store.counts.customers integer Yes —
store.counts.products integer Yes —
store.counts.orders integer Yes —
store.counts.checkouts integer Yes —
store.email object Yes Email address.
store.email.from string Yes —
store.email.reply_to string Yes Reply-To address or list of addresses.
store.email.locale string Yes —
store.email.effective_locale string Yes —
store.connected_at string | null Yes Format: date-time.
store.created_at string Yes Creation time, YYYY-MM-DD HH:MM:SS.ffffff+00 (UTC). Format: date-time.

Errors

Errors have the shape {"statusCode", "name", "message"}. See Errors for the full list.

Status Name When
401 missing_api_key, restricted_api_key No Authorization: Bearer header, or a sending_access key called an endpoint that needs full_access.
403 invalid_api_key, validation_error The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account).
409 — Conflict (store_connected_elsewhere, store_connecting, store_not_connected)
422 validation_error A field is missing or invalid; message names it.
429 rate_limit_exceeded Too many requests per second. Wait for Retry-After seconds.
502 — The AI service failed or returned an unusable answer (ai_unavailable, ai_busy, ai_timeout, ai_invalid_output)