Stripe

Getting started

If you have not yet set up Trigger.dev in your project, go to the quick start guide.

Installation

npm

npm add @trigger.dev/stripe@latest

pnpm add @trigger.dev/stripe@latest

yarn add @trigger.dev/stripe@latest

Authentication

The Stripe integration supports secret API Keys

import { Stripe } from "@trigger.dev/stripe";

const stripe = new Stripe({
  id: "stripe",
  apiKey: process.env.STRIPE_API_KEY!,
});

Triggers

The Stripe integration exposes a number of triggers that can be used on a job, powered by Stripe webhooks.

We recommend testing Stripe payloads using Stripe Shell, Stripe’s browser-based shell with the Stripe CLI pre-installed.

client.defineJob({
  id: "stripe-price",
  name: "Stripe Price",
  version: "0.1.0",
  trigger: stripe.onPriceCreated(),
  run: async (payload, io, ctx) => {
    console.log(ctx.event.name); // "price.created"
  },
});

As you can see above, the job will be triggered on the price.created event. If you’d like to trigger a job on multiple events, you can use the aggregate version of the trigger:

client.defineJob({
  id: "stripe-price",
  name: "Stripe Price",
  version: "0.1.0",
  trigger: stripe.onPrice(),
  run: async (payload, io, ctx) => {
    console.log(ctx.event.name); // "price.created", "price.updated", "price.deleted"
  },
});

“Aggregate” triggers also give you the ability to filter on specific events:

client.defineJob({
  id: "stripe-price",
  name: "Stripe Price",
  version: "0.1.0",
  trigger: stripe.onPrice({
    events: ["price.created", "price.updated"],
  }),
  run: async (payload, io, ctx) => {
    console.log(ctx.event.name); // "price.created", "price.updated"
  },
});

Available triggers are listed below:

Function Name	Payload Object	Events	Aggregate Version
onCharge	Charge	charge.succeeded, charge.failed, charge.captured, charge.refunded, charge.updated	✔️
onChargeSucceeded	Charge	charge.succeeded	onCharge
onChargeFailed	Charge	charge.failed	onCharge
onChargeCaptured	Charge	charge.captured	onCharge
onChargeRefunded	Charge	charge.refunded	onCharge
onChargeUpdated	Charge	charge.updated	onCharge
onProduct	Product	product.created, product.updated, product.deleted	✔️
onProductCreated	Product	product.created	onProduct
onProductUpdated	Product	product.updated	onProduct
onProductDeleted	Product	product.deleted	onProduct
onPrice	Price	price.created, price.updated, price.deleted	✔️
onPriceCreated	Price	price.created	onPrice
onPriceUpdated	Price	price.updated	onPrice
onPriceDeleted	Price	price.deleted	onPrice
onCheckoutSession	CheckoutSession	checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed, checkout.session.expired	✔️
onCheckoutSessionCompleted	CheckoutSession	checkout.session.completed	onCheckoutSession
onCheckoutSessionExpired	CheckoutSession	checkout.session.expired	onCheckoutSession
onCustomerSubscription	Subscription	customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, customer.subscription.paused, customer.subscription.pending_updated_applied, customer.subscription.pending_update_expired, customer.subscription.resumed	✔️
onCustomerSubscriptionCreated	Subscription	customer.subscription.created	onCustomerSubscription
onCustomerSubscriptionUpdated	Subscription	customer.subscription.updated	onCustomerSubscription
onCustomerSubscriptionDeleted	Subscription	customer.subscription.deleted	onCustomerSubscription
onCustomerSubscriptionPaused	Subscription	customer.subscription.paused	onCustomerSubscription
onCustomerSubscriptionPending	Subscription	customer.subscription.pending_updated_applied, customer.subscription.pending_update_expired	onCustomerSubscription
onCustomerSubscriptionResumed	Subscription	customer.subscription.resumed	onCustomerSubscription
onCustomer	Customer	customer.created, customer.updated, customer.deleted	✔️
onCustomerCreated	Customer	customer.created	onCustomer
onCustomerUpdated	Customer	customer.updated	onCustomer
onCustomerDeleted	Customer	customer.deleted	onCustomer
onExternalAccount	Card or Bank Account	account.external_account.created, account.external_account.updated, account.external_account.deleted	✔️
onExternalAccountCreated	Card or Bank Account	account.external_account.created	onExternalAccount
onExternalAccountUpdated	Card or Bank Account	account.external_account.updated	onExternalAccount
onExternalAccountDeleted	Card or Bank Account	account.external_account.deleted	onExternalAccount
onPerson	Person	account.person.created, account.person.updated, account.person.deleted	✔️
onPersonCreated	Person	account.person.created	onPerson
onPersonUpdated	Person	account.person.updated	onPerson
onPersonDeleted	Person	account.person.deleted	onPerson
onAccountUpdated	Account	account.updated	N/A
onPaymentIntent	PaymentIntent	payment_intent.created, payment_intent.succeeded, payment_intent.payment_failed, payment_intent.canceled, payment_intent.processing, payment_intent.amount_capturable_updated, payment_intent.requires_action, payment_intent.partially_funded	✔️
onPaymentIntentCreated	PaymentIntent	payment_intent.created	onPaymentIntent
onPaymentIntentSucceeded	PaymentIntent	payment_intent.succeeded	onPaymentIntent
onPaymentIntentPaymentFailed	PaymentIntent	payment_intent.payment_failed	onPaymentIntent
onPaymentIntentCanceled	PaymentIntent	payment_intent.canceled	onPaymentIntent
onPaymentIntentProcessing	PaymentIntent	payment_intent.processing	onPaymentIntent
onPaymentIntentRequiresAction	PaymentIntent	payment_intent.requires_action	onPaymentIntent
onPaymentIntentAmountCapturableUpdated	PaymentIntent	payment_intent.amount_capturable_updated	onPaymentIntent
onPaymentIntentPartiallyFunded	PaymentIntent	payment_intent.partially_funded	onPaymentIntent
onPayout	Payout	payout.created, payout.updated, payout.canceled, payout.paid, payout.failed, payout.reconciliation_completed	✔️
onPayoutCreated	Payout	payout.created	onPayout
onPayoutUpdated	Payout	payout.updated	onPayout
onPayoutCanceled	Payout	payout.canceled	onPayout
onPayoutPaid	Payout	payout.paid	onPayout
onPayoutFailed	Payout	payout.failed	onPayout
onPayoutReconciliationCompleted	Payout	payout.reconciliation_completed	onPayout
onInvoice	Invoice	invoice.created, invoice.finalized, invoice.finalization_failed, invoice.deleted, invoice.marked_uncollectible, invoice.paid, invoice.payment_action_required, invoice.payment_failed, invoice.payment_succeeded, invoice.sent, invoice.upcoming, invoice.voided, invoiceitem.created, invoiceitem.deleted	✔️
onInvoiceCreated	Invoice	invoice.created	onInvoice
onInvoiceFinalized	Invoice	invoice.finalized	onInvoice
onInvoiceFinalizationFailed	Invoice	invoice.finalization_failed	onInvoice
onInvoiceDeleted	Invoice	invoice.deleted	onInvoice
onInvoiceMarkedUncollectible	Invoice	invoice.marked_uncollectible	onInvoice
onInvoicePaid	Invoice	invoice.paid	onInvoice
onInvoicePaymentActionRequired	Invoice	invoice.payment_action_required	onInvoice
onInvoicePaymentFailed	Invoice	invoice.payment_failed	onInvoice
onInvoicePaymentSucceeded	Invoice	invoice.payment_succeeded	onInvoice
onInvoiceSent	Invoice	invoice.sent	onInvoice
onInvoiceUpcoming	Invoice	invoice.upcoming	onInvoice
onInvoiceVoided	Invoice	invoice.voided	onInvoice
onInvoiceItemCreated	InvoiceItem	invoiceitem.created	N/A
onInvoiceItemDeleted	InvoiceItem	invoiceitem.deleted	N/A

If there are any triggers missing that you’d like to see added, please open a new GitHub Issue

Filtering

All the Stripe triggers take an optional filter parameter that allows you to only run the job when the filter matches the event payload:

// Only trigger when the currency is USD
client.defineJob({
  id: "stripe-on-subscription-created",
  name: "Stripe On Subscription Created",
  version: "0.1.0",
  trigger: stripe.onCustomerSubscriptionCreated({
    filter: {
      currency: ["usd"],
    },
  }),
  run: async (payload, io, ctx) => {
    await io.logger.info("ctx", { ctx });
  },
});

Check out our Event Filter docs for more information on how to use the filter.

Tasks

You can make reliable calls to the Stripe API inside of jobs using the exposed stripe tasks:

const stripe = new Stripe({
  id: "stripe",
  apiKey: process.env["STRIPE_API_KEY"]!,
});

client.defineJob({
  id: "stripe-example-1",
  name: "Stripe Example 1",
  version: "0.1.0",
  trigger: eventTrigger({
    name: "stripe.example",
    schema: z.object({
      customerId: z.string(),
      source: z.string(),
    }),
  }),
  integrations: {
    stripe,
  },
  run: async (payload, io, ctx) => {
    await io.stripe.createCharge("create-charge", {
      amount: 100,
      currency: "usd",
      source: payload.source,
      customer: payload.customerId,
    });
  },
});

We automatically fill in the idempotencyKey for you, so we can gaurentee that the API call will only be executed once.

Available tasks are listed below:

Function Name	Description
createCharge	Use the Payment Intents API to initiate a new payment instead of using this method. Confirmation of the PaymentIntent creates the Charge object used to request payment, so this method is limited to legacy integrations.
createCustomer	Creates a new customer object
updateCustomer	Updates the specified customer by setting the values of the parameters passed
retrieveSubscription	Retrieves the subscription with the given ID.
createCheckoutSession	Creates a new Checkout Session object.

If there are any tasks missing that you’d like to see added, please open a new GitHub Issue

Using the underlying Stripe client

You can use the underlying client to do anything the stripe-node client supports by using runTask on the integration:

const stripe = new Stripe({
  id: "stripe",
  apiKey: process.env["STRIPE_API_KEY"]!,
});

client.defineJob({
  id: "stripe-example-1",
  name: "Stripe Example 1",
  version: "0.1.0",
  trigger: eventTrigger({
    name: "stripe.example",
  }),
  integrations: {
    stripe,
  },
  run: async (payload, io, ctx) => {
    const price = await io.stripe.runTask(
      "create-price",
      async (client, task) => {
        return client.prices.create(
          {
            unit_amount: 2000,
            currency: "usd",
            product_data: {
              name: "T-shirt",
            },
          },
          {
            idempotencyKey: task.idempotencyKey,
          }
        );
      },
      //this is optional, it will appear on the Run page
      { name: "Create Price" }
    );
  },
});

Make sure to pass the idempotencyKey to the underlying client to ensure that the API call is only executed once. This is only needed for mutating API calls.

Example jobs

Code examples

Check out pre-built jobs using Stripe in our API section.