---
title: "Send invoices in bulk"
description: "Emails many invoices to their customers in one job, as the Invoices page bulk send does: pick invoices by id, or by a created date range with optional status / link / document type. Returns 202 with a job id; GET /docume"
url: https://docs.invoicefalcon.com/v3-reference/documents/send-invoices-in-bulk/
api: "API v3 reference"
method: POST
path: "/documents/bulk/send"
---

# Send invoices in bulk

`POST https://app.invoicefalcon.com/api/v3/external/documents/bulk/send`

Emails many invoices to their customers in one job, as the Invoices page bulk send does: pick invoices by id, or by a created date range with optional status / link / document type. Returns 202 with a job id; [`GET /documents/bulk/:job_id`](https://docs.invoicefalcon.com/v3-reference/documents/retrieve-a-bulk-job/) reports which were sent.

**Note:** Sends emails to customers as soon as the job runs; there is no confirmation step. Refused when the shop cannot send email (email_sending_disabled). Only one bulk job may run per shop at a time (429 bulk_action_in_progress). Filtering needs both from and to.

## Request body

- `ids` (array of integers): Invoice ids to include. Without ids the list filters below select the invoices.
- `document_type` (string): Which documents when filtering: 'invoice' (default), 'quote', 'credit_note' or 'pro_forma'. One of: `invoice`, `quote`, `credit_note`, `pro_forma`.
- `link` (string): 'linked' (created from a Shopify order), 'not_linked' (standalone) or 'trashed'. One of: `linked`, `not_linked`, `trashed`.
- `status` (string): Shopify financial status of the order, one or many ('paid', 'pending').
- `from` (string): Created on or after this date (ISO 8601).
- `to` (string): Created on or before this date (ISO 8601).

## Returns

- `job_id` (integer): e.g. `10`
- `status` (string): e.g. `pending`
- `count` (integer): e.g. `0`
- `kind` (string): e.g. `send`

Rate limit: this call costs 2 points ([rate limits](https://docs.invoicefalcon.com/v3/docs/api-v3/rate-limits/)).

## Examples

### Email chosen invoices

```sh
curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/bulk/send" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      48213,
      48190
    ]
  }'
```

### Email every pending invoice from March

```sh
curl -X POST "https://app.invoicefalcon.com/api/v3/external/documents/bulk/send" \
  -H "X-Auth-Token: $INVOICE_FALCON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": [
      "pending",
      "partially_paid"
    ],
    "from": "2026-03-01",
    "to": "2026-03-31"
  }'
```

## 200

The updated resource.

```json
{
  "job_id": 10,
  "status": "pending",
  "count": 0,
  "kind": "send"
}
```

## 202

Accepted: the job was queued. Poll the returned job id for progress.

```json
{
  "job_id": 10,
  "status": "pending",
  "count": 0,
  "kind": "send"
}
```

## 401

Missing or unknown `X-Auth-Token`, or the shop uninstalled the app.

```json
{
  "errors": [
    "Invalid API key"
  ],
  "code": "unauthorized"
}
```

## 403

`v3_required`: the shop still runs the previous dashboard. `paid_plan_required`: API access needs a paid plan.

```json
{
  "errors": [
    "API access requires a paid plan"
  ],
  "code": "paid_plan_required"
}
```

## 422

The request failed validation. Nothing was saved.

```json
{
  "errors": [
    "id is missing"
  ]
}
```

## 429

Rate limited: cost-weighted per key (reads cost less than writes). Wait `Retry-After` seconds; see `X-RateLimit-*` headers.

```json
{
  "errors": [
    "Rate limit exceeded"
  ],
  "code": "rate_limited"
}
```

