SOURCE_ID: import_from_stripe NAME: Import Stripe Data CATEGORY: First-party Import Stripe billing records — subscriptions, charges, invoices, customers, and more — into Floqer, either as a one-time historical pull or as an ongoing source that re-syncs on a schedule. Imported records become available to your Floqer workflows for enrichment, scoring, churn signals, outreach, and the like. 1. ENDPOINTS Source identifier (used in every endpoint path): `import_from_stripe`. POST /api/v1/sources/import_from_stripe/preview Scope: sources:read Returns a sample page of records (up to 100 total across the selected entities) without creating anything. Use this to validate the entity selection and inspect row shape before committing. POST /api/v1/sources/import_from_stripe Scope: sources:write Creates the source, imports matching records immediately, and — for an active source — keeps re-syncing on a schedule. Returns `source_instance_id` (the new source's UUID). GET /api/v1/sources//data Scope: sources:read Paginated rows imported into the created source. `` is the UUID returned by Create. Query: `page_no` (default 1), `page_size` (default 20, max 200). Source-agnostic; see concepts.txt §10. POST /api/v1/sources//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with the source's current rows. `` here is the UUID returned by Create. Body: { workflow_id, field_mapping, push_existing?, run? } — `field_mapping` keys are `input.` references on the target workflow, values are the source fields to pull. This step is source-agnostic; see concepts.txt §10 for the full shape. PATCH /api/v1/sources//status Scope: sources:write Pause or resume an active source by UUID. Body: {"status": "active" | "paused"}. Pausing stops an active source from picking up new records. Source-agnostic. This source has no dynamic-options endpoint (see §6). Every endpoint first verifies the API-key user has an active Stripe connection. Missing connection → 424. 2. IMPORT TYPE (ONE-TIME VS ONGOING) `import_type` is optional and defaults to "static". Values: "static" One-time import. The source imports matching records once and stops — no recurring schedule. "active" Ongoing source. Imports matching records initially AND keeps picking up new records on the cadence in `frequency` (a cron string) until `expiration_date`. `frequency` is required when `import_type: active` on create. Otherwise it is ignored. 3. BODY SHAPE (PREVIEW + CREATE) Field names are snake_case. Unknown top-level keys are rejected with 400 — the body is strict. Preview accepts: entities required: non-empty array of entity slugs (see §5) start_date ISO date; optional (earliest records to pull) import_type "static" | "active"; optional (defaults to "static") frequency cron string; required when import_type === "active" (create) expiration_date ISO date; optional (active source only) Create accepts all the preview fields plus: name required: display name for the new source 4. FIELD CATALOGUE entities (string[]) — required Non-empty array of Stripe entity slugs to import. See §5 for the full list. You can select more than one (e.g. ["subscription", "charge"]). start_date (string) — optional ISO date. Only records from this date forward are pulled. Omit to pull from the beginning of available history. import_type (string) — optional "static" (one-time) or "active" (ongoing). Defaults to "static". See §2. frequency (string) — required on create when import_type === "active" Cron string for the re-sync cadence (e.g. "0 12 * * *"). expiration_date (string) — optional, active only ISO date after which an active source stops re-syncing. name (string) — required on create only Human-readable display name for the source. 5. ENTITIES `entities` must contain only these slugs: subscription Stripe subscriptions charge Charges paid_invoice Paid invoices failed_invoice Failed invoices customer Customers payment_intent Payment intents refund Refunds dispute Disputes Any other value is rejected with a 400. Each selected entity contributes its own rows; preview caps at 100 rows total across all selected entities. 6. DYNAMIC OPTIONS None. There is no `POST /api/v1/sources/import_from_stripe/options/` endpoint — the only enumerated field, `entities`, has a fixed list (see §5), and the rest are free-form. A Stripe connection is still required for preview and create (424 if missing). 7. HOW TO CONFIGURE END-TO-END Typical flow for an AI agent building a Stripe import source: Step 1 — Preview before committing POST /api/v1/sources/import_from_stripe/preview Body: { "entities": ["subscription", "charge"], "start_date": "2026-01-01" } Check the returned `data[]` row shape and `metadata.total_results`. Iterate the entity selection until you're happy — preview never creates anything. Step 2 — Create the source POST /api/v1/sources/import_from_stripe Body: + the create-only fields: "name": "", "import_type": "static" | "active", "frequency": "0 12 * * *", // only when import_type=active "expiration_date": "2027-01-01" // optional, active only Response: { "status": 201, "data": { "source_instance_id": "", "name", "created_at" }} Step 2b — (Optional) Poll imported rows while the import runs GET /api/v1/sources//data?page_no=1&page_size=20 ( = UUID from Step 2) `total_count` grows until the import finishes. Step 3 — Sync the source into a workflow (so its records flow downstream) POST /api/v1/sources//sync ( = UUID from Step 2 ) First build `field_mapping`: a. GET /api/v1/workflows → pick the destination workflow_id. b. GET /api/v1/workflows//sheets//inputs → each input has a `reference` like `{{input.email}}`. c. Map each workflow input (reference WITHOUT braces) to a source field — the source fields are the keys on the preview `data[]` rows. Body: { "workflow_id": "", "field_mapping": { "input.email": "" }, "push_existing": true, "run": "all" } See concepts.txt §10 for the full sync semantics (source-agnostic). The initial import runs asynchronously — the create call returns as soon as the source is created and the import has started, not when records have finished arriving. 8. KEY NOTES - Stripe connection is mandatory. If the API-key user has no active Stripe connection, preview and create return 424 ("User is not connected to 'stripe'."). Surface this as a "connect Stripe first" CTA. - `entities` is required and must contain only the slugs in §5. Selecting several entities imports rows for each. - `import_type` defaults to "static" (one-time). For an ongoing source set it to "active" and supply `frequency`; pausing via PATCH /status stops it from picking up new records. - Preview caps at 100 rows total across the selected entities. - `start_date` bounds how far back records are pulled. - Credits are consumed when the source is created. If credit consumption fails (e.g. insufficient balance), the source is still created but its import can't start; the API returns 402 so you can top up and retry. 9. WHERE IT FITS UPSTREAM (in Stripe) Subscriptions, charges, invoices, customers, and the other entities live in the user's Stripe account. THIS SOURCE Creates a Stripe import source. On creation it imports matching records; an active source keeps picking up new records on the `frequency` cron until `expiration_date`. DOWNSTREAM (in Floqer) Imported records become available to your Floqer workflows — wire the source into a workflow to enrich accounts, detect churn / payment signals, or trigger outreach. 10. WHEN TO USE - One-time export of Stripe billing data for analysis or enrichment: `import_type: static`. - Keep billing events flowing into a Floqer workflow on a schedule (e.g. failed-payment or churn follow-up): `import_type: active`, `frequency: "0 12 * * *"`. Last updated: 2026-06-02. Reference: https://floqer.com/docs/reference