Track past-due invoices with invoice_past_due

Fires when a customer’s account falls behind on an invoice. Track it once per invoice, then use it to start collection flows and to count accounts at risk of involuntary churn. Upstack doesn’t generate this SaaS event for you, so your app or billing webhook has to send it. Use it alongside payment_failed, not instead of it. payment_failed fires on every failed charge attempt, so one invoice can produce several. invoice_past_due marks the moment the account itself is behind on payment.

JavaScript

Track it from the browser when your app first learns the invoice is past due, for example when it renders a billing banner. Pass a stable eventId as the third argument so repeat page loads count as one event.

window._upstack('track', 'invoice_past_due', {
  accountId: 'acct_abc123',
  invoiceId: 'in_1QxR8m2eZvKYlo2C',
  subscriptionId: 'sub_1QxR4k2eZvKYlo2C',
  amount: 9900,
  value: 99.00,
  currency: 'USD',
  attemptCount: 3
}, 'invoice_past_due_in_1QxR8m2eZvKYlo2C');

Server-side

Billing changes usually reach you as webhooks, where window._upstack() isn’t available. Send the event from your server with POST /tr/api/events instead. The API key needs the events:write scope. This Express handler watches Stripe’s customer.subscription.updated event. When the subscription status is past_due, it looks up the subscription’s latest invoice and sends invoice_past_due to Upstack.

// Node.js / Express. Assumes you store your own account ID in subscription metadata.
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers['stripe-signature'],
    process.env.STRIPE_WEBHOOK_SECRET
  );

  if (event.type === 'customer.subscription.updated') {
    const subscription = event.data.object;

    if (subscription.status === 'past_due') {
      const invoice = await stripe.invoices.retrieve(subscription.latest_invoice);

      await fetch('https://api.upstackdata.com/tr/api/events', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-api-key': process.env.UPSTACK_API_KEY,
          'x-pixel-id': process.env.UPSTACK_PIXEL_ID
        },
        body: JSON.stringify({
          events: [{
            name: 'invoice_past_due',
            eventId: `invoice_past_due_${invoice.id}`,
            userProperties: {
              emails: invoice.customer_email ? [invoice.customer_email] : []
            },
            eventProperties: {
              accountId: subscription.metadata.account_id,
              invoiceId: invoice.id,
              subscriptionId: subscription.id,
              amount: invoice.amount_remaining,
              value: invoice.amount_remaining / 100, // two-decimal currencies
              currency: invoice.currency.toUpperCase(),
              attemptCount: invoice.attempt_count
            }
          }]
        })
      });
    }
  }

  res.json({ received: true });
});

Stripe sends customer.subscription.updated for any change to the subscription, so a past-due subscription can trigger the handler more than once. The eventId takes care of that: Upstack skips an event whose eventId it has already seen in the last 30 days, so each invoice is counted once. If you bill with invoices that have a due date instead of automatic charges, Stripe’s invoice.overdue event is the closer match. It fires a set number of days after an invoice’s due date, and you choose the number of days in Stripe’s billing automations. Its payload is the invoice itself, so you can skip the stripe.invoices.retrieve call.

Properties

Property	Type	Required	Description
accountId	string	No	Your ID for the customer’s account or workspace
invoiceId	string	No	The past-due invoice, for example Stripe’s `in_...` ID
subscriptionId	string	No	The subscription the invoice belongs to
amount	number	No	Amount still owed, in the smallest currency unit (cents for USD)
value	number	No	Amount still owed, in currency units (`99.00`, not `9900`). Feeds the Invoice Past Due Value measure
currency	string	No	ISO 4217 code, uppercase: `USD`, `EUR`
attemptCount	number	No	Payment attempts made so far. Not a standard Upstack property, so it’s stored as sent

Upstack doesn’t reject an invoice_past_due event with missing properties, but send accountId and invoiceId so you can tell events apart later.

Send value as well as amount if you want the money owed to show in reports. Upstack’s Invoice Past Due Value measure adds up value. It ignores amount.

When to fire

A subscription’s status changes to past_due (Stripe customer.subscription.updated)
An invoice with a due date is still unpaid after that date (Stripe invoice.overdue)
Your own billing system flags an invoice as overdue

Don’t fire it on each failed charge. That’s payment_failed.

Where it goes

Reports. Three measures are available on custom dashboards: Invoice Past Due (count), Invoice Past Due Value, and Cost per Invoice Past Due.
Klaviyo. Sent by default as the metric Invoice Past Due - Upstack, so you can start a collection flow from it. See Klaviyo.
Meta, Microsoft Ads and Reddit. Sent by default as a custom event named invoice_past_due. Meta needs the custom event approved before you can optimize on it. See How to approve Meta custom events.
Other destinations. Not sent by default. Add it on the destination’s Event Mappings tab with a destination event mapping. LinkedIn, Snapchat, AppLovin, and NewsBreak can’t receive custom events.

payment_failed

Each failed charge attempt, usually before the invoice goes past due

invoice_paid

The invoice is settled and the account recovers

invoice_created

The invoice is issued

subscription_churned

The subscription ends after collection fails

For every SaaS event in one place, see the SaaS events reference.

​JavaScript

​Server-side

​Properties

​When to fire

​Where it goes

​Related events

payment_failed

invoice_paid

invoice_created

subscription_churned

JavaScript

Server-side

Properties

When to fire

Where it goes

Related events