Stripe actions

The Stripe block runs Stripe API calls from a workflow step. For the plain-language guide, see Stripe.

When to use it

Use it to create and send invoices, issue credit notes and refunds, manage customers, products, prices and subscriptions, and read payments, balances and balance transactions. Stripe has no Studio trigger block. A developer can configure a generic webhook trigger for Stripe Connect events tied to a connected account; see Webhook trigger. A schedule, API call, email or another system's event can also start the workflow.

Connection

• Provider id: stripe.
• Two ways to connect, chosen in Studio's connect dialog or with authVariant when you start a connect session: oauth (Stripe Connect, the default) and api_key (a Stripe restricted key). Both produce the same kind of connection, and every action works with either.
• A reconnect keeps the method the account was first connected with.
• Pin an account with config.connection (a connection id). Without it, the step uses the company's default Stripe connection. A pinned connection that cannot be used stops the run.

Actions

Each step names one action as stripe.<operation>. The table lists every action the block registers, in the order Studio shows them.

Settings

Fields go in the step's config. "Used by" lists the operations that show the field in Studio. Field names are the same in Studio and in a workflow definition.

The executors also read a few fields Studio does not show: daysUntilDue and autoAdvance (createInvoice), customerId (createInvoiceItem), phone and address (createCustomer, updateCustomer), status (listInvoices, listSubscriptions), and phases (createSubscriptionSchedule).

Rules the actions enforce

• Amounts are integers in the smallest currency unit (cents for USD).
• createRefund and createCreditNote require idempotencyKey. Build it from ids that stay the same when the step is retried, such as refund:<invoice id>. createRefund tags the refund with the key and, on a re-run, returns the refund it already made; a re-run that asks for a different amount is refused.
• createRefund takes paymentIntentId (pi_...) or chargeId (ch_... or py_...), and amount as whole positive cents, or fullRefund: true. Any other value stops the step before Stripe is called.
• deleteInvoice deletes only a draft. Stripe refuses any other status; use voidInvoice for a finalized invoice.
• updateInvoiceMetadata sends only metadata[key]=value pairs to POST /v1/invoices/:id, so it cannot change anything else on the invoice. Stripe keeps the keys you do not send; an empty string or null clears a key. An empty object is refused, because Stripe reads a bare metadata= as "clear every key". Stripe allows up to 50 keys, key names up to 40 characters without [ or ], and values up to 500 characters (Stripe metadata); the step checks these before calling Stripe.
• listInvoices filters by subscriptionId and by createdFrom/createdTo (created[gte]/created[lte], ISO 8601 or unix seconds, inclusive; a date-only createdTo covers the whole UTC day). autoPaginate fetches every page at 100 per page and fails the step past 100 pages.
• createInvoiceItem accepts priceId, or productId with unitAmount or amount, or amount alone. priceId cannot be combined with productId, unitAmount or amount. couponId cannot be combined with discountAmount. A positive discountAmount creates a single-use coupon for that line.
• createInvoice sends collection_method charge_automatically and auto_advance true unless you set them.

Output

A step's output is the Stripe API object the call returns, stored as is. Read it with {{steps.<stepId>.<path>}}, for example {{steps.create_invoice.id}} or {{steps.create_invoice.hosted_invoice_url}}. List actions return Stripe's list object, with the records under data.

Example

This workflow creates an invoice for the customer passed in at run time, adds one line, finalizes it and emails it.

{
  "name": "Invoice a customer",
  "trigger": { "type": "api" },
  "steps": [
    {
      "id": "create_invoice",
      "type": "action",
      "name": "Create the invoice",
      "action": "stripe.createInvoice",
      "config": {
        "customerId": "{{input.customerId}}",
        "collectionMethod": "send_invoice",
        "daysUntilDue": 30,
        "description": "Services for {{input.period}}"
      }
    },
    {
      "id": "add_line",
      "type": "action",
      "name": "Add the line",
      "action": "stripe.createInvoiceItem",
      "config": {
        "customerId": "{{input.customerId}}",
        "invoiceId": "{{steps.create_invoice.id}}",
        "amount": 125000,
        "currency": "usd",
        "description": "Monthly retainer"
      }
    },
    {
      "id": "finalize",
      "type": "action",
      "name": "Finalize the invoice",
      "action": "stripe.finalizeInvoice",
      "config": { "invoiceId": "{{steps.create_invoice.id}}" }
    },
    {
      "id": "send",
      "type": "action",
      "name": "Email the invoice",
      "action": "stripe.sendInvoice",
      "config": { "invoiceId": "{{steps.create_invoice.id}}" }
    }
  ]
}

Live catalog

• GET /api/v1/blocks/stripe returns the block's current actions and fields.
• GET /api/v1/blocks/stripe/actions/<operation>/examples returns the stored input and output examples for one action, where one exists.

See Block and action discovery.

Errors and limits

• A Stripe API error fails the step, and the step error carries Stripe's own message and code.
• A validation rule above fails the step before Stripe is called, with a message that names the field.
• The workflow validator rejects an operation that is not in the table above.