Why isn't my Stripe Test Clock recording meter events on invoice.created for usage-based billing?

I have a usage‐based Stripe product where an invoice is generated at the end of each billing period (month). I'm using a Test Clock to verify that the usage is properly recorded on the invoice.

In draft mode, I listen for the invoice.created webhook, calculate the usage, and report it to the meter (see the docs). However, the invoice never reflects the usage I submit.

My process in Test Mode is as follows:

1. Create a Test Clock
2. Create a Customer associated with the Test Clock
3. Create a monthly Subscription for the Customer, starting immediately
4. Advance the Test Clock one month, which triggers the invoice.created event
5. Run the following code in the webhook to record usage:

JAVASCRIPTCopied
const invoice = event.data.object;
const {
  id,
  customer: stripeCustomerId,
  customer_email: email,
  period_start: invoicePeriodStart,
  period_end: invoicePeriodEnd,
  subscription: stripeSubscriptionId,
  status,
} = invoice;

try {
  // A finalized invoice is created when the user first signs up for the usage‐based subscription; we want to ignore this one
  if (status !== 'draft') return;

  // Manually created invoices do not have a subscription and are not of interest here
  if (!stripeSubscriptionId) return;

  // Only report usage for invoices that are for the usage‐based subscription
  const subscription = await stripe.subscriptions.retrieve(stripeSubscriptionId);
  if (subscription.items.data[0].price.lookup_key !== myLookupKey) {
    console.log(
      `Subscription lookup key ${subscription.items.data[0].price.lookup_key} !== ${myLookupKey}`,
    );
    return;
  }

  const user = await users.findByEmail(email);

  // Call another server to get the usage for the previous period
  const organization = user.organization;
  const startDate = new Date(invoicePeriodStart * 1000);
  const endDate = new Date(invoicePeriodEnd * 1000);
  const usageString = await crossServerPostRequest(
    new URL(`<URL FOR GETTING USAGE FOR PERIOD>`),
    {
      organization,
      startDate,
      endDate,
    },
  );

  await stripe.billing.meterEvents.create({
    event_name: 'event_name',
    identifier: crypto.randomUUID(),
    payload: {
      value: parseInt(usageString, 10),
      stripe_customer_id: stripeCustomerId,
    },
    timestamp: invoicePeriodEnd, invoicePeriodStart + (invoicePeriodEnd - invoicePeriodStart) / 2, // I've tried different values here: invoicePeriodStart, invoicePeriodEnd
  });

  postSlackMessage(
      `Usage reported to Stripe for ${user.organization}: ${usageString} (${startDate.toDateString()} - ${endDate.toDateString()})`,
    );
} catch (error) {
  console.error(error);
  postSlackMessage(
    `Error during invoice.created Stripe webhook for ${id} for ${request.body.email}; usage may not have been reported
${error}`,
  );
}

6. I see the event on the Stripe Dashboard for the meter associated with my Test Clock customer
7. I advance the Test Clock by another hour to finalize the invoice
8. The finalized invoice does not include the reported usage

I have also tried advancing the clock to the middle of the period and submitting a meter event manually via the Stripe Dashboard, but the usage still isn't reflected.

Occasionally, setting the meter event timestamp to invoicePeriodStart works, but it's inconsistent. Considering that meter events are processed asynchronously, could this timing be the cause of my issue? I need to ensure that this approach will reliably work in live mode.

Am I doing something wrong, or do Test Clocks not work with meter events as expected?

References:

• Test Clock Limitations