Invoices

Send multiple invoices by email

Sends multiple invoices by email to the specified recipients. **Limits:** - Maximum 20 invoices per request - Maximum 25MB total attachment size **Email behavior:** - Single email with all PDFs as attachments - Uses BULK_INVOICES template **Validations:** - Invoices must have status ISSUED, PAID, SENT or OVERDUE (not DRAFT or VOIDED) - At least one recipient required (from request or user's accountant email) **Partial success:** If some invoices cannot be attached, the email will still be sent with available PDFs. Response includes `failures` array.

POST
/v1/invoices/bulk/send

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Request Body

invoice_idsarray<UUID>

List of invoice IDs to send

Items1 <= items <= 200
recipients?array<Email>

Email recipients. If not provided, uses accountant email from user profile.

cc?array<Email>

CC recipients

subject?string

Custom email subject. If not provided, uses default template.

Lengthlength <= 200
message?string

Custom message body. If not provided, uses default template.

Lengthlength <= 2000
language?string
Value in"es" | "en" | "ca"

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/invoices/bulk/send" \  -H "Content-Type: application/json" \  -d '{    "invoice_ids": [      "550e8400-e29b-41d4-a716-446655440001",      "550e8400-e29b-41d4-a716-446655440002"    ],    "recipients": [      "accountant@example.com"    ],    "subject": "Invoices for January 2025",    "message": "Please find attached the invoices from last month for your review."  }'
{
  "success": true,
  "data": {
    "email_id": "550e8400-e29b-41d4-a716-446655440000",
    "sent_to": [
      "user@example.com"
    ],
    "sent_at": "2019-08-24T14:15:22Z",
    "total_invoices": 0,
    "invoices_attached": 0,
    "failures": [
      {
        "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
        "error_code": "NOT_FOUND",
        "error_message": "string"
      }
    ]
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "field": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Send invoice by email POST

Sends the invoice by email to the customer. **Email:** Sent to the billing emails configured for the customer. **Attachments:** Includes the invoice PDF.

Cancel scheduled invoice POST

Cancels a scheduled invoice and converts it back to draft. **Status change:** `SCHEDULED` → `DRAFT` The invoice can then be edited or manually issued.