{"openapi":"3.1.0","info":{"title":"Flow-e Connect API","version":"1.0.0","description":"Server-to-server API to connect a store that is not on Shopify (or a large Shopify store) to Flow-e.\n\n**Authentication.** Create an API key in the Flow-e portal (Settings → Developers → Data connection) and send it as\n`Authorization: Bearer fconn_live_…` (or `X-Api-Key`). Keys are shown once, stored only as a hash, and can be limited\nto scopes and IP addresses. Never put a key in a URL or in browser code: the API has no CORS on purpose.\n\n**Request id.** Every response carries `X-Request-Id` and `request_id`. Quote it when you contact support:\nit is the key of the call in your log (`GET /logs?request_id=…`) and in ours.\n\n**Limits.** 60 requests per minute per key (`429 RATE_LIMITED` with `Retry-After`). After 10 requests with a\nmissing or invalid key in a minute, the calling address is blocked for 15 minutes (`429 TOO_MANY_FAILED_ATTEMPTS`).\n\n**Retries.** `retry: \"no\"` → fix the request, do not retry. `retry: \"after\"` → wait `Retry-After` seconds.\n`retry: \"backoff\"` → retry with exponential backoff and jitter (1, 2, 4, 8, 16 s; at most 5 times).\n\n**Versioning.** `v1` is stable: fields are only added, never removed or renamed. Breaking changes get a new\nversion and at least 6 months of notice.\n\n**Batches.** `PUT /products` (up to 250) and `PATCH /inventory` (up to 1,000) never fail as a whole because of\none bad item: every item comes back in `results` with its `index`, `status` and, when rejected, a\n`code`. Both are idempotent: sending the same batch twice writes nothing the second time, so retrying after a\nnetwork error is always safe. Bodies up to 4 MB, `Content-Encoding: gzip` accepted (8 MB decompressed).\n\n**Indexing.** Every valid product is written immediately: catalog, prices, stock and the Flow-e search bar are up\nto date within minutes. Only the semantic indexing (used by the AI assistant) runs at a steady pace, by default\n300 products per hour and 1,500 per hour between 00:00 and 06:00 Europe/Rome per organization: Flow-e schedules\nthe rest itself. Nothing is ever rejected or deferred because of it and you never resend anything: the `indexing`\nobject of each response says how many products entered the queue and when the last one does (`queued_until`).\nPrice, stock and availability changes never enter the queue.\n\n**Large catalogs: imports.** To load or replace a whole catalog (tens of thousands of products), open an import\n(`POST /imports`), upload it in parts of up to 5,000 products as NDJSON or JSON, gzip recommended\n(`PUT /imports/{id}/parts/{n}`, n = 1…40; uploading the same part again replaces it), then commit it\n(`POST /imports/{id}/commit`). Flow-e applies it in the background with the same rules as `PUT /products`\n(about 4,000 products per minute) and `GET /imports/{id}` reports progress. Mode `snapshot` also deactivates the\nAPI products missing from the file; if that would deactivate more than 50 products and 20% of the active ones, the\nimport stops in `needs_confirmation` until you commit again with `confirm_deactivation: true` (the confirmation\ncovers the number shown, +5%; products created after the import was opened are never deactivated). Limits: 300 MB\nof product data per import, 24 imports per organization per day; an import waiting for confirmation expires after 7\ndays. Errors about an existing import (IMPORT_ALREADY_ACTIVE, IMPORT_NOT_OPEN, SNAPSHOT_GUARD, IMPORT_EMPTY) carry\nthe `import` next to `error`; `GET /imports` lists the last 20. `line` in import errors counts non-empty lines.\n\n**Orders.** `POST /orders` reports every order created in a time window. Orders carrying `flowe_sid` (the visit\nid the storefront exposes as `window.__eflow_sid`) become conversions in Flow-e analytics; the others prove the\nwindow was read in full. All or nothing: one invalid order rejects the call. Idempotent: the same order counts once.\n\n### Error codes\n| code | HTTP | retry | meaning |\n|---|---|---|---|\n| `MISSING_KEY` | 401 | no | Send the API key in the Authorization header: Bearer fconn_live_… |\n| `INVALID_KEY` | 401 | no | The API key is not valid. Copy it again from the Flow-e portal (Data connection). |\n| `KEY_REVOKED` | 401 | no | This API key has been revoked. Create a new one in the Flow-e portal. |\n| `KEY_EXPIRED` | 401 | no | This API key has expired. Create a new one in the Flow-e portal. |\n| `ORG_INACTIVE` | 403 | no | The organization linked to this key is not active. |\n| `CONNECT_DISABLED` | 403 | no | Flow-e Connect is not enabled for this organization. Contact Flow-e support. |\n| `IP_NOT_ALLOWED` | 403 | no | Requests with this key are only accepted from the IP addresses set in the portal. |\n| `SCOPE_NOT_GRANTED` | 403 | no | This API key does not have the scope required by this endpoint. |\n| `ORDERS_FROM_SHOPIFY` | 403 | no | This organization's orders are read directly from Shopify: POST /orders is not available for it. |\n| `INVALID_REQUEST` | 400 | no | The request is not valid. Check the parameters against the API reference. |\n| `NOT_FOUND` | 404 | no | The requested resource does not exist for this organization. |\n| `METHOD_NOT_ALLOWED` | 405 | no | Method not allowed on this endpoint. |\n| `PAYLOAD_TOO_LARGE` | 413 | no | The request body is too large. Split it into smaller batches. |\n| `IMPORT_NOT_FOUND` | 404 | no | No import with this id for this organization. |\n| `IMPORT_NOT_OPEN` | 409 | no | The import is not in a state that allows this operation (see import.status in the response). |\n| `IMPORT_ALREADY_ACTIVE` | 409 | no | Another import is already open or running for this organization (see import in the response, or GET /imports): commit it, wait for it to finish or cancel it. |\n| `IMPORT_TOO_LARGE` | 413 | no | An import holds at most 40 parts, 200,000 items and 300 MB of product data. Split the catalog into more imports. |\n| `IMPORT_EMPTY` | 422 | no | The import has no valid items to apply. See GET /imports/{id}/errors. |\n| `SNAPSHOT_GUARD` | 409 | no | This snapshot would deactivate many products (see import.snapshot). If that is intended, commit again with {\"confirm_deactivation\": true}. |\n| `BATCH_IN_PROGRESS` | 409 | after | Another batch for this organization is being written. Send batches one at a time; retry after Retry-After seconds. |\n| `RATE_LIMITED` | 429 | after | Too many requests for this API key. Wait for the number of seconds in Retry-After. |\n| `TOO_MANY_FAILED_ATTEMPTS` | 429 | after | Too many requests with a missing or invalid key from this address. Wait for the number of seconds in Retry-After. |\n| `CONNECT_PAUSED` | 503 | after | Flow-e Connect is temporarily paused. Retry later. |\n| `NOT_CONFIGURED` | 503 | after | Flow-e Connect is not available on this server yet. |\n| `SERVICE_BUSY` | 503 | after | Too many batches are being written right now. Retry after Retry-After seconds. |\n| `SERVICE_UNAVAILABLE` | 503 | backoff | The service is temporarily unavailable. Retry with exponential backoff. |\n| `INTERNAL_ERROR` | 500 | backoff | Unexpected error. Retry with exponential backoff; if it persists, contact support with the request_id. |\n\n### Item codes (in `results[].code` and in import errors)\n| code | meaning |\n|---|---|\n| `INVALID_ID` | Missing or invalid id (products: 1-200 characters; orders: digits only, up to 20). |\n| `DUPLICATE_ID` | The same id appears more than once: in a batch the first one is applied, in an import the last one. |\n| `INVALID_JSON` | This line of the NDJSON part is not a valid JSON object. |\n| `UNKNOWN_FIELD` | Unknown field (see `field`). Only documented fields are accepted. |\n| `INVALID_FIELD` | Invalid value (see `field`). |\n| `INVALID_TYPE` | type must be simple, master or variant. |\n| `MISSING_PARENT` | A variant needs parent_sku (the sku of its master). |\n| `MISSING_NAME` | name is required. |\n| `MISSING_CATEGORY` | category is required for simple and master products. |\n| `INVALID_PRICE` | price is required (except for masters) and must be between 0 and 10,000,000. |\n| `INVALID_URL` | URLs must be https, without credentials, at most 2,048 characters. |\n| `OWNED_BY_SHOPIFY` | This product comes from the Shopify sync and cannot be changed through the API. |\n| `PLAN_LIMIT_REACHED` | The plan's product limit is reached: the product was not created or reactivated. |\n| `NOT_FOUND` | No product with this id in your catalog. |\n| `OUT_OF_WINDOW` | The order was created outside the from/to window of this call. |\n\n### Import codes (in `import.code`)\n| code | meaning |\n|---|---|\n| `PARTIAL_FAILURE` | Completed, but some items were rejected: see GET /imports/{id}/errors. |\n| `SNAPSHOT_GUARD` | Waiting for confirmation: the snapshot would deactivate many products. |\n| `IMPORT_EXPIRED` | Not committed within 24 hours of the last part, or not confirmed within 7 days: closed automatically. |\n| `IMPORT_CANCELLED` | Cancelled with DELETE /imports/{id}. Items already applied stay. |\n| `CONNECT_DISABLED` | Stopped because Flow-e Connect was disabled for the organization. |\n| `INTERNAL_ERROR` | Stopped by an unexpected error. Flow-e is alerted; contact support with the import id. |","contact":{"name":"Flow-e support","email":"team@looma.company"}},"servers":[{"url":"https://portal.flow-e.app/api/connect/v1"}],"security":[{"bearer":[]}],"paths":{"/status":{"get":{"operationId":"getStatus","summary":"Check the API key","description":"Returns the organization and the key in use. The first call to make when you start an integration.","responses":{"200":{"description":"The key works.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Connect disabled, IP not allowed or organization inactive.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable. Retry with backoff.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"put":{"operationId":"upsertProducts","summary":"Create or update products (scope catalog:write)","description":"Up to 250 products per call. The `id` is your product id and the key of the product in Flow-e. A product is fully described by each call (fields left out are stored as empty); use `PATCH /inventory` for partial price and stock updates. Variants link to their master through `parent_sku` = the master's `sku`; a master's price, stock and image are computed from its active variants. Defaults: `sku` = `id`, `currency` = EUR, `sale_price` missing or not lower than `price` = no discount, `stock` missing = always available. HTML in descriptions is converted to text. Products synchronized from Shopify cannot be changed here (`OWNED_BY_SHOPIFY`). To load a whole catalog, an import (`POST /imports`) is simpler: same rules, one upload per 5,000 products.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["products"],"properties":{"products":{"type":"array","minItems":1,"maxItems":250,"items":{"$ref":"#/components/schemas/Product"}}}}}}},"responses":{"200":{"description":"Batch processed (see `outcome` and each result).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"description":"The body is not `{\"products\": [...]}` with 1 to 250 items, or not JSON.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope catalog:write missing, Connect disabled or IP not allowed.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another batch of this organization is being written (BATCH_IN_PROGRESS).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body larger than 4 MB (or 8 MB decompressed).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Busy or temporarily unavailable. See Retry-After.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getProducts","summary":"Read products as Flow-e stores them","description":"Up to 50 ids, to check what a write produced. Includes `source` (api, csv, shopify) and the indexing state.","parameters":[{"name":"id","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"maxItems":50},"style":"form","explode":true},{"name":"ids","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated alternative to `id`."}],"responses":{"200":{"description":"The products found (unknown ids are simply absent).","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/StoredProduct"}},"request_id":{"type":"string"}}}}}},"400":{"description":"No id, or more than 50.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/inventory":{"patch":{"operationId":"updateInventory","summary":"Update prices, stock and availability (scope inventory:write)","description":"Up to 1,000 items. Only the fields present change and they apply immediately. Prices and stock never enter the indexing queue; reactivating a product that was never indexed does, and is scheduled like a new product (see `indexing`). Use `active: false` to hide a product without deleting it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/InventoryItem"}}}}}}},"responses":{"200":{"description":"Batch processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"description":"The body is not `{\"items\": [...]}` with 1 to 1,000 items.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope inventory:write missing.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another batch of this organization is being written.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body too large.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/imports":{"post":{"operationId":"createImport","summary":"Open a bulk import (scope catalog:write)","description":"Opens an import for a whole catalog. One open or running import per organization, at most 24 per day. An import that is not committed within 24 hours of its last part expires.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"mode":{"type":"string","enum":["upsert","snapshot"],"default":"upsert","description":"`upsert`: create or update the products in the file, leave the others as they are. `snapshot`: the file is the whole catalog; at the end the API products missing from it are deactivated (guarded, see SNAPSHOT_GUARD)."}}}}}},"responses":{"201":{"description":"Import open.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"import":{"$ref":"#/components/schemas/Import"},"request_id":{"type":"string"}}}}}},"400":{"description":"Invalid body.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope catalog:write missing.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another import is open or running (IMPORT_ALREADY_ACTIVE); the response carries it in `import`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"More than 24 imports in 24 hours, or too many requests (RATE_LIMITED, see Retry-After).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listImports","summary":"The last 20 imports of the organization","description":"Newest first. Use it to find the id of the active import.","responses":{"200":{"description":"The imports.","content":{"application/json":{"schema":{"type":"object","properties":{"imports":{"type":"array","items":{"$ref":"#/components/schemas/Import"}},"request_id":{"type":"string"}}}}}},"401":{"description":"Missing, invalid, revoked or expired key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/imports/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"operationId":"getImport","summary":"Import status and progress","description":"Poll every 10 to 30 seconds while the import is `queued` or `processing`.","responses":{"200":{"description":"The import.","content":{"application/json":{"schema":{"type":"object","properties":{"import":{"$ref":"#/components/schemas/Import"},"request_id":{"type":"string"}}}}}},"404":{"description":"No import with this id for this organization.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"cancelImport","summary":"Cancel an import (scope catalog:write)","description":"Stops an open, queued, running or waiting import. Products already applied stay as they are.","responses":{"200":{"description":"Cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"import":{"$ref":"#/components/schemas/Import"},"request_id":{"type":"string"}}}}}},"404":{"description":"No import with this id.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The import is already finished (IMPORT_NOT_OPEN), or a processing round is running on it right now (BATCH_IN_PROGRESS: retry after Retry-After).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/imports/{id}/parts/{n}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"n","in":"path","required":true,"schema":{"type":"integer","minimum":1,"maximum":40}}],"put":{"operationId":"uploadImportPart","summary":"Upload one part of an import (scope catalog:write)","description":"Up to 5,000 products, each validated like PUT /products. `application/x-ndjson` (one product per line) or `application/json` `{\"products\": [...]}`; `Content-Encoding: gzip` recommended (4 MB compressed, 40 MB decompressed). Uploading the same part number again REPLACES it, so retrying after a network error is safe. Parts can be uploaded in any order, one at a time.","requestBody":{"required":true,"content":{"application/x-ndjson":{"schema":{"type":"string","description":"One Product JSON object per line."}},"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["products"],"properties":{"products":{"type":"array","minItems":1,"maxItems":5000,"items":{"$ref":"#/components/schemas/Product"}}}}}}},"responses":{"200":{"description":"Part stored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportPartResult"}}}},"400":{"description":"Invalid part number or body.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No import with this id.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The import is not open (already committed, cancelled or expired).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"More than 5,000 products, more than 4 MB compressed / 40 MB decompressed, or more than 200,000 products in the import.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/imports/{id}/commit":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"post":{"operationId":"commitImport","summary":"Commit an import (scope catalog:write)","description":"Closes the parts and queues the import; Flow-e applies it in the background (202). The same id more than once in the file: the LAST occurrence wins. Send `{\"confirm_deactivation\": true}` to allow a snapshot to deactivate many products, upfront or when it is in `needs_confirmation`.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"confirm_deactivation":{"type":"boolean","default":false}}}}}},"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","properties":{"import":{"$ref":"#/components/schemas/Import"},"request_id":{"type":"string"}}}}}},"404":{"description":"No import with this id.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not open (IMPORT_NOT_OPEN) or waiting for confirm_deactivation (SNAPSHOT_GUARD).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"No valid products to apply (IMPORT_EMPTY).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/imports/{id}/errors":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"after","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]{1,2}:[0-9]{1,4}$"},"description":"The `next_after` of the previous page."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100}}],"get":{"operationId":"listImportErrors","summary":"Rejected products of an import","description":"In file order (part, line). Includes the products rejected at upload, the duplicates (all but the last occurrence) and the ones rejected while applying.","responses":{"200":{"description":"One page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportErrors"}}}},"400":{"description":"Invalid after or limit.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No import with this id.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"post":{"operationId":"reportOrders","summary":"Report the orders of a time window (scope orders:write)","description":"Send ALL the orders created between `from` and `to` (at most 31 days, at most 1,000 orders; split longer periods and send the windows OLDEST FIRST, so coverage grows without gaps). Orders with a `flowe_sid` (uuid) are attributed to that Flow-e visit and fully validated: numeric `id` (Magento: `entity_id`), totals and items. Orders without a visit only need `id` and `created_at`: they tell Flow-e the window is complete. A `flowe_sid` that is not a uuid is ignored and counted in `invalid_flowe_sid`. Every `created_at` must fall inside the window. Times are ISO 8601 WITH an offset (`Z` or `+01:00`). Line `product_id`/`variant_id` are matched against your catalog ids; non-numeric ids are used for the match and not stored, so send `sku` too. Nothing is written if any order is invalid (`outcome: rejected`, with the request `index`, `code` and `field` of each). Sending the same window again is safe: an order already recorded is not counted twice. Organizations whose orders are read from Shopify get `403 ORDERS_FROM_SHOPIFY`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["from","to","orders"],"properties":{"from":{"type":"string","format":"date-time","description":"Start of the window (inclusive), ISO 8601 with offset."},"to":{"type":"string","format":"date-time","description":"End of the window, ISO 8601 with offset; not in the future."},"orders":{"type":"array","minItems":0,"maxItems":1000,"items":{"$ref":"#/components/schemas/Order"}}}}}}},"responses":{"200":{"description":"Window recorded (`outcome: ok`) or rejected as a whole (`outcome: rejected`, see `results`).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrdersResult"}}}},"400":{"description":"The body is not `{from, to, orders}`, the window is longer than 31 days or in the future, or more than 1,000 orders.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Scope orders:write missing, Connect disabled, IP not allowed, or orders read from Shopify (ORDERS_FROM_SHOPIFY).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Another order report of this organization is being written (BATCH_IN_PROGRESS).","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Body too large.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable. Retry with backoff.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/logs":{"get":{"operationId":"getLogs","summary":"Read the call log of your organization","description":"The same log shown in the portal: one entry per API call (never the payload, never personal data).","parameters":[{"name":"request_id","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9A-Za-z_-]{8,64}$"},"description":"Return only the entries of this request."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Most recent entries first.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Logs"}}}},"400":{"description":"Invalid parameters.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked or expired key.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Connect disabled, IP not allowed or organization inactive.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited. See Retry-After.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Temporarily unavailable. Retry with backoff.","headers":{"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"fconn_live_ + 38 characters"}},"headers":{"RequestId":{"description":"Identifier of this call (same as `request_id` in the body).","schema":{"type":"string"}}},"schemas":{"Product":{"type":"object","additionalProperties":false,"required":["id","name"],"properties":{"id":{"type":"string","minLength":1,"maxLength":200,"description":"Your product id. Unique in your catalog."},"sku":{"type":["string","null"],"maxLength":200,"description":"Defaults to `id`. Variants point to their master's `sku`."},"type":{"type":"string","enum":["simple","master","variant"],"default":"simple"},"parent_sku":{"type":["string","null"],"maxLength":200,"description":"Required for variants: the master's sku."},"name":{"type":"string","minLength":1,"maxLength":500},"brand":{"type":["string","null"],"maxLength":200},"description":{"type":["string","null"],"maxLength":20000,"description":"Plain text or HTML (converted to text)."},"long_description":{"type":["string","null"],"maxLength":50000},"category":{"type":["string","null"],"maxLength":200,"description":"Required for simple and master products."},"sub_category":{"type":["string","null"],"maxLength":200},"third_category":{"type":["string","null"],"maxLength":200},"tags":{"type":["array","null"],"maxItems":50,"items":{"type":"string","maxLength":100}},"attributes":{"type":["object","null"],"description":"Product attributes, e.g. {\"Material\": [\"Wool\"], \"Gender\": \"Women\"}. Max 50.","additionalProperties":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"variant_attributes":{"type":["object","null"],"description":"Options of a variant, e.g. {\"Color\": \"Red\", \"Size\": \"M\"}. Max 20.","additionalProperties":{"type":"string"}},"image_url":{"type":["string","null"],"format":"uri","pattern":"^https://","maxLength":2048,"description":"Main image. Required in practice for good results."},"images":{"type":["array","null"],"maxItems":20,"items":{"type":"string","pattern":"^https://"}},"url":{"type":["string","null"],"format":"uri","pattern":"^https://","maxLength":2048,"description":"Product page on your store."},"currency":{"type":["string","null"],"pattern":"^[A-Za-z]{3}$","default":"EUR"},"price":{"type":["number","string","null"],"minimum":0,"maximum":10000000,"description":"Full (list) price. Required except for masters."},"sale_price":{"type":["number","string","null"],"minimum":0,"maximum":10000000,"description":"Price actually paid, when lower than `price`."},"stock":{"type":["integer","string","null"],"minimum":0,"description":"Missing = always available."},"stock_status":{"type":["string","null"],"enum":["in_stock","out_of_stock",null]},"active":{"type":["boolean","null"],"default":true},"rating_avg":{"type":["number","null"],"minimum":0,"maximum":5},"rating_count":{"type":["integer","null"],"minimum":0},"translations":{"type":["object","null"],"description":"By language: {\"de\": {\"name\": \"…\", \"description\": \"…\"}}. Max 10 languages.","additionalProperties":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"description":{"type":"string"}}}}}},"InventoryItem":{"type":"object","additionalProperties":false,"required":["id"],"properties":{"id":{"type":"string","minLength":1,"maxLength":200},"price":{"type":["number","string","null"],"minimum":0,"maximum":10000000,"description":"New full price."},"sale_price":{"type":["number","string","null"],"minimum":0,"maximum":10000000,"description":"New sale price; null removes the discount."},"stock":{"type":["integer","string"],"minimum":0,"description":"Sets availability too, unless stock_status is given."},"stock_status":{"type":"string","enum":["in_stock","out_of_stock"]},"active":{"type":"boolean"}}},"Order":{"type":"object","additionalProperties":false,"required":["id","created_at"],"properties":{"id":{"type":["string","integer"],"maxLength":80,"description":"Your order id. Numeric (up to 20 digits) when flowe_sid is set (Magento: entity_id)."},"created_at":{"type":"string","format":"date-time","description":"ISO 8601 with offset, inside the from/to window."},"flowe_sid":{"type":["string","null"],"description":"The Flow-e visit id (uuid) saved on the cart or order (window.__eflow_sid). Other values are ignored and counted."},"name":{"type":["string","null"],"maxLength":80,"description":"Order number shown to the customer, e.g. 000000123."},"total":{"type":["number","string","null"],"minimum":0,"maximum":10000000,"description":"Order total."},"currency":{"type":["string","null"],"pattern":"^[A-Za-z]{3}$"},"items":{"type":["array","null"],"maxItems":200,"items":{"type":"object","additionalProperties":false,"properties":{"product_id":{"type":["string","integer"],"description":"Catalog id of the product (as sent to PUT /products)."},"variant_id":{"type":["string","integer"]},"sku":{"type":["string","null"],"maxLength":200},"quantity":{"type":"integer","minimum":1,"maximum":999999},"amount":{"type":["number","string","null"],"minimum":0,"maximum":10000000,"description":"Line amount."}}}},"test":{"type":"boolean","description":"Test order: recorded but excluded from revenue."},"cancelled":{"type":"boolean"}}},"OrdersResult":{"type":"object","properties":{"outcome":{"type":"string","enum":["ok","rejected"]},"counts":{"type":"object","properties":{"received":{"type":"integer"},"with_flowe_visit":{"type":"integer"},"new":{"type":"integer"},"already_recorded":{"type":"integer"},"invalid_flowe_sid":{"type":"integer"},"rejected":{"type":"integer"}}},"covered_from":{"type":["string","null"],"format":"date-time","description":"Window now known to be complete (ok only)."},"covered_to":{"type":["string","null"],"format":"date-time"},"results":{"type":"array","description":"Only when rejected: the orders to fix.","items":{"type":"object","properties":{"index":{"type":"integer"},"id":{"type":"string"},"status":{"type":"string","const":"rejected"},"code":{"type":"string","enum":["INVALID_ID","DUPLICATE_ID","INVALID_JSON","UNKNOWN_FIELD","INVALID_FIELD","INVALID_TYPE","MISSING_PARENT","MISSING_NAME","MISSING_CATEGORY","INVALID_PRICE","INVALID_URL","OWNED_BY_SHOPIFY","PLAN_LIMIT_REACHED","NOT_FOUND","OUT_OF_WINDOW"]},"field":{"type":"string"},"message":{"type":"string"}}}},"note":{"type":"string"},"request_id":{"type":"string"}}},"BatchResult":{"type":"object","properties":{"outcome":{"type":"string","enum":["ok","partial","rejected"]},"counts":{"type":"object","properties":{"received":{"type":"integer"},"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"rejected":{"type":"integer"}}},"indexing":{"$ref":"#/components/schemas/Indexing"},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Position in your request."},"id":{"type":"string"},"status":{"type":"string","enum":["created","updated","unchanged","rejected"]},"code":{"type":"string","enum":["INVALID_ID","DUPLICATE_ID","INVALID_JSON","UNKNOWN_FIELD","INVALID_FIELD","INVALID_TYPE","MISSING_PARENT","MISSING_NAME","MISSING_CATEGORY","INVALID_PRICE","INVALID_URL","OWNED_BY_SHOPIFY","PLAN_LIMIT_REACHED","NOT_FOUND","OUT_OF_WINDOW"]},"field":{"type":"string"},"message":{"type":"string"}}}},"request_id":{"type":"string"}}},"Indexing":{"type":"object","description":"Semantic indexing of the products written by this call. Nothing to do on your side: Flow-e schedules it.","properties":{"queued":{"type":"integer","description":"Products that entered the indexing queue (new, or changed name/description/category/attributes)."},"scheduled":{"type":"integer","description":"Of these, the ones waiting for their turn because of the hourly pace."},"queued_until":{"type":["string","null"],"format":"date-time","description":"When the last of them enters the queue; indexing usually follows within 30 minutes."}}},"Import":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"mode":{"type":"string","enum":["upsert","snapshot"]},"status":{"type":"string","enum":["open","queued","processing","needs_confirmation","completed","cancelled","failed"]},"code":{"type":["string","null"],"enum":["PARTIAL_FAILURE","SNAPSHOT_GUARD","IMPORT_EXPIRED","IMPORT_CANCELLED","CONNECT_DISABLED","INTERNAL_ERROR",null]},"message":{"type":"string"},"parts":{"type":"integer"},"items":{"type":"object","properties":{"received":{"type":"integer"},"rejected_on_upload":{"type":"integer"},"processed":{"type":"integer"},"to_process":{"type":"integer"}}},"counts":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"rejected":{"type":"integer"},"deactivated":{"type":"integer"}}},"indexing":{"$ref":"#/components/schemas/Indexing"},"snapshot":{"type":["object","null"],"properties":{"to_deactivate":{"type":"integer"},"active":{"type":"integer"},"confirmed":{"type":"boolean"}}},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"Only while open."},"committed_at":{"type":["string","null"],"format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"links":{"type":"object","properties":{"self":{"type":"string"},"parts":{"type":"string"},"commit":{"type":"string"},"errors":{"type":"string"}}}}},"ImportPartResult":{"type":"object","properties":{"part":{"type":"integer"},"received":{"type":"integer"},"accepted":{"type":"integer"},"rejected":{"type":"integer"},"errors":{"type":"array","description":"The first 100 rejected products of this part.","items":{"type":"object","properties":{"line":{"type":"integer","description":"1-based position in the part (blank NDJSON lines are not counted)."},"id":{"type":"string"},"code":{"type":"string","enum":["INVALID_ID","DUPLICATE_ID","INVALID_JSON","UNKNOWN_FIELD","INVALID_FIELD","INVALID_TYPE","MISSING_PARENT","MISSING_NAME","MISSING_CATEGORY","INVALID_PRICE","INVALID_URL","OWNED_BY_SHOPIFY","PLAN_LIMIT_REACHED","NOT_FOUND","OUT_OF_WINDOW"]},"field":{"type":"string"},"message":{"type":"string"}}}},"import":{"$ref":"#/components/schemas/Import"},"request_id":{"type":"string"}}},"ImportErrors":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"part":{"type":"integer"},"line":{"type":"integer"},"id":{"type":"string"},"code":{"type":"string","enum":["INVALID_ID","DUPLICATE_ID","INVALID_JSON","UNKNOWN_FIELD","INVALID_FIELD","INVALID_TYPE","MISSING_PARENT","MISSING_NAME","MISSING_CATEGORY","INVALID_PRICE","INVALID_URL","OWNED_BY_SHOPIFY","PLAN_LIMIT_REACHED","NOT_FOUND","OUT_OF_WINDOW"]},"field":{"type":"string"},"message":{"type":"string"}}}},"next_after":{"type":["string","null"],"description":"Pass it as `after` to get the next page; null when there are no more."},"request_id":{"type":"string"}}},"StoredProduct":{"type":"object","description":"Same fields as Product, plus how Flow-e stores it.","properties":{"source":{"type":"string","enum":["api","csv","shopify"]},"slug":{"type":["string","null"]},"indexing":{"type":"object","properties":{"embedded":{"type":"boolean"},"pending":{"type":"boolean"},"scheduled_for":{"type":"string","format":"date-time","description":"Present while the product waits for its turn in the indexing queue."}}},"updated_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","retry","request_id"],"properties":{"code":{"type":"string","enum":["MISSING_KEY","INVALID_KEY","KEY_REVOKED","KEY_EXPIRED","ORG_INACTIVE","CONNECT_DISABLED","IP_NOT_ALLOWED","SCOPE_NOT_GRANTED","ORDERS_FROM_SHOPIFY","INVALID_REQUEST","NOT_FOUND","METHOD_NOT_ALLOWED","PAYLOAD_TOO_LARGE","IMPORT_NOT_FOUND","IMPORT_NOT_OPEN","IMPORT_ALREADY_ACTIVE","IMPORT_TOO_LARGE","IMPORT_EMPTY","SNAPSHOT_GUARD","BATCH_IN_PROGRESS","RATE_LIMITED","TOO_MANY_FAILED_ATTEMPTS","CONNECT_PAUSED","NOT_CONFIGURED","SERVICE_BUSY","SERVICE_UNAVAILABLE","INTERNAL_ERROR"]},"message":{"type":"string","description":"English by default; Italian with `Accept-Language: it`."},"retry":{"type":"string","enum":["no","after","backoff"]},"request_id":{"type":"string"}}}}},"Status":{"type":"object","properties":{"status":{"type":"string","const":"ok"},"api_version":{"type":"string","const":"v1"},"organization":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"key":{"type":"object","properties":{"prefix":{"type":"string","examples":["fconn_live_Ab12Cd"]},"scopes":{"type":"array","items":{"type":"string","enum":["catalog:write","inventory:write","orders:write"]}},"expires_at":{"type":"string","format":"date-time"}}},"rate_limit":{"type":"object","properties":{"per_minute":{"type":"integer"},"used_last_minute":{"type":"integer"}}},"server_time":{"type":"string","format":"date-time"},"request_id":{"type":"string"}}},"Logs":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string","examples":["status","logs.read","products.upsert","inventory.update","orders.report","imports.part","products.import"]},"outcome":{"type":"string","enum":["ok","partial","rejected","error"]},"code":{"type":["string","null"]},"counts":{"type":["object","null"],"examples":[{"received":250,"created":40,"updated":6,"unchanged":202,"rejected":2,"queued_for_indexing":46,"scheduled_for_indexing":0}]},"errors":{"type":["array","null"],"description":"At most 20 samples.","items":{"type":"object","properties":{"index":{"type":"integer"},"id":{"type":"string"},"code":{"type":"string"}}}},"duration_ms":{"type":["integer","null"]},"key_prefix":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}}},"request_id":{"type":"string"}}}}}}