payment-kit 1.15.19 → 1.15.21

package/api/src/libs/notification/template/subscription-will-renew.ts

@@ -21,8 +21,8 @@ import {
 import { getPaymentAmountForCycleSubscription, type PaymentDetail } from '../../payment';
 import { getMainProductName } from '../../product';
 import { getCustomerSubscriptionPageUrl } from '../../subscription';
-import { formatTime, getPrettyMsI18nLocale } from '../../time';
-import { getExplorerLink, getSubscriptionNotificationCustomActions } from '../../util';
+import { formatTime, getPrettyMsI18nLocale, getSimplifyDuration } from '../../time';
+import { getCustomerRechargeLink, getSubscriptionNotificationCustomActions } from '../../util';
 import type { BaseEmailTemplate, BaseEmailTemplateType } from './base';
 
 export interface SubscriptionWillRenewEmailTemplateOptions {
@@ -92,9 +92,7 @@ export class SubscriptionWillRenewEmailTemplate
     const locale = await getUserLocale(userDid);
     const productName = await getMainProductName(subscription.id);
     const at: string = formatTime(invoice.period_end * 1000);
-    const willRenewDuration: string =
-      locale === 'en' ? this.getWillRenewDuration(locale) : this.getWillRenewDuration(locale).split(' ').join('');
-
+    const willRenewDuration = getSimplifyDuration((invoice.period_end - dayjs().unix()) * 1000, locale);
     // const upcomingInvoiceAmount = await getUpcomingInvoiceAmount(subscription.id);
     // const amount: string = fromUnitToToken(+upcomingInvoiceAmount.amount, upcomingInvoiceAmount.currency?.decimal);
     // const paymentDetail: PaymentDetail = await getPaymentDetail(userDid, invoice, amount);
@@ -135,16 +133,12 @@ export class SubscriptionWillRenewEmailTemplate
       userDid,
     });
     const paymentMethod: PaymentMethod | null = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
-    // @ts-ignore
-    const chainHost: string | undefined = paymentMethod?.settings?.[paymentMethod.type]?.api_host;
-    const addFundsLink: string = getExplorerLink({
-      type: 'account',
-      did: userDid,
-      chainHost,
-      queryParams: {
-        action: 'recharge',
-      },
-    })!;
+
+    const addFundsLink: string = getCustomerRechargeLink({
+      locale,
+      userDid,
+      subscriptionId: subscription.id,
+    });
 
     const customActions = getSubscriptionNotificationCustomActions(
       subscription,
@@ -213,31 +207,6 @@ export class SubscriptionWillRenewEmailTemplate
     return currentPeriodEnd > expectedCurrentPeriodEnd;
   }
 
-  getWillRenewDuration(locale: string): string {
-    if (this.options.willRenewUnit === 'M') {
-      if (this.options.willRenewValue > 1) {
-        return `${this.options.willRenewValue} ${translate('notification.common.months', locale)}`;
-      }
-
-      return `${this.options.willRenewValue} ${translate('notification.common.month', locale)}`;
-    }
-    if (this.options.willRenewUnit === 'd') {
-      if (this.options.willRenewValue > 1) {
-        return `${this.options.willRenewValue} ${translate('notification.common.days', locale)}`;
-      }
-      return `${this.options.willRenewValue} ${translate('notification.common.day', locale)}`;
-    }
-
-    if (this.options.willRenewUnit === 'm') {
-      if (this.options.willRenewValue > 1) {
-        return `${this.options.willRenewValue} ${translate('notification.common.minutes', locale)}`;
-      }
-      return `${this.options.willRenewValue} ${translate('notification.common.minute', locale)}`;
-    }
-
-    return `${this.options.willRenewValue} ${this.options.willRenewUnit}`;
-  }
-
   async getTemplate(): Promise<BaseEmailTemplateType | null> {
     const {
       locale,
@@ -421,11 +390,13 @@ export class SubscriptionWillRenewEmailTemplate
       ].filter(Boolean),
       // @ts-ignore
       actions: [
-        !canPay && {
-          name: translate('notification.common.addFunds', locale),
-          title: translate('notification.common.addFunds', locale),
-          link: addFundsLink,
-        },
+        !canPay &&
+          !isStripe &&
+          addFundsLink && {
+            name: translate('notification.common.addFunds', locale),
+            title: translate('notification.common.addFunds', locale),
+            link: addFundsLink,
+          },
         {
           name: translate('notification.common.viewSubscription', locale),
           title: translate('notification.common.viewSubscription', locale),

package/api/src/libs/time.ts

@@ -1,5 +1,6 @@
 import type { LiteralUnion } from 'type-fest';
 
+import prettyMsI18n from 'pretty-ms-i18n';
 import dayjs from './dayjs';
 
 export function formatTime(time: dayjs.ConfigType): string {
@@ -15,3 +16,15 @@ export function getPrettyMsI18nLocale(
 
   return 'en';
 }
+
+export function getSimplifyDuration(ms: number, locale: string): string {
+  const options = {
+    locale: getPrettyMsI18nLocale(locale),
+    compact: true,
+    verbose: true,
+  };
+  if (ms < 1000 && ms >= 0) {
+    options.verbose = false;
+  }
+  return prettyMsI18n(ms, options);
+}

package/api/src/libs/util.ts

@@ -292,6 +292,23 @@ export function getCustomerProfileUrl({
   );
 }
 
+export function getCustomerRechargeLink({
+  locale = 'en',
+  userDid,
+  subscriptionId,
+}: {
+  locale: LiteralUnion<'en' | 'zh', string>;
+  userDid: string;
+  subscriptionId: string;
+}) {
+  return getUrl(
+    withQuery(`customer/subscription/${subscriptionId}/recharge`, {
+      locale,
+      ...getConnectQueryParam({ userDid }),
+    })
+  );
+}
+
 export async function getOwnerDid() {
   try {
     const { user } = await blocklet.getOwner();

package/api/src/locales/en.ts

@@ -153,9 +153,18 @@ export default flat({
     },
 
     subscriptWillCanceled: {
-      title: '{productName} subscription is about to be automatically cancelled ',
-      body: 'Your subscription {productName} will be automatically unsubscribed by the system after {at} (after {willCancelDuration}) due to a long period of failure to automatically complete the automatic payment. Please handle the problem of automatic payment manually in time, so as not to affect the use. If you have any questions, please feel free to contact us.',
+      title: '{productName} subscription is about to be cancelled ',
+      pastDue:
+        'Your subscription {productName} will be automatically unsubscribed by the system after {at} (after {willCancelDuration}) due to a long period of failure to automatically complete the automatic payment. Please handle the problem of automatic payment manually in time, so as not to affect the use. If you have any questions, please feel free to contact us.',
+      body: 'Your subscription to {productName} will be automatically canceled on {at} ({willCancelDuration} later). If you have any questions, please feel free to contact us.',
       renewAmount: 'deduction amount ',
+      cancelReason: 'Cancel reason',
+      revokeStake: 'Revoke stake',
+      adminCanceled: 'Admin canceled',
+      customerCanceled: 'User-initiated cancellation',
+      paymentDisputed: 'Payment disputed',
+      paymentFailed: 'Payment failed',
+      stakeRevoked: 'Stake revoked',
     },
 
     subscriptionCanceled: {
@@ -173,6 +182,7 @@ export default flat({
       customerCanceledAndStakeReturned:
         'User-initiated cancellation, the stake will be returned later, please check for the stake return email',
       paymentFailed: 'Payment failed',
+      stakeRevoked: 'Stake revoked',
     },
   },
 });

package/api/src/locales/zh.ts

@@ -150,9 +150,17 @@ export default flat({
     },
 
     subscriptWillCanceled: {
-      title: '{productName} 订阅即将自动取消',
-      body: '由于长时间未能自动完成扣费，您订阅的 {productName} 将于 {at} ({willCancelDuration}后) 被系统自动取消订阅。请您及时手动处理扣费问题，以免影响使用。如有任何疑问，请随时与我们联系。',
+      title: '{productName} 订阅即将取消',
+      pastDue:
+        '由于长时间未能自动完成扣费，您订阅的 {productName} 将于 {at} ({willCancelDuration}后) 被系统自动取消订阅。请您及时手动处理扣费问题，以免影响使用。如有任何疑问，请随时与我们联系。',
+      body: '您订阅的 {productName} 将于 {at} ({willCancelDuration}后) 被系统取消订阅，如有疑问，请随时与我们联系。',
       renewAmount: '扣费金额',
+      cancelReason: '取消原因',
+      adminCanceled: '管理员取消',
+      customerCanceled: '用户于 {canceled_at} 主动取消',
+      paymentDisputed: '扣费争议',
+      paymentFailed: '扣费失败',
+      stakeRevoked: '撤销质押',
     },
 
     subscriptionCanceled: {
@@ -168,6 +176,7 @@ export default flat({
       customerCanceled: '用户主动取消',
       customerCanceledAndStakeReturned: '用户主动取消, 押金会在稍后退还, 请留意后续的质押退还邮件',
       paymentFailed: '扣费失败',
+      stakeRevoked: '撤销质押',
     },
   },
 });

package/api/src/queues/subscription.ts

@@ -16,6 +16,7 @@ import {
   checkUsageReportEmpty,
   getSubscriptionCycleAmount,
   getSubscriptionCycleSetup,
+  getSubscriptionRefundSetup,
   getSubscriptionStakeAddress,
   getSubscriptionStakeReturnSetup,
   getSubscriptionStakeSlashSetup,
@@ -29,6 +30,7 @@ import { Price } from '../store/models/price';
 import { Subscription } from '../store/models/subscription';
 import { SubscriptionItem } from '../store/models/subscription-item';
 import { invoiceQueue } from './invoice';
+import { SubscriptionWillCanceledSchedule } from '../crons/subscription-will-canceled';
 
 type SubscriptionJob = {
   subscriptionId: string;
@@ -227,7 +229,10 @@ const handleSubscriptionBeforeCancel = async (subscription: Subscription) => {
 
     // persist invoice id
     await subscription.update({ latest_invoice_id: invoice.id });
-    logger.info('Subscription updated before cancel', { invoice: invoice.id, subscription: subscription.id });
+    logger.info('Subscription updated before cancel', {
+      subscription: subscription.id,
+      latestInvoiceId: invoice.id,
+    });
   }
 };
 
@@ -256,6 +261,9 @@ const handleSubscriptionWhenActive = async (subscription: Subscription) => {
     const now = dayjs().unix();
     if (subscription.trial_end && subscription.trial_end <= now) {
       await subscription.update({ status: 'active' });
+      logger.info('Subscription status updated from trialing to active', {
+        subscription: subscription.id,
+      });
     }
   }
 
@@ -438,6 +446,11 @@ const handleStakeSlashAfterCancel = async (subscription: Subscription) => {
       },
     },
   });
+  logger.info('PaymentIntent updated after stake slash', {
+    subscription: subscription.id,
+    paymentIntent: paymentIntent.id,
+    status: 'succeeded',
+  });
   await invoice.update({
     paid: true,
     status: 'paid',
@@ -447,6 +460,12 @@ const handleStakeSlashAfterCancel = async (subscription: Subscription) => {
     attempted: true,
     status_transitions: { ...invoice.status_transitions, paid_at: dayjs().unix() },
   });
+
+  logger.info('Invoice updated after stake slash', {
+    subscription: subscription.id,
+    invoice: invoice.id,
+    status: 'paid',
+  });
 };
 
 const ensureReturnStake = async (subscription: Subscription) => {
@@ -626,7 +645,11 @@ const slashStakeOnCancel = async (subscription: Subscription) => {
         subscription_id: subscription.id,
       } as unknown as Invoice,
     });
-    logger.info('Invoice created for stake slash', { invoice: newInvoice.id, subscription: subscription.id });
+    logger.info('New invoice created for stake slash', {
+      subscription: subscription.id,
+      invoice: newInvoice.id,
+      amount: result.return_amount,
+    });
     invoiceQueue.push({
       id: newInvoice.id,
       job: { invoiceId: newInvoice.id, retryOnError: true },
@@ -635,6 +658,58 @@ const slashStakeOnCancel = async (subscription: Subscription) => {
   }
 };
 
+const ensureRefundOnCancel = async (subscription: Subscription) => {
+  // @ts-ignore
+  const { refund } = subscription.cancelation_details;
+  if (!['last', 'proration'].includes(refund)) {
+    logger.warn('Refund skipped because refund type is not last or proration', {
+      subscription: subscription.id,
+      refund,
+    });
+    return;
+  }
+  const result = await getSubscriptionRefundSetup(subscription, subscription.cancel_at);
+  if (result.unused === '0') {
+    logger.warn('Refund skipped because unused amount is 0', {
+      subscription: subscription.id,
+      unused: result.unused,
+    });
+    return;
+  }
+  const item = await Refund.create({
+    type: 'refund',
+    livemode: subscription.livemode,
+    amount: refund === 'last' ? result.total : result.unused,
+    description: 'refund_transfer_on_subscription_cancel',
+    status: 'pending',
+    reason: 'requested_by_admin',
+    currency_id: subscription.currency_id,
+    customer_id: subscription.customer_id,
+    payment_method_id: subscription.default_payment_method_id,
+    payment_intent_id: result.lastInvoice.payment_intent_id as string,
+    invoice_id: result.lastInvoice.id,
+    subscription_id: subscription.id,
+    attempt_count: 0,
+    attempted: false,
+    next_attempt: 0,
+    last_attempt_error: null,
+    starting_balance: '0',
+    ending_balance: '0',
+    starting_token_balance: {},
+    ending_token_balance: {},
+    metadata: {
+      requested_by: subscription.cancelation_details?.requested_by,
+      unused_period_start: refund === 'last' ? subscription.current_period_start : subscription.cancel_at,
+      unused_period_end: subscription.current_period_end,
+    },
+  });
+  logger.info('Created refund for canceled subscription', {
+    subscription: subscription.id,
+    refund: item.toJSON(),
+    refundType: refund,
+  });
+};
+
 // generate invoice for subscription periodically
 export const handleSubscription = async (job: SubscriptionJob) => {
   logger.info('handle subscription', job);
@@ -793,6 +868,25 @@ export const returnStakeQueue = createQueue({
   },
 });
 
+export const subscriptionCancelRefund = createQueue({
+  name: 'subscription-cancel-refund',
+  onJob: async (job) => {
+    const { subscriptionId } = job;
+    const subscription = await Subscription.findByPk(subscriptionId);
+    if (!subscription) {
+      return;
+    }
+    await ensureRefundOnCancel(subscription);
+  },
+  options: {
+    concurrency: 1,
+    maxRetries: 5,
+    retryDelay: 1000,
+    maxTimeout: 60000,
+    enableScheduledJob: true,
+  },
+});
+
 export async function addSubscriptionJob(
   subscription: Subscription,
   action: 'cycle' | 'cancel' | 'resume',
@@ -831,6 +925,7 @@ subscriptionQueue.on('failed', ({ id, job, error }) => {
 
 events.on('customer.subscription.past_due', async (subscription: Subscription) => {
   await subscriptionQueue.delete(subscription.id);
+  await new SubscriptionWillCanceledSchedule().reScheduleSubscriptionTasks([subscription]);
   await addSubscriptionJob(subscription, 'cancel', true, subscription.cancel_at || subscription.current_period_end);
   logger.info('subscription cancel job scheduled after past_due', {
     subscription: subscription.id,
@@ -852,6 +947,15 @@ events.on('customer.subscription.deleted', (subscription: Subscription) => {
   });
   // FIXME: ensure invoices that are open or uncollectible are voided
 
+  if (
+    subscription.cancelation_details?.refund &&
+    ['last', 'proration'].includes(subscription.cancelation_details.refund)
+  ) {
+    subscriptionCancelRefund.push({
+      id: `subscription-cancel-refund-${subscription.id}`,
+      job: { subscriptionId: subscription.id },
+    });
+  }
   if (subscription.cancelation_details?.slash_stake) {
     slashStakeQueue.push({
       id: `slash-stake-${subscription.id}`,
@@ -863,8 +967,7 @@ events.on('customer.subscription.deleted', (subscription: Subscription) => {
 });
 
 events.on('customer.subscription.upgraded', async (subscription: Subscription) => {
-  await subscriptionQueue.delete(subscription.id);
-  await addSubscriptionJob(subscription, 'cancel', true, subscription.current_period_end);
+  await addSubscriptionJob(subscription, 'cycle', true, subscription.current_period_end);
   logger.info('subscription cycle job rescheduled after upgrade', {
     subscription: subscription.id,
     runAt: subscription.current_period_end,
@@ -891,5 +994,6 @@ events.on('customer.stake.revoked', async ({ subscriptionId, tx }: { subscriptio
       comment: `Revoked by ${tx.tx.from} with tx ${tx.hash}`,
     },
   });
+  await new SubscriptionWillCanceledSchedule().reScheduleSubscriptionTasks([subscription]);
   await addSubscriptionJob(subscription, 'cancel', true, subscription.current_period_end);
 });

package/api/src/routes/connect/recharge.ts

@@ -0,0 +1,143 @@
+import type { Transaction } from '@ocap/client';
+import { fromAddress } from '@ocap/wallet';
+import { fromTokenToUnit, toBase58 } from '@ocap/util';
+import { encodeTransferItx } from 'api/src/integrations/ethereum/token';
+import { executeEvmTransaction, waitForEvmTxConfirm } from 'api/src/integrations/ethereum/tx';
+import type { CallbackArgs } from '../../libs/auth';
+import { getGasPayerExtra } from '../../libs/payment';
+import { getTxMetadata } from '../../libs/util';
+import { ensureSubscriptionRecharge, getAuthPrincipalClaim } from './shared';
+import logger from '../../libs/logger';
+
+export default {
+  action: 'recharge',
+  authPrincipal: false,
+  claims: {
+    authPrincipal: async ({ extraParams }: CallbackArgs) => {
+      const { paymentMethod } = await ensureSubscriptionRecharge(extraParams.subscriptionId);
+      return getAuthPrincipalClaim(paymentMethod, 'recharge');
+    },
+  },
+  onConnect: async ({ userDid, userPk, extraParams }: CallbackArgs) => {
+    const { subscriptionId } = extraParams;
+    let { amount } = extraParams;
+    const { paymentMethod, paymentCurrency, receiverAddress } = await ensureSubscriptionRecharge(subscriptionId);
+    amount = fromTokenToUnit(amount, paymentCurrency.decimal).toString();
+    if (paymentMethod.type === 'arcblock') {
+      const tokens = [{ address: paymentCurrency.contract as string, value: amount }];
+      // @ts-ignore
+      const itx: TransferV3Tx = {
+        outputs: [{ owner: receiverAddress, tokens, assets: [] }],
+        data: getTxMetadata({
+          rechargeCustomerId: receiverAddress,
+          subscriptionId,
+          currencyId: paymentCurrency.id,
+          amount,
+          action: 'recharge',
+        }),
+      };
+
+      const claims: { [key: string]: object } = {
+        prepareTx: {
+          type: 'TransferV3Tx',
+          description: `Recharge account for ${receiverAddress}`,
+          partialTx: { from: userDid, pk: userPk, itx },
+          requirement: { tokens },
+          chainInfo: {
+            host: paymentMethod.settings?.arcblock?.api_host as string,
+            id: paymentMethod.settings?.arcblock?.chain_id as string,
+          },
+        },
+      };
+
+      return claims;
+    }
+
+    if (paymentMethod.type === 'ethereum') {
+      return {
+        signature: {
+          type: 'eth:transaction',
+          data: toBase58(
+            Buffer.from(
+              JSON.stringify({
+                network: paymentMethod.settings?.ethereum?.chain_id,
+                tx: encodeTransferItx(receiverAddress, amount, paymentCurrency.contract as string),
+              }),
+              'utf-8'
+            )
+          ),
+        },
+      };
+    }
+
+    throw new Error(`Payment method ${paymentMethod.type} not supported`);
+  },
+  onAuth: async ({ request, userDid, claims, extraParams }: CallbackArgs) => {
+    const { subscriptionId } = extraParams;
+    const { paymentMethod, paymentCurrency, receiverAddress } = await ensureSubscriptionRecharge(subscriptionId);
+    let { amount } = extraParams;
+    amount = fromTokenToUnit(amount, paymentCurrency.decimal).toString();
+
+    if (paymentMethod.type === 'arcblock') {
+      try {
+        const client = paymentMethod.getOcapClient();
+        const claim = claims.find((x) => x.type === 'prepareTx');
+
+        const tx: Partial<Transaction> = client.decodeTx(claim.finalTx);
+        if (claim.delegator && claim.from) {
+          tx.delegator = claim.delegator;
+          tx.from = claim.from;
+        }
+
+        // @ts-ignore
+        const { buffer } = await client.encodeTransferV3Tx({ tx });
+        const txHash = await client.sendTransferV3Tx(
+          // @ts-ignore
+          { tx, wallet: fromAddress(userDid) },
+          getGasPayerExtra(buffer, client.pickGasPayerHeaders(request))
+        );
+
+        logger.info('Recharge successful', {
+          receiverAddress,
+          amount,
+          subscriptionId,
+          paymentMethod: paymentMethod.type,
+        });
+
+        return { hash: txHash };
+      } catch (err) {
+        console.error(err);
+        logger.error('Failed to finalize recharge on arcblock', { receiverAddress, error: err });
+        throw err;
+      }
+    }
+
+    if (paymentMethod.type === 'ethereum') {
+      try {
+        const paymentDetails = await executeEvmTransaction('transfer', userDid, claims, paymentMethod);
+        waitForEvmTxConfirm(
+          paymentMethod.getEvmClient(),
+          Number(paymentDetails.block_height),
+          paymentMethod.confirmation.block
+        )
+          .then(() => {
+            logger.info('Recharge successful', {
+              receiverAddress,
+              amount,
+              subscriptionId,
+              paymentMethod: paymentMethod.type,
+            });
+          })
+          .catch(console.error);
+
+        return { hash: paymentDetails.tx_hash };
+      } catch (err) {
+        console.error(err);
+        logger.error('Failed to finalize recharge on ethereum', { receiverAddress, error: err });
+        throw err;
+      }
+    }
+
+    throw new Error(`Payment method ${paymentMethod.type} not supported`);
+  },
+};

package/api/src/routes/connect/shared.ts

@@ -606,6 +606,31 @@ export async function ensureInvoiceForCollect(invoiceId: string) {
   };
 }
 
+export async function ensureSubscriptionRecharge(subscriptionId: string) {
+  const subscription = await Subscription.findByPk(subscriptionId);
+  if (!subscription) {
+    throw new Error(`Subscription ${subscriptionId} not found`);
+  }
+  const paymentCurrency = await PaymentCurrency.findByPk(subscription.currency_id);
+  if (!paymentCurrency) {
+    throw new Error(`Currency ${subscription.currency_id} not found`);
+  }
+  const paymentMethod = await PaymentMethod.findByPk(paymentCurrency.payment_method_id);
+  if (!paymentMethod) {
+    throw new Error(`Payment method ${paymentCurrency.payment_method_id} not found`);
+  }
+  // @ts-ignore
+  const receiverAddress = subscription?.payment_details?.[paymentMethod.type]?.payer;
+  if (!receiverAddress) {
+    throw new Error(`Receiver address not found for subscription ${subscriptionId}`);
+  }
+  return {
+    paymentCurrency: paymentCurrency as PaymentCurrency,
+    paymentMethod: paymentMethod as PaymentMethod,
+    receiverAddress,
+  };
+}
+
 export function getAuthPrincipalClaim(method: PaymentMethod, action: string) {
   let chainInfo = { type: 'none', id: 'none', host: 'none' };
   if (method.type === 'arcblock') {

package/api/src/routes/customers.ts

@@ -96,8 +96,8 @@ router.get('/me', user(), async (req, res) => {
     } else {
       const [summary, stake, token] = await Promise.all([
         doc.getSummary(),
-        getStakeSummaryByDid(doc.did, doc.livemode),
-        getTokenSummaryByDid(doc.did, doc.livemode),
+        getStakeSummaryByDid(doc.did, req?.livemode || doc.livemode),
+        getTokenSummaryByDid(doc.did, req?.livemode || doc.livemode),
       ]);
       res.json({ ...doc.toJSON(), summary: { ...summary, stake, token } });
     }

package/api/src/routes/subscription-items.ts

@@ -8,7 +8,9 @@ import { createListParamSchema, MetadataSchema } from '../libs/api';
 import { authenticate } from '../libs/security';
 import { expandLineItems } from '../libs/session';
 import { formatMetadata } from '../libs/util';
-import { Price, Product, SubscriptionItem, UsageRecord } from '../store/models';
+import { Price, Product, Subscription, SubscriptionItem, UsageRecord } from '../store/models';
+import { forwardUsageRecordToStripe } from '../integrations/stripe/resource';
+import { usageRecordQueue } from '../queues/usage-record';
 
 const router = Router();
 const auth = authenticate<SubscriptionItem>({ component: true, roles: ['owner', 'admin'] });
@@ -164,19 +166,55 @@ router.post('/:id/add-usage-quantity', auth, async (req, res) => {
     return res.status(403).json({ error: 'add usage quantity not allowed in livemode' });
   }
 
-  const subscriptionItem = await SubscriptionItem.findByPk(req.params.id);
-  if (!subscriptionItem) {
-    return res.status(404).json({ error: `SubscriptionItem(${req.params.id}) item not found` });
+  const quantity = Number(req.body.quantity);
+  if (quantity <= 0) {
+    return res.status(400).json({ error: 'quantity must be positive' });
   }
 
-  await UsageRecord.create({
-    livemode: Boolean(livemode),
-    subscription_item_id: subscriptionItem.id,
-    quantity: req.body.quantity,
-    timestamp: dayjs().unix(),
-  } as UsageRecord);
+  try {
+    const subscriptionItem = await SubscriptionItem.findByPk(req.params.id);
+    if (!subscriptionItem) {
+      return res.status(404).json({ error: `SubscriptionItem(${req.params.id}) item not found` });
+    }
+    const subscription = await Subscription.findByPk(subscriptionItem.subscription_id);
+    if (!subscription) {
+      return res.status(400).json({ error: `Subscription not found: ${subscriptionItem.subscription_id}` });
+    }
+
+    if (subscription.isImmutable()) {
+      return res.status(400).json({ error: `subscription(${subscription.id}) is immutable` });
+    }
+
+    const now = dayjs().unix();
+
+    if (now < subscription.current_period_start || now > subscription.current_period_end) {
+      return res.status(400).json({ error: 'timestamp must be within the current period' });
+    }
+
+    const usageRecord = await UsageRecord.create({
+      livemode: Boolean(livemode),
+      subscription_item_id: subscriptionItem.id,
+      quantity,
+      timestamp: now,
+    } as UsageRecord);
+
+    if (subscription.billing_thresholds?.amount_gte) {
+      usageRecordQueue.push({
+        id: `usage-${subscription.id}`,
+        job: { subscriptionId: subscription.id, subscriptionItemId: subscriptionItem.id },
+      });
+    }
 
-  return res.json();
+    await forwardUsageRecordToStripe(subscriptionItem, {
+      quantity,
+      timestamp: now,
+      action: 'increment',
+    });
+    return res.json(usageRecord);
+  } catch (err) {
+    console.error(err);
+    return res.status(400).json({ error: `Failed to add usage quantity: ${err.message}` });
+  }
 });
 
 export default router;