JP_StripeのFBグループで質問したところいろいろ教えていただけたので、それをもとに調べたことをまとめてみました。

３行まとめ

• subscriptions.updateは次回請求タイミングに差分を請求する仕様
• 即時決済したい場合はinvoices.createで請求を作る必要がある
• subscriptionで設定した税率を設定漏れすると請求に含まれないので注意

やりたいこと

プラン変更時に、差額だけ即時決済したい。

ドキュメント

 If you want the customer to immediately pay the price difference when switching to a more expensive plan on the same billing cycle, you need to generate an invoice after making the switch.

[Google 翻訳]同じ請求サイクルでより高価なプランに切り替えるときに、顧客がすぐに価格差額を支払うようにするには、切り替え後に請求書を生成する必要があります。

https://stripe.com/docs/subscriptions/upgrading-downgrading

実験

ケース1:プラン変更のみ

subscriptions.retrieve()で存在確認後にsubscriptions.update()で更新するのみで実験。

const stripe = require("stripe")(
  "sk_test_XXXX"
);

const subscriptionId = 'sub_XXXX'
const customerId = 'cus_XXXX'
const planId = 'new-plan-id'


stripe.subscriptions.retrieve(subscriptionId)
.then(subscription=> {
  const params = {
    items: [{
      id: subscription.items.data[0].id,
      plan: planId,
    }]
  }
  return stripe.subscriptions.update(subscriptionId, params)
})
.then(result => console.log(result))
.catch(err => console.log(err))

ケース1実験結果

プランの変更と比例配分の調整が実施されました。
調整金額は次回の支払いサイクル（4月）にまとめて決済されます。

ケース2:プラン変更と同時にInvoiceを発行する

今度はsubscriptions.update()実行直後にinvoices.crete()を実行してみます。

const stripe = require("stripe")(
  "sk_test_XXXX"
);

const subscriptionId = 'sub_XXXX'
const customerId = 'cus_XXXX'
const planId = 'new-plan-id'


stripe.subscriptions.retrieve(subscriptionId)
.then(subscription=> {
  const params = {
    items: [{
      id: subscription.items.data[0].id,
      plan: planId,
    }]
  }
  return stripe.subscriptions.update(subscriptionId, params)
})
.then(() => {
  return stripe.invoices.create({
    customer: customerId,
    subscription: subscriptionId
  })
})
.then(result => console.log(result))
.catch(err => console.log(err))

ケース2実験結果

こちらもプランの変更と比例配分の調整が実施されています。ただし今回はそれだけではなく、調整金額のみを請求するInvoiceが作成されています。

新しく発行されたInvoiceをみると、比例配分の金額のみが明細に記載されているのがわかります。また、請求タイミングについても1〜2週間以内と通常の請求サイクルとは別になっています。

そのため次回の請求サイクルには、変更後のプランの料金のみが記載されるようになっています。

ケース3:極端なケースを試してみる

ここまできたらせっかくなので、ちょっと極端なケースを試してみます。ケースとしては、「年額のプランをsubscribe」し、「即座にプランをupdate」するとどうなるかというものです。

// == 自分のアカウントのデータに書き換える ==
const stripe = require("stripe")(
  "sk_test_XXXX"
);

const customerId = 'cus_XXXX'
const plan1Id = 'yearly-plan-1'
const plan2Id = 'yearly-plan-2'
// === ここまで ===

let subscriptionId = ''

stripe.subscriptions.create({
  customer: customerId,
  items: [
    {
      plan: plan1Id,
    }
  ],
}).then(subscription => {
  subscriptionId = subscription.id
  return stripe.subscriptions.retrieve(subscriptionId)
.then(subscription=> {
  const params = {
    items: [{
      id: subscription.items.data[0].id,
      plan: planId,
    }]
  }
  return stripe.subscriptions.update(subscriptionId, params)
})
.then(() => {
  return stripe.invoices.create({
    customer: customerId,
    subscription: subscriptionId
  })
})
.then(result => console.log(result))
.catch(err => console.log(err))

ケース3実験結果

さっそく作成されたSubscriptionをダッシュボードから見にいきます。

ちゃんと今年分の変更差額と、来年の請求が別々に請求するようになっていますね。

プランの追加などでも問題なさそうです。

ついでなので以下のようなコードで、プラン変更ではなく新しく追加した場合にどうなるかも試してみました。

// == 自分のアカウントのデータに書き換える ==
const stripe = require("stripe")(
  "sk_test_XXXX"
);

const customerId = 'cus_XXXX'
const planId = 'yearly-plan'
const option = 'yearly-option'
// === ここまで ===

let subscriptionId = ''

stripe.subscriptions.create({
  customer: customerId,
  items: [
    {
      plan: planId,
    }
  ],
}).then(subscription => {
  subscriptionId = subscription.id
  return stripe.subscriptions.retrieve(subscriptionId)
}).then(subscription=> {
  return stripe.subscriptionItems.create({
    subscription: subscriptionId,
    plan: option,
    quantity: 1
  })
})
.then(() => {
  return stripe.invoices.create({
    customer: customerId,
    subscription: subscriptionId
  })
})
.then(result => console.log(result))
.catch(err => console.log(err))

この場合も差額だけ1~2週間以内に請求するという決済が実現していました。

消費税の取り扱いに注意

ドキュメントに「subscriptionで設定したtax_percentはinvoice.createに自動反映されない」とあります。

When you manually generate an invoice, Stripe does not apply the taxesyou may have established on the subscription. If taxes should apply, manually add the tax on the invoice itself (as a flat amount or percent).

https://stripe.com/docs/subscriptions/invoices#generating-invoices

なので以下のようにtax_percentを設定するようにしましょう。

stripe.invoices.create({
    customer: customerId,
    subscription: subscriptionId,
    tax_percent: 8
})

2018/3/27補足：SubscriptionItems.createの場合

以下のようにstripe.subscriptionItems.create()した場合は元のsubscriptionの税率が適用される様子です。

stripe.subscriptionItems.create({
    subscription: subscriptionId,
    plan: option,
    quantity: 1
  })
}).then(() => {
  return stripe.invoices.create({
    customer: customerId,
    subscription: subscriptionId
  })

stripe.invoices.createでも以下のように税率を指定している場合でも、二重に課税されることはありませんので安心です。

stripe.invoices.create({
    customer: customerId,
    subscription: subscriptionId,
    tax_percent: 8
})

まとめ

subscriptions.update()またはsubscriptionItems.create()などでsubscriptionの内容を変更した場合、invoices.create({customer: 'CUSTOMER_ID', subscription: 'SUBSCRIPTION_ID'})で1~2週間以内に差額のみ決済させることが可能です。

逆にこれを実行しない場合、次回の請求サイクルに差額がのせられることとなりますので、年額プランを運用されている場合などは要注意です。