v1

latestOpenAPI 3.1.02026-07-261420929.5 KB

Listar/Buscar Faturas

Retorna uma lista das faturas em sua conta ordenadas pela data de criação, da mais à menos recente. Por padrão, este endpoint retorna no máximo 100 registros. O campo "totalItems" contém sempre a quantidade total de faturas cadastradas, independentemente dos parâmetros de pesquisa utilizados, e o resultado da pesquisa fica sempre dentro de "items".

get/invoices

Query parameters

limitinteger

Limita o número de registros retornados em até 100, que é o padrão de retorno desta chamada. Também utilizado em <a href="https://dev.iugu.com/v1.0/reference#paginação">paginação</a>.

startinteger

Quantos registros pular do início da pesquisa, usado para paginação.

created_at_fromstring date-time

Registros criados a partir dessa data passada no parâmetro. Formato (AAAA-MM-DDThh:mm:ss-03:00)

created_at_tostring date-time

Registros criados até esta data passada no parâmetro. Formato (AAAA-MM-DDThh:mm:ss-03:00)

paid_at_fromstring date-time

Registros pagos a partir dessa data passada no parâmetro. Formato (AAAA-MM-DDThh:mm:ss-03:00)

paid_at_tostring date

Registros pagos até esta data passada no parâmetro. Formato (AAAA-MM-DDThh:mm:ss-03:00)

due_datestring date

Data de Vencimento (AAAA-MM-DD)

querystring

Neste parâmetro pode ser passado um texto para pesquisa como e-mail, nome, anotações e o order_id. Necessário usar a paginação (limit, start, etc)

updated_sincestring date-time

Registros atualizados desde o momento passado no parâmetro. Formato (AAAA-MM-DDThh:mm:ss-03:00)

customer_idstring

ID do Cliente

status_filterstring

Usado para filtrar as faturas pelo status (pending, paid, canceled, partially_paid, externally_paid, refunded, expired, authorized)

Response

200

totalItemsinteger

Example response

{
  "items": [
    {
      "id": "ACD03D71D16249BAB49FC89EB6F8516F",
      "due_date": "2025-04-07",
      "currency": "BRL",
      "email": "email@iugu.com",
      "status": "pending",
      "total_cents": 500,
      "payable_with": "credit_card",
      "updated_at": "2025-04-02T13:27:43-03:00",
      "account_id": "44C5DC6376804D1FA792CBCA382105C1",
      "account_name": "Nome da Conta",
      "secure_id": "acd03d71-d162-49ba-b49f-c89eb6f8516f-5fa4",
      "secure_url": "https://checkout.iugu.com/invoices/acd03d71-d162-49ba-b49f-c89eb6f8516f-5fa4",
      "total": "R$ 5,00",
      "taxes_paid": "R$ 0,00",
      "total_paid": "R$ 0,00",
      "total_overpaid": "R$ 0,00",
      "total_refunded": "R$ 0,00",
      "commission": "R$ 0,00",
      "fines_on_occurrence_day": "R$ 0,00",
      "total_on_occurrence_day": "R$ 0,00",
      "paid": "R$ 0,00",
      "bank_slip_extra_due": 10,
      "created_at": "02/04, 13:27",
      "created_at_iso": "2025-04-02T13:27:43-03:00",
      "items": [
        {
          "id": "14E870A66B4B46DA8947DB8661590009",
          "description": "Desc",
          "price_cents": 500,
          "quantity": 1,
          "created_at": "2025-04-02T13:27:43-03:00",
          "updated_at": "2025-04-02T13:27:43-03:00",
          "price": "R$ 5,00"
        }
      ]
    }
  ],
  "facets": {
    "late": {
      "_type": "filter"
    },
    "status": {
      "_type": "terms",
      "terms": [
        {
          "term": "expired",
          "count": 43
        }
      ],
      "total": 66
    }
  },
  "totalItems": 66
}