Pause and resume recurring invoices in bulk

Pausing a batch of recurring invoices meant one call per template: POST /v1/recurring_invoices/{recurring_invoice}/pause for each id, with your own retry and error bookkeeping on top. Deleting in bulk already had POST /v1/recurring_invoices/bulk-delete; changing status did not.

POST /v1/recurring_invoices/bulk-status closes that gap with the same partial-success contract the other bulk status operations use.

The operation

curl -X POST https://api.factuarea.com/v1/recurring_invoices/bulk-status \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b" \
  -d '{
    "ids": [
      "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
      "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff"
    ],
    "new_status": "paused"
  }'

{
  "data": {
    "total": 3,
    "successful": 2,
    "failed": 1,
    "failures": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff",
        "error_code": "recurring_invoice_already_paused",
        "error_message": "Esta factura recurrente ya está pausada."
      }
    ]
  }
}

Nothing aborts the batch

paused pauses the active recurrences and active resumes the paused ones. Each id goes through the same single transition — and therefore the same guards — as POST /v1/recurring_invoices/{recurring_invoice}/pause and /resume, so a batch never applies a change the one-by-one route would have refused.

Ids that are not eligible come back in failures[] with their error_code while the rest of the batch is applied:

A body with more than 50 ids, duplicated ids or a new_status outside [active, paused] is rejected as a whole with 422 invalid_param_value before anything is applied.

New error code: recurring_invoice_completed_cannot_resume

422 recurring_invoice_completed_cannot_resume now names the case that used to arrive as a generic rule violation: a recurrence that has used up its occurrences or passed its end date is not resumed or activated. It is emitted inside failures[] by the bulk operation and as the response status of POST /v1/recurring_invoices/{recurring_invoice}/resume and /activate, whose contracts declare 422 from this release on. Create a new recurrence, or extend the occurrence count or end date of this one, before activating it.

MCP

bulk_change_recurring_invoice_status mirrors the operation: scope recurring_invoices:transition, category write, up to 50 ids and the same new_status. It returns the same counters and failures[], so an assistant can report what was applied and what was skipped. See the MCP tool catalog.

bulk_delete_recurring_invoices and the single-template operations are unchanged.