--- title: "Connect a store" method: POST path: "/companies/{company}/stores" tags: ["Stores"] --- # Connect a store `POST /companies/{company}/stores` ## Request - Base URL: `https://api.factuarea.com/v1` - URL: `https://api.factuarea.com/v1/companies/{company}/stores` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` Connects an e-commerce store to the company; auto-invoicing stays OFF until you enable it. - `external_store_id` is unique per provider (`store_already_connected`). - `remote_base_url` must pass the outbound policy (`store_url_not_allowed`). ## Path parameters - `company` string, uuid, required ## Headers - `Idempotency-Key` string - `Factuarea-Version` string, date ## Request body - ConnectStoreV1Request: Public REST API v1 — POST /v1/companies/{company}/stores. Connect an e-commerce store to your company. Required: `integration_id` (the provider connection that backs the store), `provider`, `external_store_id` (the identifier the provider gives to the shop) and `name`. The eight settings are optional and each one falls back to its declared default, so a store connected without any of them is created with automatic invoicing OFF and in the `test` environment. `simplified_threshold` is expressed in EUROS and capped at the legal maximum for a simplified invoice. `series_id` is a series of type invoice; omit it to follow the default series of your company, which is never frozen into the store. A company may connect several stores of the same provider, but not the same remote shop twice. - `integration_id` string, uuid, required: Identifier (UUID v7) of the provider connection that backs the store. - `provider` 'woocommerce' | 'shopify' | 'prestashop', required: E-commerce provider of the store: `woocommerce`, `shopify` or `prestashop`. - `external_store_id` string, required: Identifier the provider gives to the shop; unique per provider within your company. - `name` string, required: Display name of the store, editable at any time. - `series_id` string, uuid, nullable: Series (UUID v7, type invoice) the store numbers into; omit to follow the default series of your company. - `simplified_threshold` number, nullable: Order total, in euros, up to which the store issues a simplified invoice. Maximum 3000.00. - `require_tax_id` boolean, nullable: Whether the buyer tax ID is required for the order to be invoiced. - `prices_include_tax` boolean, nullable: Whether the prices of the store already include taxes. - `autoinvoicing_enabled` boolean, nullable: Whether paid orders are invoiced automatically. Off unless you turn it on. - `autosend_enabled` boolean, nullable: Whether the invoice is emailed to the buyer automatically. Off unless you turn it on. - `remote_base_url` string, uri, nullable: Base address of the remote shop, checked against the outbound policy of your company. - `environment` 'live' | 'test' | 'null', nullable: Environment the store reports as: `live` invoices for real, `test` discards with a typed reason. - `authorize_remote_host` boolean, nullable: Authorize the host of `remote_base_url` as an outbound destination in the same call. ## Response `201` Online store connected. The `Location` header contains the canonical URL of the new store connection. - object - `data` Store, required: A connected e-commerce store of your company. The public `id` is the store UUID v7. `integration_id` is the UUID of the provider connection that backs it, and `external_store_id` is the identifier the provider gives to the shop — an opaque string, not a foreign key of ours. The settings decide how the orders of the store become invoices. - `id` string, uuid, required: UUID v7 of the store. Public identity (KEY `id`). - `object` 'store', required: Stripe-like discriminator. Always `store` for this resource. - `integration_id` string, uuid, required: UUID of the provider connection (integration) that backs the store. Several stores of the same provider may hang from one connection. - `provider` 'woocommerce' | 'shopify' | 'prestashop', required: E-commerce provider of the store. - `external_store_id` string, required: Identifier the provider gives to the shop. Unique per provider within your company; an opaque string, NOT a foreign key of ours. - `name` string, required: Editable display name of the store. - `simplified_threshold` string, required: Order total, in EUROS, up to which the store issues a simplified invoice (F2). Capped at 3000.00, the legal maximum. Defaults to 400.00, the general legal limit. - `require_tax_id` boolean, required: Whether the buyer tax ID is required for an order to be invoiced. Defaults to `false`: a retail store sells to consumers who do not provide one. - `prices_include_tax` boolean, required: Whether the prices of the store already include taxes. Defaults to `true`, which is how Spanish retail displays prices. - `autoinvoicing_enabled` boolean, required: Whether paid orders are invoiced automatically. Defaults to `false`: a freshly connected store does not invoice on its own until you turn it on. - `autosend_enabled` boolean, required: Whether the invoice is emailed to the buyer automatically. Defaults to `false`. - `remote_base_url` string, nullable, required: Base address of the remote shop, or `null` when none is declared. Credentials embedded in the address are removed before it is returned. - `environment` 'live' | 'test', required: Environment the store reports as. `live` invoices for real; `test` discards its events with a typed reason. Defaults to `test`. - `status` 'active' | 'disconnected', required: Store status. `active` while connected; `disconnected` after disconnecting. - `connected_at` string, date-time, nullable, required: When the store was connected (ISO 8601), or `null` if unknown. - `invoice_note` string, nullable, required: Optional note written in the notes of the invoices auto-created from this store's orders, or `null` when none is configured (the default: invoices carry no note). When an order needed a currency conversion to EUR, the conversion trace is appended to the note. Editable with `PATCH /v1/companies/{company}/stores/{store}`; `null` or an empty string clears it. ## Other responses - `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version. - `401`: Missing or invalid API key. - `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). - `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test). - `422`: Validation failed. The `error.param` field identifies which input is invalid. - `429`: Rate limit exceeded. Retry after the duration in `Retry-After`. - `500`: Unexpected server error. --- [API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)