Payment applicationÖffentliche Vorschau

You can use payment application to apply payments to open invoices or fix reconciliation mistakes. 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 toward an invoice.

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

• You can only unapply payments from invoices with collection_method = send_invoice.
• You can’t apply a portion of a payment toward an invoice. You can only apply an entire payment toward 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 need to update your integration before reopening a paid invoice. For example, if you rely on Stripe events to update 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 toward 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 view, you can unapply a payment and leave it unapplied, or you can reapply it to a different invoice.

You can only unapply payments in the Stripe Dashboard.

1. Go to the Payments section of the invoice you want to unapply a payment from.
2. Click the overflow menu () of the payment and click Manage application.
3. Choose whether to unapply the payment from the invoice, or unapply the payment and then apply it to another open 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 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.
• Your reopen the invoice 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

• 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.

Subscription status

For subscription invoices, unapplying a payment doesn’t affect the subscription status. 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, we don’t send any notifications to the customer directly. However, both the Hosted Invoice Page and the Customer Portal reflect the updated status of the invoice.

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, it triggers an invoice_payment.detached event. You can list the last 30 days of these events.

curl -G https://api.stripe.com/v1/events \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d 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.

curl -G https://api.stripe.com/v1/payment_intents/search \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode query="metadata['unapplied']:'true'"