> ## Documentation Index
> Fetch the complete documentation index at: https://vatextract.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Upload

> Upload multiple invoices at once using a ZIP file

Process dozens of invoices in one go by uploading a ZIP file containing your PDFs and images.

## How It Works

<Steps>
  <Step title="Prepare Your ZIP">
    Gather your invoice files (PDFs, images) into a single ZIP archive. Nested folders are supported—VATextract will find all valid files inside.
  </Step>

  <Step title="Upload the ZIP">
    Go to **Dashboard → Upload** and select the **Bulk Upload** tab. Choose your ZIP file and click **Upload ZIP File**.
  </Step>

  <Step title="Automatic Processing">
    Each file is extracted, uploaded to secure cloud storage, and processed individually through the OCR pipeline. A progress bar tracks the overall upload.
  </Step>

  <Step title="Review Results">
    Once complete, you'll see a summary showing how many invoices were queued, skipped, or encountered errors. Processed invoices appear in your dashboard.
  </Step>
</Steps>

## Supported File Types

Files inside your ZIP can be any of the following formats:

| Format | Extensions      |
| ------ | --------------- |
| PDF    | `.pdf`          |
| JPEG   | `.jpg`, `.jpeg` |
| PNG    | `.png`          |
| GIF    | `.gif`          |
| WebP   | `.webp`         |
| BMP    | `.bmp`          |

<Info>
  Hidden files (dotfiles) and macOS system files (`__MACOSX`) are automatically skipped.
</Info>

## Upload Summary

After processing, you'll see a detailed breakdown:

| Status      | Description                                  |
| ----------- | -------------------------------------------- |
| **Queued**  | Successfully submitted for OCR processing    |
| **Skipped** | File was unsupported or a hidden/system file |
| **Error**   | Processing failed for this file              |

Files that are skipped or encounter errors include a reason so you can fix and re-upload if needed.

## Client Assignment

You can assign all invoices in a bulk upload to a specific client. Select a client from the dashboard before uploading, and every invoice in the ZIP will be tagged automatically.

## Usage Limits

Each invoice file inside the ZIP counts towards your monthly invoice limit. If you reach your plan's limit mid-upload, remaining files will not be processed.

<Warning>
  Check your remaining invoice allowance in **Dashboard → Usage** before uploading large ZIP files.
</Warning>

## Bulk Upload via API

You can also trigger bulk uploads programmatically:

<Steps>
  <Step title="Get a Signed URL">
    ```bash theme={null}
    POST /api/upload/signed-url
    Content-Type: application/json

    {
      "fileName": "invoices.zip",
      "fileType": "application/zip"
    }
    ```

    Returns a `signedUrl` and `gcsUri`.
  </Step>

  <Step title="Upload the ZIP to Cloud Storage">
    ```bash theme={null}
    PUT {signedUrl}
    Content-Type: application/zip

    [ZIP file binary data]
    ```
  </Step>

  <Step title="Trigger Processing">
    ```bash theme={null}
    POST /api/upload/bulk
    Content-Type: application/json
    Authorization: Bearer YOUR_TOKEN

    {
      "gcsUri": "gs://bucket/user/invoices.zip",
      "clientId": "client_abc123"
    }
    ```
  </Step>
</Steps>

### API Response

```json theme={null}
{
  "success": true,
  "summary": {
    "total": 15,
    "queued": 12,
    "skipped": 2,
    "errors": 1
  },
  "results": [
    {
      "fileName": "invoice-001.pdf",
      "status": "queued",
      "invoiceId": "inv_abc123"
    },
    {
      "fileName": ".DS_Store",
      "status": "skipped",
      "reason": "Hidden or system file"
    }
  ]
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Organise Before Upload" icon="folder-open">
    Remove non-invoice files from your ZIP to avoid unnecessary skips and speed up processing.
  </Card>

  <Card title="Check Your Limit" icon="gauge">
    Verify your remaining invoice allowance before bulk uploading to avoid partial processing.
  </Card>

  <Card title="Use Supported Formats" icon="file-image">
    Stick to PDF and high-resolution images for the best extraction accuracy.
  </Card>

  <Card title="Assign a Client" icon="user-tag">
    Select a client before uploading so all invoices are tagged automatically.
  </Card>
</CardGroup>