Payment applicationPrivate Vorschau

You can apply payments to open invoices or fix reconciliation mistakes with payment application. If you use Stripe Invoicing or Stripe Billing and receive payments by bank transfer, check, or outside of Stripe, you might need to manually apply or unapply payments to or from invoices. You can also collect a payment without using an invoice, and then apply the payment towards an invoice.

Before applying or unapplying a payment to or from an invoice, consider the following:

• You can’t apply a portion of a payment towards an invoice. You can only apply an entire payment towards an invoice, which means you can’t apply a payment across multiple invoices.
• If parts of your integration with Stripe assume that an invoice can’t be reopened, evaluate whether you should update your integration before reopening a paid invoice. For example, if your integration has a downstream accounting system, confirm whether your integration is ready to handle an invoice being reopened.
• The Stripe Connector for NetSuite doesn’t support payment application on invoices. If you use the connector and you reopen an invoice, the connector won’t reopen the invoice in NetSuite.

Apply a payment to an invoice

You can apply any payment to an invoice if the payment amount is less than or equal to the unpaid balance on the invoice, and the invoice is for the same customer as the payment. If you apply a payment that fully pays the invoice, the status moves to paid.

You can’t apply part of a payment towards a single invoice. For example, you can’t use a single payment to pay multiple invoices. However, if a payment was created from a Bank Transfer, you can refund the payment to the cash balance and then apply the funds across different invoice amounts.

Disable auto-reconciliation before you refund the payment to the cash balance, to prevent reconciling the balance towards an invoice.

Unapply a payment from an invoice

From the invoice detail view, under the Payments section, you can manage payment application. In this flow, you can unapply a payment and leave it unapplied, or you can reapply it to a different invoice.

After you unapply a payment from an invoice, the status moves back to open. The invoice shows as Open, Past Due, Partially Paid, or Failed (for auto-charge invoices) in the Dashboard.

Automatic collection

After you reopen an invoice, automatic collection is off by default. You can expect the following behavior when you reopen an invoice:

You can turn on automatic collection to resume sending reminders, retrying failed payments, or changing invoice and subscription statuses based on your settings.

Automatic collection examples

The examples below illustrate different scenarios for turning on automatic collection for a reopened invoice.

Example 1

• You send a one-off invoice for payment that’s due January 1, and the customer pays on January 1.
• You configure the customer email settings to send a reminder 3 days past the due date, 5 days past the due date, and 14 days past the due date.
• The invoice is reopened on January 10 and automatic collection is turned on (auto_advance = true).
• A reminder is sent on day 14, if the customer hasn’t paid the invoice yet.

Example 2

• A one-off invoice charged automatically on January 1 was successfully paid Jan 1.
• The retry schedule is normally 8 Smart Retries over 14 days.
• The invoice is reopened on January 7 and automatic collection is turned on (auto_advance = true).
• Smart Retries schedules retries between January 7 and January 14.

Example 3

• You send a subscription invoice for payment that’s due January 1, and the customer pays on January 1.
• You configure the customer email settings to send a reminder 3 days past the due date, 5 days past the due date, and 14 days past the due date.
• You configure the subscription settings to cancel the subscription and mark the invoice as uncollectible, if the invoice is past due for 30 days.
• The invoice is reopened on January 7 and automatic collection is turned on (auto_advance = true).
• A reminder is sent on day 14, if the customer hasn’t paid the invoice yet.
• On day 30, the subscription is cancelled and the invoice marked uncollectible, if the customer hasn’t paid the invoice yet.

Example 4

• A subscription invoice charged automatically on January 1 was successfully paid Jan 1.
• The retry schedule is normally 8 Smart Retries over 14 days.
• You configure the subscription settings to cancel the subscription and mark the invoice as uncollectible, if all retries are exhausted.
• The invoice is reopened on January 7 and automatic collection is turned on (auto_advance = true).
• Smart Retries schedules retries between January 7 and January 14.
• On day 14, the subscription is cancelled and the invoice marked uncollectible, if the customer hasn’t paid the invoice yet.

Subscription status

For subscription invoices, the subscription status isn’t affected by unapplying a payment. However, if you turn on automatic collection (auto-advance=true), any final dunning actions in your recovery settings take effect based on the date that the invoice became overdue.

Notifications

When you reopen an invoice, no notifications are sent to the customer directly. However, the updated status of the invoice is correctly reflected on the Hosted Invoice Page and in the Customer Portal.

Learn about revenue recognition impacts.

Find unapplied payments

Any payment that isn’t applied to an invoice is considered unapplied. If you previously detached payments and want to confirm that all payments are correctly applied to invoices, you can find unapplied payments using the API.

When a payment detaches from an invoice, an invoice_payment.detached event is triggered. You can list the last 30 days of these events.

stripe events list --type=invoice_payment.detached

If you use Sigma or the Stripe Data Pipeline, you can find payments that aren’t applied to an invoice in the Invoice Payments table or the Payments table.

Track unapplied payments

To track all unapplied payments without using the Stripe Dashboard, build an integration that listens to the detach event and uses metadata to stamp unapplied payments.

Set up webhook events

To track unapplied invoice payments, listen for specific webhook events related to invoice payments and flag it on the payment.

# Handler for webhook events
def webhook_handler(event)
  # Payment was detached
  if event.type == "invoice_payment.detached"
    invoice_payment = event.data.object
    payment_intent = invoice_payment.payment.payment_intent

    # Update metadata to track this
    Stripe::PaymentIntents.update(payment_intent, {
      metadata: {
        unapplied: true,
        unapplied_from: invoice_payment.invoice,
      }
    })
  else
    # Handle other event types if necessary
  end
end

Apply or reapply invoice payments

When you apply or reapply invoice payments, make sure you clear the unapplied status from the PaymentIntent.

Attach the PaymentIntent to the invoice

curl https://api.stripe.com/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/attach_payment \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent=pi_3MvUdLLkdIwHu7ix1nItxHNQ

Clear the unapplied metadata field

curl https://api.stripe.com/v1/payment_intents/pi_3MvUdLLkdIwHu7ix1nItxHNQ \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "metadata[unapplied]"=false \
  -d "metadata[unapplied_from]"=

Render unapplied invoice payments

Use the Search API to list any unapplied invoice payments, and display them as needed in your UI.

def render_unapplied_payments
  unapplied_payments = Stripe::PaymentIntents.search({
    query: "metadata['unapplied']:'true'"
  })

  unapplied_payments.each do |unapplied_payment|
    render :unapplied_payment,
           payment_intent: unapplied_payment.payment.payment_intent,
           unapplied_from: unapplied_payment.metadata.unapplied_from
  end
end