Why a customer's payment method change won't sync to Stripe

You update a customer's provider_payment_methods through the API (for example switching from card to customer_balance for bank transfers), but Lago keeps showing the old value or the change never reaches Stripe. The usual cause is a broken Stripe link: the customer's provider_customer_id is blank, so Lago can no longer sync anything to Stripe for that customer. A common way this happens is a prior customer upsert that sent provider_customer_id with an empty string value ("") rather than omitting the field.

How the Stripe link works

When a Lago customer is connected to Stripe, the connection is held by the provider_customer_id stored in the customer's billing configuration. With sync_with_provider set to true, changes you make in Lago (such as the payment method) are pushed to the corresponding Stripe customer. If provider_customer_id is empty, that link is severed: updates may still change the value in Lago, but they have nowhere to sync to on the Stripe side, so Stripe keeps behaving as before.

How to confirm the cause

Check the customer's billing configuration, either by fetching the customer through the API or by reading the customer.updated entry in the customer's Activity logs tab. Look at two fields together:

• provider_customer_id: if this is null or empty while payment_provider is still stripe, the link is broken.

• provider_payment_methods: the value here may have reverted (for example back to card) if an earlier payload reset it.

If you have access to the API request logs, look for a recent customer payload that included "provider_customer_id": "". That empty value is what breaks the link.

How to resolve the issue

Relink the customer to Stripe with a customer upsert that supplies the real Stripe customer ID, then set the payment method you want in the same call:

{
  "customer": {
    "external_id": "<lago_external_customer_id>",
    "billing_configuration": {
      "payment_provider": "stripe",
      "payment_provider_code": "<lago_stripe_connection_code>",
      "provider_customer_id": "<stripe_customer_id>",
      "sync_with_provider": true,
      "provider_payment_methods": ["<desired_payment_methods>"]
    }
  }
}

After this, the customer's information tab should reflect the correct payment method (for example "Bank Transfers") and sync should resume.

How to prevent this from happening again

When upserting a customer, omit provider_customer_id entirely rather than sending it as an empty string, and omit provider_payment_methods unless you actually intend to change it. Sending an empty provider_customer_id while sync_with_provider is true can also cause Lago to create a new, duplicate Stripe customer, so dropping the field from the payload when you are not changing it is the safest pattern.

A note on reconciliation after a broken link

While the link is severed, there is no automatic path back from Stripe. Bank transfers may still reach Stripe (for instance because the IBAN is unchanged), but Lago never receives confirmation, so those invoices stay unpaid in Lago and have to be settled with manually recorded payments. Relinking the customer is what restores automatic reconciliation going forward.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.