Why a Stripe customer ID is not linking when creating a customer via the API

When creating a customer via the Lago API or SDK and wanting to link a preexisting Stripe customer ID, the correct field is billing_configuration.provider_customer_id. The integration_customers array is unrelated to Stripe and will not establish a payment provider link.

How it works

Lago uses two separate customer fields that look parallel in the schema but serve entirely different purposes. billing_configuration contains payment provider settings including provider_customer_id, which links the Lago customer to an external payment provider like Stripe. integration_customers is an array for accounting, tax, and CRM integrations. Specifically, netsuite, okta, anrok, avalara, xero, hubspot, and salesforce. Stripe is not a valid value in integration_customers and will not be processed as a payment provider link if placed there.

How to resolve the issue

Pass the Stripe customer ID under billing_configuration:

{
  "customer": {
    "external_id": "your_customer_id",
    "billing_configuration": {
      "payment_provider": "stripe",
      "provider_customer_id": "cus_xxxxxx"
    }
  }
}

If a customer was created with integration_customers containing a Stripe ID, the Stripe link was not established. Update the customer with the correct billing_configuration structure to set it properly.

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