Stripe Billingで、プラン変更時の比例配分で減額した請求の元データを取得する

10883 ワード
StripeUpdates stripeBilling stripe stripe テキストリンク

Stripeを利用したサブスクリプションでは、プラン変更時に「変更した時から、本来の契約期間終了日までの未使用分」を値引きすることができます。

この時、請求書には、「Unused time on Starter plan after 05 Apr 2022」のように明細が記録されます。

一見便利な仕組みですが、ユーザーによっては「なぜ値引きされたか」や「何に対して値引きされたか」を知りたいとサポートに問い合わせされるケースもあります。

ここでは、UI上でユーザーがより詳細な請求内容を確認できるようにする方法として、「どの請求書に対して比例配分が行われたか」を調べる方法を紹介します。

請求書のproration_detailsで対象の請求書IDが取得可能

請求書のデータをAPIから取得すると、proration_detailsがレスポンスに含まれています。

{
  proration_details: {
    credited_items: {
     invoice: 'in_xxxx',
     invoice_line_items: ['li_xxxx']
   }
 },
  ...
}

このデータを利用することで、何に対しての比例配分だったかを調べることができます。

proration_detailsから対象の請求書データを取得するコードサンプル

以下のコードでは、請求書の明細１行ごとに対応する請求書を取得できます。

const getCreditedInvoice = async (prorationDetails) => {
  if (!prorationDetails || !prorationDetails.credited_items) return null;
  const creditedInvoiceId = prorationDetails.credited_items.invoice;
  const creditedInvoice = await stripe.invoices.retrieve(creditedInvoiceId);
  return creditedInvoice
};


const id = 'in_xxx';
const invoice = await stripe.invoices.retrieve(id);
await Promise.all(invoice.lines.data.map(async line => {
  console.log(await getCreditedInvoice(line.proration_details));
}));

もし、明細の行まで指定したい場合は、以下のような関数を追加しましょう。

const getCreditedInvoice = async (prorationDetails) => {
  if (!prorationDetails || !prorationDetails.credited_items) return null;
  const creditedInvoiceId = prorationDetails.credited_items.invoice;
  const creditedInvoice = await stripe.invoices.retrieve(creditedInvoiceId);
  return creditedInvoice
};

const findCreditedInvoiceLineItems = async (prorationDetails, invoice) => {
  if (!prorationDetails || !prorationDetails.credited_items) return [];
  if (!invoice || !invoice.lines.data) return [];
  const creditedInvoiceLineIds = prorationDetails.credited_items.invoice_line_items;
  const targets = invoice.lines.data.filter(line => creditedInvoiceLineIds.includes(line.id));
  return targets;
};

const id = 'in_xxx';
const invoice = await stripe.invoices.retrieve(id);
await Promise.all(invoice.lines.data.map(async line => {
  const invoice = await getCreditedInvoice(line.proration_details);
  console.log(await findCreditedInvoiceLineItems(line.proration_details, invoice));
}));

attributeの違い

Invoice line item attribute Description
proration_details.credited_items.invoice クレジットされた請求書の明細を含む請求書のID
proration_details.credited_items.invoice_line_items クレジットされた請求書の明細のID（複数）

[PR] Stripe開発者向け情報をQiitaにて配信中！

  • [Stripe Updates]：開発者向けStripeアップデート紹介・解説
  • ユースケース別のStripe製品や実装サンプルの紹介
  • Stripeと外部サービス・OSSとの連携方法やTipsの紹介
  • 初心者向けのチュートリアル(予定)

など、Stripeを利用してオンラインビジネスを始める方法について週に２〜３本ペースで更新中です。

-> Stripe Organizationsをフォローして最新情報をQiitaで受け取る