CompanyRecurringInvoices

Set the status of a recurring invoice

Sets the lifecycle status of a recurring invoice template. This is how generation is paused, resumed and ended.

  • PAUSED: stops automatic generation, keeping the schedule configuration intact.
  • ACTIVE: resumes generation. It keeps the scheduled next generation date whenever that date has not fallen due yet (including today), so resuming never re-issues a period you already invoiced and never undoes a skipped one. Only a date left in the past is rescheduled, to the first occurrence after today; the periods missed while the template was paused are not backfilled. If nothing is left to generate — the next generation date falls beyond end_date, or max_invoices has already been reached — the template becomes COMPLETED; for end_date that holds whether the date was kept or rescheduled.
  • COMPLETED: ends the schedule for good, from ACTIVE or PAUSED; it is also reached on its own when the schedule runs out. It is terminal: ACTIVE and PAUSED are then rejected with RECURRING_STATE_TRANSITION_INVALID.
  • Rejected transitions: resuming a template that is already active, or one whose pause.blocker is still in effect.
put/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/status

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/companies/{company_id}/recurring-invoices/{recurring_invoice_id}/status
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Idempotency key to prevent duplicates in sensitive operations.

  • Any unique client-generated string (e.g. an order id). A UUID also works but is not required
  • Allowed characters: letters, digits, _ and - (max 255 chars)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses expire 24 hours after processing

The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait for the Retry-After seconds (2) and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.

Request body

status'ACTIVE' | 'PAUSED' | 'COMPLETED' required

Target status. PAUSED stops automatic generation keeping the schedule; ACTIVE resumes it and keeps the scheduled next generation date whenever that date has not fallen due yet (including today), rescheduling only a date left in the past to the first occurrence after today; COMPLETED ends the schedule for good — valid from both ACTIVE and PAUSED.

COMPLETED is terminal: once there, ACTIVE and PAUSED are rejected with RECURRING_STATE_TRANSITION_INVALID. Ending also disarms the auto-emission timer of any draft this schedule had seeded; those drafts stay alive as regular drafts.

Example request

{
  "status": "PAUSED"
}

Response

Status applied successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "draft_in_advance": true,
    "status": "ACTIVE",
    "pause": {
      "reason": "GENERATION_FAILURE",
      "blocker": "NIF_NOT_REGISTERED"
    },
    "lines": [
      {
        "pricing_mode": "UNIT_PRICE",
        "total_excluding_tax": 1,
        "total_including_tax": 100,
        "exemption_reason": "EXENTA_ART_20"
      }
    ],
    "amount": 106,
    "custom_fields": [
      {
        "key": "project",
        "label": "Project",
        "value": "Corporate website"
      }
    ],
    "max_invoices": 6,
    "last_generated_scheduled_date": "2026-05-01"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.