Invoices

Create a recurring invoice from an invoice

Create a recurring invoice template that reuses the lines, client, and series of an existing invoice, applying the cadence (frequency, start date, optional end date and limits) supplied in the body. Returns the new recurring invoice.

post/companies/{company}/invoices/{invoice}/create-recurring

Request

  • Base URL: https://api.factuarea.com/v1
  • URL: https://api.factuarea.com/v1/companies/{company}/invoices/{invoice}/create-recurring
  • Auth: one of:
    • HTTP bearer
    • API key in header X-API-Key

Path parameters

companystring uuid required

Public identifier (UUID v7) of the company. Get it from GET /v1/me (data.scope[].id).

invoicestring uuid required

Public identifier (UUID v7) of the invoice.

Headers

Idempotency-Keystring
Example:01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 422 idempotency_key_reused; the values of secret fields (password, secret…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the Idempotency guide.

Factuarea-Versionstring date
Example:2026-06-01

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Request body

frequency'daily' | 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'semiannual' | 'yearly' required
start_onstring date required
end_onstring date nullable
namestring nullable
descriptionstring nullable
notesstring nullable
metadataMetadata nullable

A free map of up to 50 key→value pairs for storing arbitrary structured data (values are strings up to 500 characters). Unlike custom_fields — an ordered list of typed {field, value} pairs with display semantics, present on the six document resources — metadata is an unordered map for opaque integration data; a document may carry both. The master resources (Client, Supplier) have no custom_fields, so their metadata doubles as the custom-fields store.

Reserved keys (read-only). When the system auto-issues an invoice from a payment correlation (Stripe/GoCardless/MONEI), it writes stripe_subscription_id, stripe_invoice_id, billing_reason, period_start and period_end into that invoice metadata automatically. Do not set or overwrite them by hand — the platform owns them and a manual value may be replaced when the correlation runs.

holiday_handlingstring nullable
days_before_dueinteger nullable
max_occurrencesinteger nullable
generation_mode'draft' | 'issue' | 'issue_and_send' | 'null' nullable

What each run of the recurrence does with the invoice it generates: draft leaves it as a draft; issue issues it (definitive number, VeriFactu record, stock movements) without emailing it; issue_and_send issues it and emails it to the auto_delivery recipients. Any other value is rejected with 422. Optional and nullable: when omitted (or null) the mode is derived from send_automatically (true → issue_and_send, false or absent → draft). When sent, it takes precedence and send_automatically becomes a derived field (true only with issue_and_send); sending a send_automatically (top-level or inside auto_delivery) that contradicts it is rejected with 422. Recipients are only required with issue_and_send: if an auto_delivery object is configured, auto_delivery.recipients must then contain at least one address (422 auto_delivery_recipients_required otherwise); draft and issue send no email and need none. Available in every API version.

Example request

{
  "metadata": {
    "erp_code": "IVA-GEN",
    "ledger_account": "477000"
  }
}

Response

The recurring invoice created from the source invoice.

Example response

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08",
    "object": "recurring_invoice",
    "client": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
      "name": "Acme Corporation"
    },
    "series": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
      "code": "F-2026"
    },
    "status": "active",
    "frequency": "monthly",
    "name": "Cuota mantenimiento mensual Acme",
    "description": "Contrato de soporte y mantenimiento Plan Pro",
    "notes": "Renovación automática. Facturar el día 1 de cada mes.",
    "email_to": "facturacion@acme.example",
    "send_automatically": true,
    "generation_mode": "issue_and_send",
    "days_before_due": 30,
    "max_occurrences": 12,
    "occurrences_count": 3,
    "remaining_occurrences": 9,
    "holiday_handling": "next_business_day",
    "start_on": "2026-01-01",
    "end_on": "2026-12-31",
    "next_run_at": "2026-02-01T09:00:00Z",
    "last_run_at": "2026-01-01T09:00:00Z",
    "subtotal": "200.00",
    "taxes_total": "42.00",
    "total_vat": "42.00",
    "total_retention": "0.00",
    "total_surcharge": "0.00",
    "total": "242.00",
    "currency": "EUR",
    "lines": [
      {
        "object": "recurring_invoice_line",
        "description": "Cuota soporte mensual",
        "quantity": 1,
        "unit_price": "200.0000",
        "tax_rate": 21,
        "subtotal": "200.00",
        "taxes": "42.00",
        "total": "242.00",
        "counted_quantity": "4.0000",
        "configuration": {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c06",
          "name": "Soporte · Franja 24×7",
          "signature": "0d92b4e7136ca85f2e07b1c4a935d68e0f13c72a5b9d4086e315a7c2b940df63"
        },
        "options": [
          {
            "group": {
              "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c16",
              "name": "Cobertura"
            },
            "value": {
              "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c26",
              "name": "24×7"
            },
            "price_adjustment": "30.0000",
            "applied": true
          }
        ],
        "price_semantics": "per_commercial_unit",
        "price_adjustment_total": "30.0000"
      }
    ],
    "metadata": {
      "erp_code": "IVA-GEN",
      "ledger_account": "477000"
    },
    "external_id": "ERP-REC-2026-0008",
    "tags": [
      "suscripcion",
      "mantenimiento"
    ],
    "custom_fields": [
      {
        "field": "contrato",
        "value": "CTR-2026-0007"
      }
    ],
    "auto_delivery": {
      "send_automatically": true,
      "recipients": [
        "facturacion@acme.example"
      ],
      "cc": [
        "administracion@acme.example"
      ],
      "subject": "Tu factura mensual de Acme",
      "body": "Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."
    },
    "created_at": "2025-12-20T15:00:00Z",
    "updated_at": "2026-01-01T09:05:00Z"
  }
}

Changes

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