---
title: "Retrieve invoicing data for companies"
method: GET
path: "/v1/invoices/{invoice_period}"
tags: ["Invoices"]
---

# Retrieve invoicing data for companies

`GET /v1/invoices/{invoice_period}`

Retrieve data for active companies used to calculate invoices for Gusto Embedded Payroll. A company is considered active for an invoice period if they are an active partner managed company, have run payroll or created contractor payments since becoming a partner managed company, and are not suspended at any point during the invoice period.  This endpoint forces pagination, with 100 results returned at a time. You can learn more about our pagination here: [pagination guide](https://docs.gusto.com/embedded-payroll/docs/pagination)

📘 System Access Authentication

This endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)

scope: `invoices:read`

## Path parameters

- `invoice_period` string, required

## Query parameters

- `page` integer
- `per` integer
- `company_uuids` string

## Headers

- `X-Gusto-API-Version` '2026-06-15'

## Response `200`

OK

- InvoiceData — Representation of a partners invoice data
  - `active_companies` object[] — The list of companies that are active within the invoice period
    - `company_uuid` string — unique identifier for the company associated with the invoice data
    - `active_employees` integer — The number of active employees the company was or will be invoiced for that invoice period. Active employees are calculated as the count of onboarded employees hired before the end of the invoice period and not terminated before the start of the invoice period.
    - `active_contractors` integer — The number of active contractors the company was or will be invoiced for that invoice period. Active contractors are calculated as any contractor with an active contractor payment during the invoice period.
    - `initial_invoice_period` string — The first invoice period for the company. This will either be the invoice period of the first invoice-able event (first payroll or contractor payment) or the date they migrated to embedded, whichever is later.

## Other responses

- `422` — Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)