Connect a store

Connect an e-commerce store to your company.

integration_id names the provider connection the store hangs from, and external_store_id is the identifier the provider gives the shop — unique per provider within your company, so a second store of the same provider and identifier is rejected with store_already_connected.
Auto-invoicing is OFF unless you turn it on: connecting a store never starts issuing invoices by itself.
remote_base_url, if given, is checked against the outbound policy of your company and rejected with store_url_not_allowed when it is not permitted.

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 409 idempotency_key_reused. See the Idempotency guide.

Length1 <= length <= 255

Factuarea-Version?string

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Formatdate

X-Active-Profile?string

Operate on behalf of a child company (gestoría master key): pass its public id (UUID v7) and the request runs against that child's data without changing the key's scope, tier or environment (omit to use the key's own company). Invalid UUID → 400 parameter_invalid_uuid; unknown or non-owned id → 404 profile_not_found. See the Acting on behalf guide.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

integration_id*string

Identifier (UUID v7) of the provider connection that backs the store.

Formatuuid

provider*string

E-commerce provider of the store: woocommerce, shopify or prestashop.

Value in"woocommerce" | "shopify" | "prestashop"

external_store_id*string

Identifier the provider gives to the shop; unique per provider within your company.

Lengthlength <= 191

name*string

Display name of the store, editable at any time.

Lengthlength <= 191

series_id?|

Series (UUID v7, type invoice) the store numbers into; omit to follow the default series of your company.

Formatuuid

simplified_threshold?|

Order total, in euros, up to which the store issues a simplified invoice. Maximum 3000.00.

Range0 <= value <= 3000

require_tax_id?|

Whether the buyer tax ID is required for the order to be invoiced.

prices_include_tax?|

Whether the prices of the store already include taxes.

autoinvoicing_enabled?|

Whether paid orders are invoiced automatically. Off unless you turn it on.

autosend_enabled?|

Whether the invoice is emailed to the buyer automatically. Off unless you turn it on.

remote_base_url?|

Base address of the remote shop, checked against the outbound policy of your company.

Formaturi

Lengthlength <= 2048

environment?|

Environment the store reports as: live invoices for real, test discards with a typed reason.

Value in"live" | "test" | null

authorize_remote_host?|

Authorize the host of remote_base_url as an outbound destination in the same call.

Response Body

`application/json`

Request example

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/stores", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-stores-create"} },  body: JSON.stringify({  "integration_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",  "provider": "woocommerce",  "external_store_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",  "name": "Tienda principal"}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Response example

{
  "data": {
    "id": "0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090",
    "object": "store",
    "integration_id": "0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f71",
    "provider": "woocommerce",
    "external_store_id": "wc-tienda-es",
    "name": "Tienda ES",
    "simplified_threshold": 400,
    "require_tax_id": false,
    "prices_include_tax": true,
    "autoinvoicing_enabled": false,
    "autosend_enabled": false,
    "remote_base_url": "https://tienda.example.com",
    "environment": "test",
    "status": "active",
    "connected_at": "2026-08-29T09:00:00+00:00"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_5227e92bac68846062d5cb7790"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'stores:write'. Tu API key solo tiene los scopes: ninguno.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_9ec194f7b7c4eca54b4b873f56"
  }
}

{
  "error": {
    "type": "conflict_error",
    "code": "resource_conflict",
    "message": "La operación chocó con el estado actual del recurso y no aplica ningún código de conflicto más específico.",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_conflict",
    "request_id": "req_22ee1029847bc887736efd6958"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "El campo integration_id es obligatorio.",
    "param": "integration_id",
    "errors": [
      {
        "param": "integration_id",
        "code": "parameter_missing",
        "message": "El campo integration_id es obligatorio."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_07b10ce71ac4fcb8bd89d6100f"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_fb3f595ae0c04c1f5c89301ac4"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_a9cdf8fa53e72982cb1b3bfb70"
  }
}

Connect a store

Authorization

Headers

Request Body

Response Body

201application/json

401application/json

403application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`