API Reference
Start typing to search…

Invoice object

Invoices are the record of payments made or due by a client, these can be generated by a subscription or uniquely.

Invoice object atributes

id

string
Unique object's identifier.

customer

string
The ID of the customer who will be billed. In read resources this field is expandable, returns the customer object.

number

number
A unique, identifying number that appears on invoice header sent to the customer of this invoice. It's automatically assigned.

document

string
The ID of the document type for this invoice. Learn more about

test_mode

boolean
Has the value true if the object exists in production mode or the value false if the object exists in test mode.

date

date
Closing date of the invoice. Typically this is the date on which invoice is generated.

due_date

date
Due date of the invoice.

lines

list
The list of line items for this invoice.

payments

list
The list of transactions for this invoice.

amount

decimal
Taxable subtotal of this invoice.

exempt

decimal
Non taxable subtotal of this invoice.

tax

decimal
Tax amount of this invoice.

tax_percent

decimal
Tax rate for this invoice.

subtotal

decimal
Sum of amount and exempt of this invoice.

total

decimal
Sum of subtotal and taxes of this invoice.

discount

decimal
Discount amount applicable to subtotal of this invoice.

discount_scheme

string
Scheme of the discount, one of $ or %.

period_start

date
The time when the service period for the billing starts.

period_end

date
The time when the service period for the billing ends.

collection_method

string
Method to collect payments of this invoice, one of automatically, deferred or deferred_dues.

local_file

url
URL to local format when document type of this invoice belong to a tax agency.

note

string
A note for the customer of this invoice.

references (optional)

A list of references objects Reference object

fiscal_settings

object
An object with key pairs for tax agency.

subscription

string
The id of subscription if this invoice was created by a subscription.

status

string
Status of this invoice, one of draft, finalized or paid. Learn more about

metadata

object
An object with key pairs for store custom information about this invoice.

user

string
Email of the user that created this invoice.

created

datetime
Date and time of the creation of this invoice.

Invoice object example

{
  "id": "inv_XsTY9J7C12iAD9Zc1J",
  "customer": {
    "id": "cus_APxT9s7X12ilP9Zx9O",
    "name": "Acme Nation LLC",
    "address": "17st, National Sub",
    "state": "IL",
    "country": "US",
    "phone": null,
    "email": "billing@stark.com",
    "website": "https://www.stark.com"
    "tax_settings": {},
    "metadata": {},
    "created": "2020-05-12 15:42:09",
    "updated": "2020-05-12 21:16:12"
  },
  "document": {
    "id": "US1",
    "name": "Invoice",
    "country": "US",
    "currency": "USD"
  },
  "number": 10923,
  "test_mode": false,
  "date": "2020-06-17",
  "due_date": "2020-07-12",
  "lines": [
    {
      "id": "lin_APxT9s7X12ilP9Zx9O",
      "name": "Acme App",
      "description": "Software services",
      "quantity": 4.0,
      "discount": 10.0
      "discount_scheme": "%"
    },
    ...
  ],
  "collection_method": "deferred_dues",
  "payments": [
    {
      "id": "pay_APxT9s7X12ilP9Zx9O",
      "amount": 50.5,
      "currency": "USD",
      "date": "2020-06-30",
      "description": "Invoice Nº 10923"
      "source": null,
      "payment_date": null,
      "customer": "cus_APxT9s7X12ilP9Zx9O",
      "invoice": "inv_XsTY9J7C12iAD9Zc1J",
      "status": "requires_payment_method",
      "metadata": {},
      "created": "2020-06-17 14:21:32",
      "updated": "2020-06-17 14:21:32"
    },
    ...
  ],
  "amount": 100.50,
  "exempt": 0,
  "tax": 0,
  "tax_percent": 0,
  "subtotal": 100.50,
  "discount": 10.0,
  "discount_scheme": "$",
  "total": 90.50,
  "period_start": null,
  "period_end": null,
  "local_file": null,
  "note": "Hint: Chargeable to 2020-07-12",
  "fiscal_settings": {},
  "status": "finalized",
  "metadata": {},
  "user": "tony@stark.com",
  "created": "2020-06-17 14:21:32",
  "updated": "2020-06-17 14:21:32"
}

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

There are no special regulatory fields for this country.

Chile

cl_payment_type string

Indicates the type of payment with which the invoice transaction is made. Default is credit 2. You can see the codes in the table below.

KeyDescription
1Contado
2Crédito
3Sin costo (entrega gratuita). Una factura de este tipo no es elegible para crédito fiscal.

México

mx_cfdi_use string

CFDI usage code according to the SAT catalog. You can see the codes in the table below. For global invoices, enter code S01.

KeyDescriptionTax regime
G01Adquisición de mercancías.601, 603, 606, 612, 620, 621, 622, 623, 624, 625,626
G02Devoluciones, descuentos o bonificaciones.601, 603, 606, 612, 620, 621, 622, 623, 624, 625,626
G03Gastos en general.601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
I01Construcciones.601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
I02Mobiliario y equipo de oficina por inversiones.601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
I03Equipo de transporte.601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
I04Equipo de computo y accesorios.601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
I05Dados, troqueles, moldes, matrices y herramental.601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
I06Comunicaciones telefónicas.601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
I07Comunicaciones satelitales.601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
I08Otra maquinaria y equipo.601, 603, 606, 612, 620, 621, 622, 623, 624, 625, 626
D01Honorarios médicos, dentales y gastos hospitalarios.605, 606, 608, 611, 612, 614, 607, 615, 625
D02Gastos médicos por incapacidad o discapacidad.605, 606, 608, 611, 612, 614, 607, 615, 625
D03Gastos funerales.605, 606, 608, 611, 612, 614, 607, 615, 625
D04Donativos.605, 606, 608, 611, 612, 614, 607, 615, 625
D05Intereses reales efectivamente pagados por créditos hipotecarios (casa habitación).605, 606, 608, 611, 612, 614, 607, 615, 625
D06Aportaciones voluntarias al SAR.605, 606, 608, 611, 612, 614, 607, 615, 625
D07Primas por seguros de gastos médicos.605, 606, 608, 611, 612, 614, 607, 615, 625
D08Gastos de transportación escolar obligatoria.605, 606, 608, 611, 612, 614, 607, 615, 625
D09Depósitos en cuentas para el ahorro, primas que tengan como base planes de pensiones.605, 606, 608, 611, 612, 614, 607, 615, 625
D10Pagos por servicios educativos (colegiaturas).605, 606, 608, 611, 612, 614, 607, 615, 625
S01Sin efectos fiscales.601, 603, 605, 606, 608, 610, 611, 612, 614, 616, 620, 621, 622, 623, 624, 607, 615, 625, 626
CP01Pagos601, 603, 605, 606, 608, 610, 611, 612, 614, 616, 620, 621, 622, 623, 624, 607, 615, 625, 626
CN01Nómina605

mx_payment_form string

Code representing the payment method, according to the SAT catalog. You can see the codes in the table below.

KeyDescription
01Efectivo
02Cheque nominativo
03Transferencia electrónica de fondos
04Tarjeta de crédito
05Monedero electrónico
06Dinero electrónico
08Vales de despensa
12Dación en pago
13Pago por subrogación
14Pago por consignación
15Condonación
17Compensación
23Novación
24Confusión
25Remisión de deuda
26Prescripción o caducidad
27A satisfacción del acreedor
28Tarjeta de débito
29Tarjeta de servicios
30Aplicación de anticipos
31Intermediario pagos
99Por definir

Example using attributes

{
    "tax_settings": {
        "mx_cfdi_use": "G03",
        "mx_payment_form": "99"
    }
}

Updated 21 days ago

Did this page help you?

Updated 21 days ago

Did this page help you?