{"openapi":"3.1.0","info":{"title":"Flowzio API","version":"1.0.0","summary":"Send what happens in your store to Flowzio: signups, carts, orders, refunds and your product catalog.","description":"One address per job, one key in the x-api-key header, JSON in and out. Keys are created in Settings > API keys and shown once; they start with flz_. Every request is scoped to the key's brand. Full guide: https://docs.flowzio.ai/tracking-api","contact":{"name":"Flowzio support","email":"support@flowzio.ai","url":"https://flowzio.ai/support"},"termsOfService":"https://flowzio.ai/terms-of-service"},"externalDocs":{"description":"Developer documentation","url":"https://docs.flowzio.ai/developers"},"servers":[{"url":"https://flowzio.ai"}],"security":[{"apiKey":[]}],"tags":[{"name":"Events","description":"What a person did: the input to contacts, revenue and flows."},{"name":"Catalog","description":"The store's products, so emails can show real items."},{"name":"MCP","description":"The Model Context Protocol server, for AI assistants."}],"paths":{"/api/mcp":{"post":{"tags":["MCP"],"operationId":"mcp","summary":"MCP server (JSON-RPC)","description":"Flowzio's Model Context Protocol server, Streamable HTTP transport, stateless. Send one JSON-RPC 2.0 message per request with an API key or an OAuth access token as Authorization: Bearer (or the key as x-api-key); without one the 401 names the OAuth metadata. Methods: initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get. Reads need the key's read scope, changes its manage scope, store events its events:write scope. Guide: https://docs.flowzio.ai/mcp","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"A JSON-RPC 2.0 request","properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string","example":"tools/list"},"params":{"type":"object"}},"required":["jsonrpc","method"]}}}},"responses":{"200":{"description":"The JSON-RPC response","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"id":{},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"202":{"description":"A notification: nothing to answer"},"400":{"description":"The body is not JSON-RPC","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The key is missing, invalid or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests; wait Retry-After seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/track":{"get":{"tags":["Events"],"operationId":"checkApiKey","summary":"Check a key","description":"Check your API key and brand without changing data.","responses":{"200":{"description":"The key is valid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyCheck"}}}},"401":{"description":"The header is missing, or the key is invalid or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the events:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over 3000 calls a minute for this key, or too many invalid keys from this address. Wait the Retry-After seconds, then send again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Events"],"operationId":"trackEvents","summary":"Send one event, or up to 100","description":"An event is what a person did, with their email. Flowzio turns events into contacts, revenue reports and flows (abandoned checkout, post-purchase).\n\nFlows can start on these types: subscribed, form_submit, lead_captured, quote_requested, appointment_booked, appointment_completed, appointment_cancelled, job_completed, viewed_product, added_to_cart, started_checkout, abandoned_checkout, placed_order, fulfilled_order, cancelled_order, refunded, coupon_used. Any other type is accepted and recorded on the contact's timeline, and starts nothing.\n\nplaced_order with an orderId is idempotent: redelivering it never creates a second order or counts revenue twice. refunded with a refundId is a no-op the second time. fulfilled_order and cancelled_order are recorded once per orderId.\n\nContact facts in data (firstName, lastName, phone, city, state, country, birthday) fill empty fields on the contact and never overwrite a value already set.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Event"},{"$ref":"#/components/schemas/EventBatch"}]},"examples":{"order":{"summary":"An order","value":{"type":"placed_order","email":"jane@example.com","data":{"orderId":"1001","total":64,"items":[{"externalProductId":"sku-42","name":"Trail runner","quantity":2,"price":32,"imageUrl":"https://shop.example/img/42.jpg","url":"https://shop.example/p/42"}]}}},"checkout":{"summary":"A checkout, with the link the recovery email uses","value":{"type":"started_checkout","email":"jane@example.com","data":{"total":64,"checkoutUrl":"https://shop.example/checkout/abc","items":[{"externalProductId":"sku-42","name":"Trail runner","quantity":2,"price":32}]}}},"signup":{"summary":"An opt-in","value":{"type":"subscribed","email":"jane@example.com","data":{"firstName":"Jane","marketingConsent":"subscribed"}}},"batch":{"summary":"Several at once","value":{"events":[{"type":"viewed_product","email":"jane@example.com","data":{"externalProductId":"sku-42"}},{"type":"added_to_cart","email":"jane@example.com","data":{"total":32}}]}}}}}},"responses":{"200":{"description":"Recorded. A batch answers per event, in order, so a failed slot can be retried on its own.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EventResult"},{"$ref":"#/components/schemas/BatchResult"}]}}}},"400":{"description":"A field is missing or malformed; the message names it","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The header is missing, or the key is invalid or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the events:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"data is over 64 KB, or the body is over 8 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over 3000 calls a minute for this key, or too many invalid keys from this address. Wait the Retry-After seconds, then send again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/catalog":{"post":{"tags":["Catalog"],"operationId":"upsertProducts","summary":"Send products, up to 250","description":"Create or update products by externalId. Omitted fields stay unchanged. Replaying a batch refreshes existing products. Order items also create products automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductBatch"},"example":{"products":[{"externalId":"sku-42","name":"Trail runner","price":32,"imageUrl":"https://shop.example/img/42.jpg","url":"https://shop.example/p/42","category":"Shoes"}]}}}},"responses":{"200":{"description":"Done","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogResult"}}}},"400":{"description":"products is missing, empty or over 250 items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The header is missing, or the key is invalid or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the events:write scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 4 MB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Over 3000 calls a minute for this key, or too many invalid keys from this address. Wait the Retry-After seconds, then send again.","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Get a brand key (flz_) from Settings > API keys. Keep it server-side."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What went wrong, in words"}}},"KeyCheck":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"brand":{"type":["string","null"],"description":"The brand the key belongs to"},"scopes":{"type":"string","description":"Comma-separated scopes","example":"events:write"},"key":{"type":"object","properties":{"name":{"type":"string"},"prefix":{"type":"string"},"expiresAt":{"type":["string","null"],"format":"date-time"}}}}},"Event":{"type":"object","required":["type"],"anyOf":[{"required":["email"]},{"required":["ref"]}],"properties":{"type":{"type":"string","maxLength":64,"description":"What happened. Flows start on: subscribed, form_submit, lead_captured, quote_requested, appointment_booked, appointment_completed, appointment_cancelled, job_completed, viewed_product, added_to_cart, started_checkout, abandoned_checkout, placed_order, fulfilled_order, cancelled_order, refunded, coupon_used. Any other value is recorded and starts nothing.","examples":["subscribed","form_submit","lead_captured","quote_requested","appointment_booked","appointment_completed","appointment_cancelled","job_completed","viewed_product","added_to_cart","started_checkout","abandoned_checkout","placed_order","fulfilled_order","cancelled_order","refunded","coupon_used"]},"email":{"type":"string","format":"email","description":"Whose it is. Placeholder and disposable addresses are refused. A viewed_product for an address that is not a contact yet is answered but not recorded."},"ref":{"type":"string","description":"Instead of email: the fz_ref a click in a Flowzio email adds to links to the brand's site. Names an existing contact of this brand only."},"data":{"$ref":"#/components/schemas/EventData"},"occurredAt":{"type":"string","format":"date-time","description":"When it happened. Defaults to now. Not in the future."},"historical":{"type":"boolean","default":false,"description":"True when importing old data: dated when it happened, attributed to no email, and no flow starts."}}},"EventBatch":{"type":"object","required":["events"],"properties":{"events":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/Event"}}}},"EventData":{"type":"object","description":"Details of the event. Up to 64 KB. Any key is kept; these are the ones Flowzio reads.","properties":{"orderId":{"type":"string","description":"Your order id. Makes placed_order idempotent, lets refunded find the order, and keeps fulfilled_order and cancelled_order to one per order."},"refundId":{"type":"string","description":"Your refund id. Makes a redelivered refund a no-op."},"total":{"type":"number","description":"Order, cart or refund amount. On refunded, omit for a full refund."},"couponCode":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri","description":"The link an abandoned checkout email sends people back to."},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"externalProductId":{"type":"string","description":"Your product id, on viewed_product."},"marketingConsent":{"type":"string","enum":["subscribed","unsubscribed"],"description":"An explicit opt-in or opt-out. Leave out when no box was ticked."},"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"city":{"type":"string"},"state":{"type":"string"},"country":{"type":"string"},"birthday":{"type":"string","description":"1990-03-14, 14 March 1990, or 03/14/1990 with dayFirst for DD/MM."},"dayFirst":{"type":"boolean"}},"additionalProperties":true},"Item":{"type":"object","required":["name","quantity","price"],"properties":{"externalProductId":{"type":"string","description":"Your product id. The product is found or created by it."},"productId":{"type":"string","description":"A Flowzio product id, if you have one. Unknown ids are dropped, never an error."},"name":{"type":"string"},"quantity":{"type":"integer","minimum":1},"price":{"type":"number","description":"Unit price"},"imageUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"}}},"EventResult":{"type":"object","required":["ok","contactId"],"properties":{"ok":{"type":"boolean","const":true},"contactId":{"type":"string","description":"The contact the event landed on"},"orderId":{"type":"string","description":"Flowzio's id for the order, on placed_order"},"duplicate":{"type":"boolean","description":"True when this order or refund was already recorded; nothing changed"}}},"BatchResult":{"type":"object","required":["ok","accepted","failed","results"],"properties":{"ok":{"type":"boolean","description":"True when every event landed"},"accepted":{"type":"integer"},"failed":{"type":"integer"},"results":{"type":"array","description":"One result per event, in order. Retry failed events individually.","items":{"oneOf":[{"allOf":[{"$ref":"#/components/schemas/EventResult"},{"type":"object","properties":{"status":{"type":"integer","const":200}}}]},{"type":"object","required":["ok","status","error"],"properties":{"ok":{"type":"boolean","const":false},"status":{"type":"integer","examples":[400,413,500]},"error":{"type":"string"}}}]}}}},"ProductBatch":{"type":"object","required":["products"],"properties":{"products":{"type":"array","minItems":1,"maxItems":250,"items":{"$ref":"#/components/schemas/Product"}}}},"Product":{"type":"object","required":["externalId","name"],"properties":{"externalId":{"type":"string","maxLength":120,"description":"Your product id"},"name":{"type":"string","maxLength":200},"price":{"type":"number"},"imageUrl":{"type":"string","format":"uri"},"url":{"type":"string","format":"uri"},"category":{"type":"string","maxLength":120},"description":{"type":"string","maxLength":2000}}},"CatalogResult":{"type":"object","properties":{"ok":{"type":"boolean"},"upserted":{"type":"integer"},"skipped":{"type":"integer","description":"Items without an externalId or name"}}}}}}