Create a customer

Route

POST

/api/v1/customers

Usage

Curl

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/customers" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "customer": {
      "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "address_line1": "5230 Penfield Ave",
      "address_line2": "",
      "city": "Woodland Hills",
      "country": "US",
      "currency": "EUR",
      "email": "dinesh@piedpiper.test",
      "legal_name": "Coleman-Blair",
      "legal_number": "49-008-2965",
      "logo_url": "http://hooli.com/logo.png",
      "name": "Gavin Belson",
      "phone": "1-171-883-3711 x245",
      "state": "CA",
      "timezone": "Europe/Paris",
      "url": "http://hooli.com",
      "zipcode": "91364",
      "billing_configuration": {
        "invoice_grace_period": 3,
        "payment_provider": "stripe",
        "provider_customer_id": "cus_12345",
        "sync": true,
        "sync_with_provider": true,
        "document_locale": "fr",
        "vat_rate": 12.5
      },
      "metadata": [
        {
          "key": "Name",
          "value": "John",
          "display_in_invoice": true
        }
      ]
    }
  }'

Python

from lago_python_client import Client
from lago_python_client.models import Customer, CustomerBillingConfiguration

client = Client(api_key='__YOUR_API_KEY__')

metadata_object = Metadata(
  display_in_invoice=True,
  key='key',
  value='value'
)

customer = Customer(
  external_id="5eb02857-a71e-4ea2-bcf9-57d8885990ba",
  address_line1="5230 Penfield Ave",
  address_line2=None,
  city="Woodland Hills",
  currency="EUR",
  country="US",
  email="test@example.com",
  legal_name="Coleman-Blair",
  legal_number="49-008-2965",
  logo_url="http://hooli.com/logo.png",
  name="Test Name",
  phone="1-171-883-3711 x245",
  state="CA",
  timezone="Europe/Paris",
  url="http://hooli.com",
  zipcode="91364",
  billing_configuration=CustomerBillingConfiguration(
    invoice_grace_period=3,
    payment_provider="stripe",
    provider_customer_id="cus_12345",
    sync=true,
    sync_with_provider=true,
    document_locale="fr",
    vat_rate=12.5
  ),
  metadata=MetadataList(__root__=[metadata_object])
)

client.customers().create(customer)

Node.js

import Client from 'lago-nodejs-client'
import Customer from 'lago-nodejs-client/customer'
import CustomerBillingConfiguration from 'lago-nodejs-client/customer_billing_configuration'

let client = new Client('__API_KEY__')

let customer = new Customer(
  "5eb02857-a71e-4ea2-bcf9-57d8885990ba",  // externalId
  None,  // addressLine1
  None,  // addressLine2
  None,  // city
  None,  // country
  "EUR", // currency
  "test@example.com",  // email
  None,  // legalName
  None,  // legalNumber
  None,  // lagoUrl
  "test name",  // name
  None,  // phone
  None,  // state
  "Europe/Paris", // timezone
  None,  // url
  None,  // zipcode
  new CustomerBillingConfiguration(
    3,  // invoiceGracePeriod
    "stripe",  // paymentProvider
    "cus_12345",  // providerCustomerId
    true,  // sync
    true, // syncWithProvider
    "fr", // documentLocale
    None  // vatRate
  ),
  [
    new CustomerMetadata({
      key: 'key',
      value: 'value',
      displayInInvoice: true
    })
  ]
)
await client.createCustomer(customer);

Ruby

require 'lago-ruby-client'

client = Lago::Api::Client.new({api_key: '__YOUR_API_KEY__'})

client.customers.create(
  external_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
  address_line1: "5230 Penfield Ave",
  address_line2: nil,
  city: "Woodland Hills",
  country: "US",
  currency: "EUR",
  email: "dinesh@piedpiper.test",
  legal_name: "Coleman-Blair",
  legal_number: "49-008-2965",
  logo_url: "http://hooli.com/logo.png",
  name: "Gavin Belson",
  phone: "1-171-883-3711 x245",
  state: "CA",
  timezone: "Europe/Paris",
  url: "http://hooli.com",
  zipcode: "91364",
  billing_configuration: {
    invoice_grace_period: 3,
    payment_provider: "stripe",
    provider_customer_id: "cus_12345",
    sync: true,
    sync_with_provider: true,
    document_locale: "fr",
    vat_rate: 12.5
  },
  metadata: [
    {
      key: 'key',
      value: 'value',
      display_in_invoice: true
    }
  ]
)

Go

  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

    customerInput := &lago.CustomerInput{
      ExternalID:   "__YOUR_CUSTOMER_ID__",
      Name:         "Customer",
      Email:        "customer@getlago.com",
      AddressLine1: "Address Line 1",
      AddressLine2: "Address Line 2",
      City:         "Paris",
      Country:      "France",
      Currency:     "EUR",
      State:        "Paris",
      Zipcode:      "75001",
      LegalName:    "GetLago",
      LegalNumber:  "123456",
      Phone:        "+330100000000",
      Timezone:     "Europe/Paris",
      URL:          "https://getlago.com",
      BillingConfiguration: &CustomerBillingConfigurationInput{
        InvoiceGracePeriod: 3,
        PaymentProvider: lago.PaymentProviderStripe,
        ProviderCustomerID: "__STRIPE_CUSTOMER_ID__",
        SyncWithProvider: true,
        DocumentLocale: "fr",
        VatRate: 20.0
      },
      Metadata: [
        &CustomerMetadataInput{
          Key: "Key",
          Value: "Value",
          DisplayInInvoice: true
        }
      ]
    }

    customer, err := lagoClient.Customer().Create(customerInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // You can use the same input to update the customer
    customer, err := lagoClient.Customer().Update(customerInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // customer is *lago.Customer
    fmt.Println(customer)
  }

C#

using System.Collections.Generic;
using System.Diagnostics;
using Org.OpenAPITools.Api;
using Org.OpenAPITools.Client;
using Org.OpenAPITools.Model;

namespace Example
{
  public class CreateCustomerExample
  {
      public static void Main()
      {
          Configuration.Default.BasePath = "https://api.getlago.com/api/v1";
          // Configure HTTP bearer authorization: bearerAuth
          Configuration.Default.AccessToken = "YOUR_ACCESS_TOKEN";

          var apiInstance = new CustomersApi(Configuration.Default);
          var customerInput = new CustomerInput(); // CustomerInput | Customer payload

          try
          {
              // Create a customer
              Customer result = apiInstance.CreateCustomer(customerInput);
              Debug.WriteLine(result);
          }
          catch (ApiException e)
          {
              Debug.Print("Exception when calling CustomersApi.CreateCustomer: " + e.Message );
              Debug.Print("Status Code: "+ e.ErrorCode);
              Debug.Print(e.StackTrace);
          }
      }
  }
}

PHP

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Bearer authorization: bearerAuth
$config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');


$apiInstance = new OpenAPI\Client\Api\CustomersApi(
  // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
  // This is optional, `GuzzleHttp\Client` will be used as default.
  new GuzzleHttp\Client(),
  $config
);
$customer_input = new \OpenAPI\Client\Model\CustomerInput(); // \OpenAPI\Client\Model\CustomerInput | Customer payload

try {
  $result = $apiInstance->createCustomer($customer_input);
  print_r($result);
} catch (Exception $e) {
  echo 'Exception when calling CustomersApi->createCustomer: ', $e->getMessage(), PHP_EOL;
}

Arguments

{
  "customer": {
    "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "address_line1": "5230 Penfield Ave",
    "address_line2": null,
    "city": "Woodland Hills",
    "country": "US",
    "currency": "EUR",
    "email": "dinesh@piedpiper.test",
    "legal_name": "Coleman-Blair",
    "legal_number": "49-008-2965",
    "logo_url": "http://hooli.com/logo.png",
    "name": "Gavin Belson",
    "phone": "1-171-883-3711 x245",
    "state": "CA",
    "timezone": "Europe/Paris",
    "url": "http://hooli.com",
    "zipcode": "91364",
    "billing_configuration": {
      "invoice_grace_period": 3,
      "payment_provider": "stripe",
      "provider_customer_id": "cus_12345",
      "sync": true,
      "sync_with_provider": true,
      "document_locale": "fr",
      "vat_rate": 12.5
    },
    "metadata": [
      {
        "key": "Key example",
        "value": "Value example",
        "display_in_invoice": true
      }
    ]
  }
}

info

If the customer already exists, this request will trigger an update.

Attributes	Type	Description
external_id	String      Required	Customer unique identifier in your application
address_line1	String      Optional	First line of the billing address
address_line2	String      Optional	Second line of the billing address
city	String      Optional	City of the customer's billing address
country	String      Optional ISO 3166 (alpha-2)	Country code of the customer's billing address
currency	String      Optional ISO 4217	Currency of the customer - learn more
email	String      Optional	Email of the customer
legal_name	String      Optional	Legal company name of the customer
legal_number	String      Optional	Legal company number of the customer
logo_url	String      Optional	Logo URL of the customer
name	String      Optional	Full name of the customer
phone	String      Optional	Phone number of the customer
state	String      Optional	State of the customer's billing address
timezone	String      Optional TZ database	Timezone of the customer - learn more Will override the organization's timezone
url	String      Optional	Custom URL of the customer
zipcode	String      Optional	Zipcode of the customer's billing address
billing_configuration	Object      Optional	Payment provider specific configuration used to bill the customer

Billing configuration

Attributes	Type	Description
invoice_grace_period	Integer      Optional	Grace period in days for the invoice.
payment_provider	String      Optional	Payment provider used to bill the customer. Accepted values: stripe and gocardless This field is required if you want to assign a provider_customer_id
provider_customer_id	String      Optional	Customer ID on the payment provider. If not provided, Lago can optionally create the provider customer
sync	Boolean      Optional	Set to true is you want to create the provider customer synchronously with the customer creation. Apply only when provider_customer_id is null and payment provider is configured to create customer. Default value: false
sync_with_provider	Boolean      Optional	Set to true if you want to create the customer record in the provider's system. Only applies when provider_customer_id is null and sync_with_provider is set to true. Default value: false
document_locale	String      Optional	Document locale in ISO 639-1 format - learn more
vat_rate	Float      Optional	Custom VAT applied to the customer. It will override the one defined at organization level

Metadata

Attributes	Type	Description
key	String      Optional	Metadata object key
value	String      Optional	Metadata object value
display_in_invoice	Boolean      Optional	Field that determines whether the metadata key-value pair will be visible on invoices

Responses

HTTP 200

The customer was succesfuly created or updated.

Returns a customer object.

HTTP 400

{
  "status": 400,
  "error": "Bad Request"
}

The customer json root is not present in the request body.

HTTP 401

{
  "status": 401,
  "error": "Unauthorized"
}

Access to the API endpoint is unhautorized.

Possible reasons are:

• The Authorization header is missing
• The Authorization header does not contain the API key
• The Api key is invalid or expired

HTTP 422

{
  "status": 422,
  "error": "Unprocessable entity",
  "code": "validation_errors",
  "error_details": {
    "field": ["error"]
  }
}

Possible errors:

field	error	description
external_id	value_is_mandatory	external_id is missing
country	not_a_valid_country_code	Provided country value is not an ISO 3166 country code
currency	value_is_invalid	Provided currency is not an accepted currency
currency	currencies_does_not_match	Provided currency cannot be assigned to the customer as he already has a subscription, an add_on, a coupon or a wallet in an other currency.
invoice_grace_period	value_is_out_of_range	Provided invoice grace period is invalid. It must be a positive integer.
payment_provider	value_is_invalid	Provided payment provider is invalid
timezone	timezone_invalid	Provided timezone is invalid
vat_rate	value_is_out_of_range	Provided VAT rate is invalid. It must be a positive integer or floating number between 0 and 100.