Customer object

The Customer object represent your customer and the API allows you to create, update and retrieve your customers. You can retrieve a list of all your customers as well retrieve an individual customer.

Attributes

---

id

string
The object unique identifier.

---

address

string
An address for this customer object.

---

aggregations

object
An object with balance, sales, sales_current_period fields. Each field represent a summary for financial state of this customer.

---

contacts

list
A list with many objects related to this customer.

---

country

string
Two-letter ISO code for the country of this customer. In list and retrieve API return calls a Country object.

---

currency

string
Three-letter ISO code for the currency of this customer.

---

email

string
A billing email address for this customer.

---

metadata

object
A set of free key-value pairs that you will can attach to this customer. This can be useful for storing additional information about the object in a structured format.

---

name

string
A name for this customer object.

---

phone

string
A phone number for this customer object.

---

sources

list
A list with many objects related to this customer.

---

state

string
Six-letter max Piriod code for the state of this customer. In list and retrieve API return calls a State object.

---

tax_id

string
A valid tax id for this customer.

---

tax_settings

string
A set of key-value pairs that represent the legal tax agency specifications for this customer.

---

website

string
A valid website url for this customer.

---

created

datetime
Date and time of the creation of this customer.

---

updated

datetime
Date and time of the last update of this customer.

---

Object sample

JSON

{
    "id": "cus_dl6PTxQnTYy5BHYskV",
    "address": "ACME ST 909A",
    "aggregations": {
        "sales": 3757.00,
        "sales_current_period": 457.00,
        "balance": 457.00
    },
    "contacts": [],
    "country": {
        "id": "US",
        "name": "Estados Unidos",
        "name_en": "United states",
        "phone_code": "+1",
        "has_regulation": false,
        "tax_percent": 10
    },
    "currency": "USD",
    "email": "[e-mail]",
    "metadata": {},
    "name": "ACME TEST LLC",
    "phone": "",
    "sources": [],
    "state": {
        "id": "USAZ",
        "code": "AZ",
        "name": "Arizona"
    },
    "tax_id": "897-56-9831",
    "tax_settings": {},
    "website": "",
    "created": "2020-10-15T13:26:15.356289-03:00",
    "updated": "2020-10-15T13:26:15.356321-03:00"
}

---

Tax Settings

The following corresponds to the definition of the fields used to define tax aspects specific to the different electronic invoicing regulations of each country.

Brasil

br_city_code string

City code. Must belong to the state; otherwise, the document will be subject to verification.

---

br_city_name string

The name of the city that was determined with the code.

---

br_tax_regime string

Customer tax regime code. You can see the codes in the table below.

Key	Description
Isento	Isento
MicroempreendedorIndividual	Micro empreendedor individual
SimplesNacional	Simples nacional
LucroPresumido	Lucro presumido
LucroReal	Lucro real

---

br_municipal_tax_number string optional

Municipal tax number assigned to the customer by the city council.

Example using attributes

jso

{
    "tax_settings": {
        "br_city_code": "1100122",
        "br_city_name": "Ji-Paraná",
        "br_tax_regime": "LucroPresumido",
        "br_municipal_tax_number": ""
    }
}

---

Chile

cl_activity_description string

Printed gloss indicating the recipient giro

Example using attributes

JSON

{
    "tax_settings": {
        "cl_activity_description": "Comercialización de productos"
    }
}

---

México

mx_tax_scheme string

Required for local customers. Customer tax regime code. You can see the codes in the table below.

Key	Description
601	General de Ley Personas Morales
603	Personas Morales con Fines no Lucrativos
605	Sueldos y Salarios e Ingresos Asimilados a Salarios
606	Arrendamiento
608	Demás ingresos
609	Consolidación
610	Residentes en el Extranjero sin Establecimiento Permanente en México
611	Ingresos por Dividendos (socios y accionistas)
612	Personas Físicas con Actividades Empresariales y Profesionales
614	Ingresos por intereses
616	Sin obligaciones fiscales
620	Sociedades Cooperativas de Producción que optan por diferir sus ingresos
621	Incorporación Fiscal
622	Actividades Agrícolas, Ganaderas, Silvícolas y Pesqueras
623	Opcional para Grupos de Sociedades
624	Coordinados
628	Hidrocarburos
607	Régimen de Enajenación o Adquisición de Bienes
629	De los Regímenes Fiscales Preferentes y de las Empresas Multinacionales
630	Enajenación de acciones en bolsa de valores
615	Régimen de los ingresos por obtención de premios
625	Régimen de las Actividades Empresariales con ingresos a través de Plataformas Tecnológicas
626	Régimen Simplificado de Confianza

Example using attributes

JSON

{
    "tax_settings": {
        "mx_tax_scheme": "601"
    }
}