Connectors

Stripe

Manage Stripe customers, payment intents, subscriptions, checkout sessions, refunds, payouts, invoices, disputes, products, prices, and shipping rates. Covers auth, the smallest-unit amount convention, cursor pagination, and response access paths.

On this page

Connecting Stripe Field conventions Reading the response Customers Payment Intents Subscriptions Checkout Sessions Refunds Payouts Invoices Disputes Products Prices Shipping Rates Not covered Step Name Step Reference Execution Settings Caching Locking

Connecting Stripe

Every action needs a Stripe connection configured as a Bearer-token connection holding your Stripe Secret Key (sk_live_... or sk_test_..., from the Stripe dashboard's Developers → API keys). The connector calls Stripe through the official Stripe SDK pinned to API version 2025-08-27.basil.

Field conventions

Amounts are in the smallest currency unit — cents for USD/EUR, so 1000 = $10.00. This applies to every amount / unitAmount field.
Currency is a lowercase ISO code (usd, eur, gbp).
JSON string fields — metadata, address, items, lineItems, evidence, recurring, fixedAmount, deliveryEstimate are typed as JSON text (e.g. metadata = {"order_id":"1234"}). Invalid JSON fails the step before any API call.
Stripe timestamps (created, current_period_end, …) are Unix seconds.

Reading the response

Every action's result is at {{<stepReference>.response...}} (see Step Reference): {{<stepReference>.response.status}}, {{<stepReference>.response.statusText}}, {{<stepReference>.response.headers.<name>}}, and {{<stepReference>.response.data...}} for the body.

A single object (create / retrieve / update) — the Stripe object's fields are directly under data. A "Retrieve Customer" step (reference retrieveCustomer) resolves the email at {{retrieveCustomer.response.data.email}} and the id at {{retrieveCustomer.response.data.id}}.
A list (every "List …" action) — {{<stepReference>.response.data.items}} is the array and {{<stepReference>.response.data.hasMore}} says whether more pages exist. Page forward by setting Starting After to the id of the last item from the previous page (Ending Before pages backward). Limit is 1–100 (default 10).
A delete — {{<stepReference>.response.data.deleted}} is true and {{<stepReference>.response.data.id}} echoes the id.

A non-2xx response does not fail the step — it's returned with the real status code and Stripe's error object under {{<stepReference>.response.data}} (type, code, message, param, decline_code), so you can branch on {{<stepReference>.response.status}}.

Customers

Create Customer — no required fields; Email, Name, Phone, Description, Metadata (JSON), Address (JSON: line1, line2, city, state, postal_code, country).
Retrieve Customer / Update Customer / Delete Customer — Customer ID (cus_...) required. Update takes the same optional fields as Create.
List Customers — filter by Email; Limit, Starting After, Ending Before.

Response fields: id, email, name, balance, currency, delinquent, invoice_prefix, tax_exempt, address, shipping, metadata.

Payment Intents

Create Payment Intent — Amount and Currency required; optional Customer, Payment Method (pm_...), Description, Metadata (JSON), Confirm (attempt payment immediately), Return URL.
Retrieve Payment Intent / Confirm Payment Intent / Cancel Payment Intent — Payment Intent ID (pi_...) required. Confirm optionally takes Payment Method and Return URL.

Response fields: id, amount, amount_received, currency, status (requires_payment_method, requires_confirmation, requires_action, processing, succeeded, canceled), client_secret, payment_method, customer, cancellation_reason.

Subscriptions

Create Subscription — Customer and Items (JSON array of { "price": "price_..." }, optionally quantity) required; optional Metadata (JSON), Trial Period Days, Payment Behavior, Collection Method.
Retrieve Subscription — Subscription ID (sub_...).
Update Subscription — Subscription ID required; optional Items (JSON), Metadata, Cancel At Period End, Proration Behavior.
Cancel Subscription — Subscription ID required; Cancel At Period End = true schedules cancellation at the end of the period (the handler updates the subscription with cancel_at_period_end), otherwise it cancels immediately.
List Subscriptions — filter by Customer, Status; Limit, Starting After, Ending Before.

Response fields: id, customer, status (trialing, active, past_due, canceled, unpaid), current_period_start, current_period_end, cancel_at_period_end, canceled_at, currency.

Checkout Sessions

Create Checkout Session — Line Items (JSON array — { "price": "price_...", "quantity": 1 } or inline price_data), Mode (payment, subscription, setup), Success URL, Cancel URL all required; optional Customer, Customer Email, Metadata (JSON), Payment Method Types (JSON array), Allow Promotion Codes.
Retrieve Checkout Session — Session ID (cs_...).

Response fields: id, url (send the shopper here), mode, status, payment_intent, customer, amount_total, currency.

Refunds

Create Refund — provide Charge (ch_...) or Payment Intent (pi_...); optional Amount (partial refund; omit for full), Reason (duplicate, fraudulent, requested_by_customer), Metadata (JSON).
Retrieve Refund — Refund ID (re_...).
List Refunds — filter by Charge or Payment Intent; Limit, Starting After, Ending Before.

Response fields: id, amount, currency, charge, payment_intent, reason, status (pending, succeeded, failed, canceled).

Payouts

Create Payout — Amount and Currency required; optional Destination (bank account / card id), Description, Metadata (JSON), Method (standard, instant).
Retrieve Payout / Cancel Payout — Payout ID (po_...).
List Payouts — filter by Status; Limit, Starting After, Ending Before.

Response fields: id, amount, currency, arrival_date, status (paid, pending, in_transit, canceled, failed), type, description.

Invoices

Create Invoice — Customer required; optional Auto Advance, Collection Method (charge_automatically, send_invoice), Description, Metadata (JSON), Subscription.
Retrieve Invoice — Invoice ID (in_...).
Finalize Invoice — Invoice ID required; optional Auto Advance. Moves a draft invoice to open.
Pay Invoice — Invoice ID required; optional Source or Payment Method.
List Invoices — filter by Customer, Status; Limit, Starting After, Ending Before.

Response fields: id, customer, status (draft, open, paid, void, uncollectible), amount_due, amount_paid, amount_remaining, currency, number, subscription.

Disputes

Retrieve Dispute — Dispute ID (dp_...).
Update Dispute — Dispute ID required; Evidence (JSON object of evidence fields), Metadata (JSON), Submit (true submits the evidence to the bank).
List Disputes — filter by Charge; Limit, Starting After, Ending Before.

Response fields: id, amount, charge, currency, status (warning_needs_response, needs_response, under_review, won, lost), reason.

Products

Create Product — Name required; optional Description, Active, Unit Label, URL, Images (JSON array of URLs), Metadata (JSON).
Retrieve Product / Update Product / Delete Product — Product ID (prod_...) required.
List Products — filter by Active; Limit, Starting After, Ending Before.

Prices

Create Price — Currency and Product required; Unit Amount (integer, smallest unit) or Unit Amount Decimal; optional Recurring (JSON: { "interval": "month" }), Billing Scheme, Nickname, Active, Metadata (JSON).
Retrieve Price / Update Price — Price ID (price_...). Update takes Active, Nickname, Metadata.
List Prices — filter by Product, Active, Currency, Type (one_time, recurring); Limit, Starting After, Ending Before.

Shipping Rates

Create Shipping Rate — Display Name required; optional Type (fixed_amount), Fixed Amount (JSON: { "amount": 500, "currency": "usd" }), Delivery Estimate (JSON), Tax Behavior, Tax Code, Metadata (JSON).
Retrieve Shipping Rate / Update Shipping Rate — Shipping Rate ID (shr_...). Update takes Active, Metadata.
List Shipping Rates — filter by Active, Currency; Limit, Starting After, Ending Before.

Not covered

There is no generic-request action on this connector. For Stripe resources without a dedicated action (Charges, Payment Methods, Setup Intents, Events, Balance, Transfers, Connect, Webhooks, …), use the HTTP Connector against https://api.stripe.com/v1/... with the connection's secret key as a Bearer token and a Content-Type: application/x-www-form-urlencoded body.

Also applies here

Step Name

What it's for

Every step in a workflow gets a name — either one you set or a default based on the connector and action (e.g. "Get Order Details", "Send Welcome Email"). It's shown throughout the UI and in your execution history, and it's also the source for the step's Reference — a camelCase identifier auto-generated from the name (e.g. "Get Order Details" → getOrderDetails) — which is what you actually use in {{...}} expressions to read this step's output from later steps. See Step Reference.

Rules

Must be at least 2 characters, and 50 characters or fewer.
Must be unique within the workflow — reusing a name that's already taken will be rejected, with a suggested alternative (e.g. "Get Order Details 2").
Can't be empty.

Tips

Prefer a descriptive, human-readable name over a generic one — "Get Order Details" is easier to work with later than "HTTP Request 2", especially once a workflow has a dozen steps.
Renaming a step updates every reference to it elsewhere in the workflow automatically.

Step Reference

Syntax

Any input field can reference earlier data using {{expression}}. The expression is evaluated as JSONata — so simple dot-paths and more advanced queries (filters, functions) both work.

Referencing a step's output

Use the step's Reference — a camelCase identifier auto-generated from its Name (e.g. "Get Order Details" → getOrderDetails), shown read-only wherever the step's fields are configured — followed by the field path. Elsewhere in these docs this general pattern is written as {{<stepReference>.field.path}}:

{{getOrderDetails.response.data.id}}
{{getOrderDetails.response.status}}

The raw display name won't work here even though it's what you see in the UI — {{Get Order Details.response.data.id}} isn't valid, since a bare name containing spaces isn't a single JSONata identifier. Always use the camelCase Reference.

You can also reference steps by position instead of by reference:

{{steps[0].response.data.id}}

Referencing trigger data

{{trigger.headers.authorization}}
{{trigger.body.customerId}}
{{trigger.query.page}}
{{trigger.params.orderId}}
{{trigger.method}}
{{trigger.path}}

Referencing workflow variables

{{variables.myVariable}}

See Variables for the full list of variable types and more examples, including connection-type variables.

Referencing runtime variables

A separate, mutable namespace written by the Variable connector while a run is in progress — not the same as the workflow-level variables above:

{{runtimeVariables.myVariable}}

Notes

If an expression can't be resolved (a typo in a step name, a field that doesn't exist), it resolves to an empty string rather than failing the workflow — check your execution history if a value comes through blank.
Object values are automatically JSON-stringified when interpolated into a string field.

Execution Settings

Fire-and-forget

When enabled, the workflow doesn't wait for this step to complete before moving to the next one. Use it for steps whose result nothing downstream depends on — logging, analytics, notifications — so they don't add latency to the steps that matter.

Continue on error

When enabled, a failure in this step doesn't stop the workflow — execution continues to the next step. The failure is still recorded in the execution history; this just controls whether it's fatal.

Combine the two for steps that are genuinely optional to the outcome: fire-and-forget so they don't add latency, continue-on-error so a failure in them (e.g. an analytics endpoint being briefly down) doesn't take down an otherwise-successful workflow run.

Caching

What it does

When enabled, a step's result is cached for a configurable TTL (time-to-live, in seconds). If the step runs again with the same effective cache key before the TTL expires, the cached result is returned instead of re-running the step.

Configuring it

Enabled — turn caching on or off for this step.
TTL — how long (in seconds) a cached result stays valid.
Cache key template — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same call". By default this is based on the step's resolved input; a custom template lets you cache more narrowly or broadly than that.

When to use it

Good candidates are steps that call something slow or rate-limited but return the same answer for the same input within a short window — a lookup against a rarely-changing external system, for example. Skip it for steps whose result must always be fresh (anything involving live inventory, pricing, or payment state).

Locking

What it does

When enabled, only one execution of this step (for a given lock key) can run at a time. If a second execution tries to run the same step while a lock is held, it waits until the lock is released or the hold period elapses.

Configuring it

Enabled — turn locking on or off for this step.
Lock key — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same resource". By default the lock is scoped to the step itself; a custom key lets you lock per-customer, per-order, or any other identifier that needs serialized access.
Period — how long (in seconds) the lock is held before it's automatically released, in case an execution doesn't complete normally.

When to use it

Use it whenever concurrent executions could race on the same resource — e.g. two workflow runs both trying to update the same order's status at once. A lock key scoped to the order id ensures only one of them proceeds at a time.