Ecommerce stores
Connect stores, configure order invoicing and diagnose orders and refunds through REST and MCP.
Authorize the provider connection in Factuarea first. integration_id identifies that existing connection; external_store_id is the provider’s opaque shop identifier. A store is scoped to the company authenticated by your API key.
Operations and scopes
| Operation | Required scope | MCP tool |
|---|---|---|
GET /v1/stores | stores:read | list_stores |
POST /v1/stores | stores:write | connect_store |
GET /v1/stores/{store} | stores:read | get_store |
PUT /v1/stores/{store} | stores:write | update_store |
DELETE /v1/stores/{store} | stores:write | disconnect_store |
POST /v1/woocommerce/stores/{store}/connection-test | woocommerce_store:write | test_woocommerce_store_connection |
POST /v1/shopify/stores/{store}/connection-test | shopify_store:write | test_shopify_store_connection |
These tools are API-key-only. REST operations that declare Idempotency-Key require it; use the same key when retrying the same intent. In MCP, pass idempotency_key when the tool requires it. The listing accepts limit from 1 to 100 (default 25), starting_after and ending_before; do not combine both cursors.
curl -X POST https://api.factuarea.com/v1/stores \
-H "Authorization: Bearer $FACTUAREA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: connect-tienda-es-2026-09" \
--data '{
"integration_id": "0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f71",
"provider": "woocommerce",
"external_store_id": "wc-tienda-es",
"name": "Tienda ES",
"remote_base_url": "https://tienda.example.com",
"environment": "test",
"autoinvoicing_enabled": false,
"autosend_enabled": false
}'Review settings before activation
New stores default to environment: test, autoinvoicing_enabled: false and autosend_enabled: false. prices_include_tax defaults to true, require_tax_id to false, and simplified_threshold to 400 EUR. The API allows a threshold up to 3000; select the threshold appropriate to your activity. Changing a store to live does not change the environment of a fact_test_ credential.
Paid orders can produce invoices; refunds can produce corrective invoices linked to the original. Identification, tax rates, supported order state and the configured invoice threshold still apply. Foreign-currency orders need conversion to EUR and an available exchange rate. Unsupported tax or identity cases appear as typed discard reasons instead of a fabricated invoice.
Diagnose the result
Connection tests can return HTTP 200 with credential_accepted: false. Inspect reachable, failure_code, api_version and checked_at. A missing store returns 404; a successful HTTP request alone does not prove that the remote credentials work.
Use the integration inbox for discarded orders and replay only when is_replayable is true, after correcting the cause. Subscribe to order.invoiced and order.refunded for the resulting snapshots under data.object; use correlation_id to connect related events. Invoice channel and source_store_id preserve the origin. Configured Slack/Teams notifications are a separate destination from your public webhooks. Disconnecting a store stops its connection; it does not erase its invoices or historical events.