ReplacementsPrivate preview

Learn how to handle financing offer replacements.

The Capital financing application provides users the option to link third-party data to receive updated offer terms, such as a higher loan amount. When a user receives an offer with new terms, Stripe creates a financing offer replacement.

The following example illustrates how a user might receive a replacement offer:

Stripe creates an undelivered financing offer for the user with a maximum loan amount of $5,000.
Your platform sends the user an offer email and marks the offer as delivered.
The user navigates to the Capital financing application and links their bank account.
Stripe determines the user is eligible for a new maximum loan amount of $10,000.
Stripe replaces the user’s original $5,000 offer with a new $10,000 offer.

This guide covers how to handle offer replacements. It assumes you’ve completed the API set-up guide.

Beta

Replacements aren’t enabled by default for Capital API platforms. After updating your integration to support replacements, contact us to enable them.

Create a delivered offer in test mode

From the Dashboard, create a new financing offer with status delivered in test mode.

Replace the offer

Click the three dots menu at the end of the row corresponding to the delivered offer, and select the Replace offer option.

Note

Replace offer only appears for offers that have never been replaced before and have status undelivered or delivered.

Click Replace at the bottom of the modal to replace the offer.

Stripe sends the capital.financing_offer.replacement_created webhook after a replacement financing offer is created. The body of the webhook contains details about the replacement financing offer.

{
    "type": "capital.financing_offer.replacement_created",
    "data": {
        "object": {
            "id": "financingoffer_xyz456",
            "object": "capital.financing_offer",
            "account": "acct_efg678",
            "status": "delivered",
            "financing_type": "flex_loan",
            "offered_terms": {
                "currency": "usd",
                "advance_amount": 100000,
                "fee_amount": 10000,
                "withhold_rate": 0.15,
            },
            "replacement_for": "financingoffer_abc123",
            ...
        }
    }
}

Notice that the replacement offer has status delivered. When a user receives a replacement offer, it becomes their current active offer.

Update your webhook integration to handle the capital.financing_offer.replacement_created webhook. If your internal data models store the user’s active financing offer ID, make sure you update the ID to the user’s replacement offer.

Retrieve the replaced offer

After replacing the offer, you’re redirected to a page with details about the replacement offer. The events table contains an event Account acct_egg678 has a replacement financing offer for financingoffer_abc123, providing a reference to the user’s original offer ID.

Retrieve financingoffer_abc123. Notice that it has status replaced, and the replacement attribute has value financingoffer_xyz456, indicating that financingoffer_xyz456 replaced financingoffer_abc123.

{
  "id": "financingoffer_abc123",
  "object": "capital.financing_offer",
  "status": "replaced",
  "replacement": "financingoffer_xyz456",
  ...
}

Replaced is a terminal state. If the user accepts their replacement offer, all future offer state transitions affect the replacement offer.